class Packet

Returns whether no field is set.

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.

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.

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.

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).

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.

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).

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).

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.

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.

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.

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.

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.

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.

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.

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).

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.