Struct Packet

pub struct Packet {
    pub header: Option<PacketHeader>,
    pub buffer_index: Option<u32>,
    pub stream_lifetime_ordinal: Option<u64>,
    pub start_offset: Option<u32>,
    pub valid_length_bytes: Option<u32>,
    pub timestamp_ish: Option<u64>,
    pub start_access_unit: Option<bool>,
    pub known_end_access_unit: Option<bool>,
    pub key_frame: Option<bool>,
    /* private fields */
}

A Packet represents a chunk of input or output data to or from a stream processor.

stream processor output:

While the Packet is outstanding with the client via OnOutputPacket(), the stream processor will avoid modifying the referenced output data. After the client calls RecycleOutputPacket(packet_index), the stream processor is notified that the client is again ok with the referenced data changing.

stream processor input:

The client initially has all packet_index(es) available to fill, and later gets packet_index(s) that are again ready to fill via OnFreeInputPacket(). The client must not modify the referenced data in between QueueInputPacket() and OnFreeInputPacket().

Fields

header: Option<PacketHeader>

buffer_index: Option<u32>

Which buffer this packet refers to. For single-buffer mode this will always be 0, but for multi-buffer mode, a given in-flight interval of a packet can refer to any buffer. The packet has an associated buffer only while the packet is in-flight, not while the packet is free.

The default value makes accidental inappropriate use of index 0 less likely (will tend to complain in an obvious way if not filled out instead of a non-obvious data corruption when decoding buffer 0 repeatedly instead of the correct buffers).

TODO(dustingreen): Try to make FIDL table defaults have meaning, and not complain about !has when accessing the field. For now the default specified here does nothing.

stream_lifetime_ordinal: Option<u64>

The value 1 is the lowest permitted value after stream processor creation. Values sent by the client must be odd. Values must only increase.

A stream_lifetime_ordinal represents the lifetime of a stream. All messages that are specific to a stream have the stream_lifetime_ordinal value and the value is the same for all messages relating to a given stream.

start_offset: Option<u32>

Which part of the relevant buffer is this packet using. These are valid for input data that’s in-flight to the stream processor, and are valid for output data from the stream processor.

For compressed formats and uncompressed audio, the data in [start_offset, start_offset + valid_length_bytes) is the contiguously valid data referred to by this packet.

For uncompressed video frames, FormatDetails is the primary means of determining which bytes are relevant. The offsets in FormatDetails are relative to the start_offset here. The valid_length_bytes must be large enough to include the full last line of pixel data, including the full line stride of the last line (not just the width in pixels of the last line).

Despite these being filled out, some uncompressed video buffers are of types that are not readable by the CPU. These fields being here don’t imply there’s any way for the CPU to read an uncompressed frame.

valid_length_bytes: Option<u32>

This must be > 0.

The semantics for valid data per packet vary depending on data type as follows.

uncompressed video - A video frame can’t be split across packets. Each packet is one video frame.

uncompressed audio - Regardless of float or int, linear or uLaw, or number of channels, a packet must contain an non-negative number of complete audio frames, where a single audio frame consists of data for all the channels for the same single point in time. Any stream-processor-specific internal details re. lower rate sampling for LFE channel or the like should be hidden by the StreamProcessor server implementation.

compressed data input - A packet must contain at least one byte of data. See also stream_input_bytes_min. Splitting AUs at arbitrary byte boundaries is permitted, including at boundaries that are in AU headers.

compressed data output - The stream processor is not required to fully fill each output packet’s buffer.

timestamp_ish: Option<u64>

This value is not strictly speaking a timestamp. It is an arbitrary unsigned 64-bit number that, under some circumstances, will be passed by a stream processor unmodified from an input packet to the exactly-corresponding output packet.

For timestamp_ish values to be propagated from input to output the following conditions must be true:

• promise_separate_access_units_on_input must be true
• has_timestamp_ish must be true for a given input packet, to have that timestamp_ish value (potentially) propagate through to an output
• the StreamProcessor instance itself decides (async) that the input packet generates an output packet - if a given input never generates an output packet then the timestamp_ish value on the input will never show up on any output packet - depending on the characteristics of the input and output formats, and whether a decoder is willing to join mid-stream, etc this can be more or less likely to occur, but clients should be written to accommodate timestamp_ish values that are fed on input but never show up on output, at least to a reasonable degree (not crashing, not treating as an error).

start_access_unit: Option<bool>

If promise_separate_access_units_on_input (TODO(dustingreen): or any similar mode for output) is true, this bool must be set appropriately depending on whether byte 0 is or is not the start of an access unit. The client is required to know, and required to set this boolean properly. The server is allowed to infer that when this boolean is false, byte 0 is the first byte of a continuation of a previously-started AU. (The byte at start_offset is “byte 0”.)

If promise_separate_access_units_on_input is false, this boolean is ignored.

known_end_access_unit: Option<bool>

A client is never required to set this boolean to true.

If promise_separate_access_units_on_input is true, for input data, this boolean must be false if the last byte of this packet is not the last byte of an AU, and this boolean may be true if the last byte of this packet is the last byte of an AU. A client delivering one AU at a time that’s interested in the lowest possible latency via the decoder should set this boolean to true when it can be set to true.

If promise_separate_access_units_on_input is false, this boolean is ignored.

key_frame: Option<bool>

Used for compressed video packets. If not present should be assumed to be unknown. If false, indicates the packet is not part of a key frame. If true, indicates the packet is part of a key frame.

Trait Implementations

impl Clone for Packet

fn clone(&self) -> Packet

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Packet

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

Formats the value using the given formatter.

impl<D: ResourceDialect> Decode<Packet, D> for Packet

fn new_empty() -> Self

Creates a valid instance of Self. The specific value does not matter, since it will be overwritten by decode.

unsafe fn decode( &mut self, decoder: &mut Decoder<'_, D>, offset: usize, depth: Depth, ) -> Result<()>

Decodes an object of type T from the decoder’s buffers into self.

impl Default for Packet

fn default() -> Packet

Returns the “default value” for a type.

impl<D: ResourceDialect> Encode<Packet, D> for &Packet

unsafe fn encode( self, encoder: &mut Encoder<'_, D>, offset: usize, depth: Depth, ) -> Result<()>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID.

impl PartialEq for Packet

fn eq(&self, other: &Packet) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TypeMarker for Packet

type Owned = Packet

The owned Rust type which this FIDL type decodes into.

fn inline_align(_context: Context) -> usize

Returns the minimum required alignment of the inline portion of the encoded object. It must be a (nonzero) power of two.

fn inline_size(_context: Context) -> usize

Returns the size of the inline portion of the encoded object, including padding for alignment. Must be a multiple of inline_align.

fn encode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and encoding requires no validation. When true, we can optimize encoding arrays and vectors of Self::Owned to a single memcpy.

fn decode_is_copy() -> bool

Returns true if the memory layout of Self::Owned matches the FIDL wire format and decoding requires no validation. When true, we can optimize decoding arrays and vectors of Self::Owned to a single memcpy.

impl ValueTypeMarker for Packet

type Borrowed<'a> = &'a Packet

The Rust type to use for encoding. This is a particular Encode<Self> type cheaply obtainable from &Self::Owned. There are three cases:

fn borrow(value: &<Self as TypeMarker>::Owned) -> Self::Borrowed<'_>

Cheaply converts from &Self::Owned to Self::Borrowed.

impl Persistable for Packet

impl StructuralPartialEq for Packet