Struct rav1e::prelude::context::Context

source ·

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

Expand description

The encoder context.

Contains the encoding state.

Implementations§

source §

impl<T: Pixel> Context<T>

source

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

source

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.

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

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

source

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.

source

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.

source

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.

§Errors

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

source

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.

§Errors

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

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

source

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.

§Panics

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

source

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.