Struct rav1e::Context

pub struct Context<T: Pixel> { /* fields omitted */ }

The encoder context.

Contains the encoding state.

Implementations

impl<T: Pixel> Context<T>

pub fn new_frame(&self) -> Frame<T>

Allocates and returns a new frame.

Examples

use rav1e::prelude::*;

let cfg = Config::default();
let ctx: Context<u8> = cfg.new_context()?;
let frame = ctx.new_frame();

pub fn send_frame<F>(&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.

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::*;

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,
};

// 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)?;

pub fn twopass_out(&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.

pub fn twopass_bytes_needed(&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.

pub fn twopass_in(&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.

pub fn receive_packet(&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.

Examples

Encoding a single frame:

use rav1e::prelude::*;

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)?,
    }
}

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(())
}

pub fn flush(&mut self)

Flushes the encoder.

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

pub fn container_sequence_header(&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.

impl<T: Pixel> Context<T>

pub fn rc_summary_size(&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.

pub fn rc_receive_pass_data(&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.

pub fn rc_second_pass_data_required(&self) -> usize

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

It should be called iteratively until it returns 0.

pub fn rc_send_pass_data(&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()

It may return EncoderStatus::Failure if the data provided is incorrect

Trait Implementations

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

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

Formats the value using the given formatter.