impl<T: Pixel> Context<T>

fn rc_summary_size(self: &Self) -> usize

Return the Rate Control Summary Packet size

It is useful mainly to preserve space when saving both Rate Control Summary and Frame Packets in a single file.

fn rc_receive_pass_data(self: &mut Self) -> Option<RcData>

Return the first pass data

Call it after receive_packet, it returns a packet or the encoder lifecycle statuses EncoderStatus::Encoded and EncoderStatus::LimitReached.

It will return a RcData::Summary once the encoder is flushed.

fn rc_second_pass_data_required(self: &Self) -> usize

Lower bound number of pass data packets required to progress the encoding process.

It should be called iteratively until it returns 0.

fn rc_send_pass_data(self: &mut Self, data: &[u8]) -> Result<(), EncoderStatus>

Feed the first pass Rate Control data to the encoder, Frame-specific Packets only.

Call it before receive_packet()

Errors

Returns EncoderStatus::Failure if the data provided is incorrect

impl<T: Pixel> Context<T>

fn new_frame(self: &Self) -> Frame<T>

Allocates and returns a new frame.

Examples

use rav1e::prelude::*;

# fn main() -> Result<(), InvalidConfig> {
let cfg = Config::default();
let ctx: Context<u8> = cfg.new_context()?;
let frame = ctx.new_frame();
# Ok(())
# }

fn send_frame<F>(self: &mut Self, frame: F) -> Result<(), EncoderStatus>
where
    F: IntoFrame<T>

Sends the frame for encoding.

This method adds the frame into the frame queue and runs the first passes of the look-ahead computation.

Passing None is equivalent to calling flush.

The caller is responsible for padding the invisible portion of the frame, if multiple references to the frame are held. Calling [Plane::pad()] after filling each plane or equivalent is required.

Errors

If this method is called with a frame after the encoder has been flushed or the encoder internal limit is hit (std::i32::MAX frames) the EncoderStatus::EnoughData error is returned.

Examples

use rav1e::prelude::*;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
# if false {
let cfg = Config::default();
let mut ctx: Context<u8> = cfg.new_context().unwrap();
let f1 = ctx.new_frame();
let f2 = f1.clone();
let info = FrameParameters {
  frame_type_override: FrameTypeOverride::Key,
  opaque: None,
  ..Default::default()
};

// Send the plain frame data
ctx.send_frame(f1)?;
// Send the data and the per-frame parameters
// In this case the frame is forced to be a keyframe.
ctx.send_frame((f2, info))?;
// Flush the encoder, it is equivalent to a call to `flush()`
ctx.send_frame(None)?;
# }
# Ok(())
# }

fn twopass_out(self: &mut Self) -> Option<&[u8]>

Returns the first-pass data of a two-pass encode for the frame that was just encoded.

This should be called BEFORE every call to receive_packet (including the very first one), even if no packet was produced by the last call to receive_packet, if any (i.e., EncoderStatus::Encoded was returned). It needs to be called once more after EncoderStatus::LimitReached is returned, to retrieve the header that should be written to the front of the stats file (overwriting the placeholder header that was emitted at the start of encoding).

It is still safe to call this function when receive_packet returns any other error. It will return None instead of returning a duplicate copy of the previous frame's data.

fn twopass_bytes_needed(self: &mut Self) -> usize

Returns the number of bytes of the stats file needed before the next frame of the second pass in a two-pass encode can be encoded.

This is a lower bound (more might be required), but if 0 is returned, then encoding can proceed. This is just a hint to the application, and does not need to be called for encoding the second pass to work, so long as the application continues to provide more data to twopass_in in a loop until twopass_in returns 0.

fn twopass_in(self: &mut Self, buf: &[u8]) -> Result<usize, EncoderStatus>

Provides the stats data produced in the first pass of a two-pass encode to the second pass.

On success this returns the number of bytes of the data which were consumed. When encoding the second pass of a two-pass encode, this should be called repeatedly in a loop before every call to receive_packet (including the very first one) until no bytes are consumed, or until twopass_bytes_needed returns 0.

Errors

Returns Err(EncoderStatus::Failure) if the two-pass data is invalid.

fn receive_packet(self: &mut Self) -> Result<Packet<T>, EncoderStatus>

Encodes the next frame and returns the encoded data.

This method is where the main encoding work is done.

Errors

May return Err(EncoderStatus), which should be handled by the caller.

Examples

Encoding a single frame:

use rav1e::prelude::*;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
# if false {
let cfg = Config::default();
let mut ctx: Context<u8> = cfg.new_context()?;
let frame = ctx.new_frame();

ctx.send_frame(frame)?;
ctx.flush();

loop {
    match ctx.receive_packet() {
        Ok(packet) => { /* Mux the packet. */ },
        Err(EncoderStatus::Encoded) => (),
        Err(EncoderStatus::LimitReached) => break,
        Err(err) => Err(err)?,
    }
}
# }
# Ok(())
# }

Encoding a sequence of frames:

use std::sync::Arc;
use rav1e::prelude::*;

fn encode_frames(
    ctx: &mut Context<u8>,
    mut frames: impl Iterator<Item=Frame<u8>>
) -> Result<(), EncoderStatus> {
    // This is a slightly contrived example, intended to showcase the
    // various statuses that can be returned from receive_packet().
    // Assume that, for example, there are a lot of frames in the
    // iterator, which are produced lazily, so you don't want to send
    // them all in at once as to not exhaust the memory.
    loop {
        match ctx.receive_packet() {
            Ok(packet) => { /* Mux the packet. */ },
            Err(EncoderStatus::Encoded) => {
                // A frame was encoded without emitting a packet. This is
                // normal, just proceed as usual.
            },
            Err(EncoderStatus::LimitReached) => {
                // All frames have been encoded. Time to break out of the
                // loop.
                break;
            },
            Err(EncoderStatus::NeedMoreData) => {
                // The encoder has requested additional frames. Push the
                // next frame in, or flush the encoder if there are no
                // frames left (on None).
                ctx.send_frame(frames.next().map(Arc::new))?;
            },
            Err(EncoderStatus::EnoughData) => {
                // Since we aren't trying to push frames after flushing,
                // this should never happen in this example.
                unreachable!();
            },
            Err(EncoderStatus::NotReady) => {
                // We're not doing two-pass encoding, so this can never
                // occur.
                unreachable!();
            },
            Err(EncoderStatus::Failure) => {
                return Err(EncoderStatus::Failure);
            },
        }
    }

    Ok(())
}
# fn main() -> Result<(), Box<dyn std::error::Error>> {
#   if false {
#     let mut enc = EncoderConfig::default();
#     // So it runs faster.
#     enc.width = 16;
#     enc.height = 16;
#     let cfg = Config::new().with_encoder_config(enc);
#     let mut ctx: Context<u8> = cfg.new_context()?;
#
#     let frames = vec![ctx.new_frame(); 4].into_iter();
#     encode_frames(&mut ctx, frames);
#   }
#   Ok(())
# }

fn flush(self: &mut Self)

Flushes the encoder.

Flushing signals the end of the video. After the encoder has been flushed, no additional frames are accepted.

Panics

Panics if send_frame returns an Err. This should never happen when calling it with None and indicates a development error.

fn container_sequence_header(self: &Self) -> Vec<u8>

Produces a sequence header matching the current encoding context.

Its format is compatible with the AV1 Matroska and ISOBMFF specification. Note that the returned header does not include any config OBUs which are required for some uses. See the specification.

Panics

Panics if the header cannot be written in memory. This is unrecoverable, and usually indicates the system is out of memory.

impl<T> Any for Context<T>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Context<T>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Context<T>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> Freeze for Context<T>

impl<T> From for Context<T>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> RefUnwindSafe for Context<T>

impl<T> Send for Context<T>

impl<T> Sync for Context<T>

impl<T> Unpin for Context<T>

impl<T> UnsafeUnpin for Context<T>

impl<T> UnwindSafe for Context<T>

impl<T, U> Into for Context<T>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Context<T>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Context<T>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

impl<T: Pixel> Debug for Context<T>

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result<(), Error>