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. A given in-flight interval of a packet refers to a specfic buffer using buffer_lifetime_ordinal (in PacketHeader) and buffer_index.

A client should be prepared to handle output packets that refer to a buffer_lifetime_ordinal that’s old (with buffer_index scoped to the old buffer_lifetime_ordinal). Streams that do this are not common (in this author’s experience so far). Some clients may prefer to just ignore output packets with an old buffer_lifetime_ordinal, or notice the old buffer_lifetime_ordinal and fail the stream client-side. Clients that do want to fully handle such streams (for bitstream formats that can do this in the first place) can use RemoveBuffer completion to detect when each buffer of an old buffer_lifetime_ordinal will never again be referenced in any subsequent output packet. If the dimensions of the frame in the old buffer are different than the previous output frame, OnOutputFormat will be sent in between the output packets (as usual).

A client should be prepared to handle (as in “not crash when”) two or more output packets reference the same buffer, without the first output packet having been recycled back to the StreamProcessor yet. There is intentionally no guarantee that packets in-flight with the client will all refer to unique buffers, at least due to VP9 show_existing_frame, and possibly similar coding tools in other bitstream formats. Some layers above the direct client may not support this, in which case failing the stream client-side may be acceptable if the client has no need to support decode of streams that do this. More sophisticated translation strategies in this situation are outside the scope of this documentation. Clients intending to handle DRM-protected streams should keep in mind that copying frame contents with the CPU is likely not possible. To be clear, this author has never seen a DRM-protected stream that does this, and the only non-DRM-protected streams that this author has seen do this are test streams. Still, client authors should be aware that streams “in the wild” can potentially do this.

RemoveBuffer is supported both when using dynamic buffers, and when not using dynamic buffers. When using RemoveBuffer with non-dynamic buffers, there is no AddBuffer involved or required, as SetInputBufferPartialSettings or SetOutputBufferPartialSettings was used to add all the buffers of the buffer_lifetime_ordinal. In the case of non-dynamic buffers however, the RemoveBuffer won’t actaully start the removal of a buffer. But it will complete when the buffer is fully done removing.

The packet has an associated buffer_lifetime_ordinal and buffer_index only while the packet is in-flight, not while the packet is free.

When not using dynamic buffers, this value is the same as the sysmem buffer_index.

When using dynamic buffers, this value is not the same as the sysmem buffer_index (other than by chance), nor is it guaranteed to be a small number.

By default, for output buffers, this buffer_index value is guaranteed to be unique among buffers with the same buffer_lifetime_ordinal currently in-flight with the client. For decoding bitstream formats that can output the same buffer backing different output packets where the multiple packets are in the output queue at the same time (possibly with different timestamp_ish values), a client can send EnableSameOutputBufferConcurrentlyInFlight to indicate that the client is prepared to handle more than one output packet concurrently in flight referencing the same output buffer. Streams where this makes any difference are rare outside of bitstream format tests.

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 packet
• 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 this packet does not contain the last byte of the up to one AU contained or partially contained in this packet, and this boolean may be true if the last byte of the up-to-one AU is in this packet. 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.

Some bitstream formats have the concept of an access unit delimiter or similar. A client wishing to achieve low latency may choose to inject correctly-formed access unit delimiters (or similar) after each access unit as an alternate way to signal to a decoder that the access unit has ended. However, such a client is encouraged to also set this field to true when possible, to ensure that all layers of a decoder notice. Injecting an access unit delimiter is allowed but unnecessary (for latency reduction purposes) if this is set to true (for a properly-functioning decoder). A client never needs to strip away any access unit delimiters that are potentially already present in the stream - there is no requirement that the setting of this field match the existence/non-existence of any access unit delimiter(s).

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 duplicate 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<(), Error>

Formats the value using the given formatter.

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

where D: ResourceDialect,

fn new_empty() -> Packet

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<(), Error>

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> Encode<Packet, D> for &Packet

where D: ResourceDialect,

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

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: &<Packet as TypeMarker>::Owned, ) -> <Packet as ValueTypeMarker>::Borrowed<'_>

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

impl Persistable for Packet

impl StructuralPartialEq for Packet