class PacketHeader

This is which buffer configuration lifetime this header is referring to.

See

`[fuchsia.mediacodec/StreamBufferPartialSettings.buffer_lifetime_ordinal]`.

For QueueInputPacket(), a server receiving a buffer_lifetime_ordinal

that isn't the current input buffer_lifetime_ordinal will close the

channel.

For output packets, this can be an old buffer_lifetime_ordinal only if

EnableOldOutputBuffers was sent by the client. See also RemoveBuffer to

determine when it's safe to stop tracking old output buffers (only

relevant to some video bitstream formats such as VP9, and only relevant

to decoders). Streams that want to emit old output buffers are rare

outside of bitstream format test streams.

This is which buffer configuration lifetime this header is referring to.

See

`[fuchsia.mediacodec/StreamBufferPartialSettings.buffer_lifetime_ordinal]`.

For QueueInputPacket(), a server receiving a buffer_lifetime_ordinal

that isn't the current input buffer_lifetime_ordinal will close the

channel.

For output packets, this can be an old buffer_lifetime_ordinal only if

EnableOldOutputBuffers was sent by the client. See also RemoveBuffer to

determine when it's safe to stop tracking old output buffers (only

relevant to some video bitstream formats such as VP9, and only relevant

to decoders). Streams that want to emit old output buffers are rare

outside of bitstream format test streams.

This is which buffer configuration lifetime this header is referring to.

See

`[fuchsia.mediacodec/StreamBufferPartialSettings.buffer_lifetime_ordinal]`.

For QueueInputPacket(), a server receiving a buffer_lifetime_ordinal

that isn't the current input buffer_lifetime_ordinal will close the

channel.

For output packets, this can be an old buffer_lifetime_ordinal only if

EnableOldOutputBuffers was sent by the client. See also RemoveBuffer to

determine when it's safe to stop tracking old output buffers (only

relevant to some video bitstream formats such as VP9, and only relevant

to decoders). Streams that want to emit old output buffers are rare

outside of bitstream format test streams.

When using `SetInputBufferPartialSettings` or

`SetOutputBufferPartialSettings` to allocate buffers, the valid range of

`packet_index` is from 0..buffer_count-1, where buffer_count is the

length of `[fuchsia.sysmem2/BufferCollectionInfo.buffers]`, considering

input and output separately.

When using `ParticipateInBufferAllocation` and `AddBuffer` to allocate

and add buffers, the valid range of `packet_index` is unconstrained (any

uint32 value). The client and server must still ensure that

`packet_index` values aren't re-used until the other end has indicated

the `packet_index` value is again available and can be re-used.

The number of concurrently in-flight `packet_index` values is limited

per port (input vs. output) and `buffer_lifetime_ordinal`. If a client

never puts the same input buffer in flight using more than one input

packet concurrently, this inherently ensures the client will conform to

this limit. Most clients can safely ignore this limit for output from

the server. The limit is as follows:

* When sending a packet, the sender must ensure that the number of

concurrently in-flight `packet_index` values under the port (input

or output) and `buffer_lifetime_ordinal` does not exceed the

high-water-mark number of buffers that have concurrently existed

from the server's point of view under the `buffer_lifetime_ordinal`

so far. When using `SetInputBufferPartialSettings`, this is

buffer_count as defined above.

* When using `AddBuffer`, the high-water-mark value is determined

slightly differently for input vs. output.

* For input, this high-water-mark value is the maximum value so far

under the `buffer_lifetime_ordinal` of the total number of

`AddBuffer` messages regarding the `buffer_lifetime_ordinal` minus

the total number of `RemoveBuffer` messages regarding the

`buffer_lifetime_ordinal`.

* If a client never puts an input buffer in flight more than once

concurrently using multiple different input `packet_index`

values, then the client will inherently stay under this limit

for input.

* For output, this high-water-mark value is the maximum so far under

the `buffer_lifetime_ordinal` of the total number of `AddBuffer`

messages regarding the `buffer_lifetime_ordinal` minus the total

number of completed buffer removals under the

`buffer_lifetime_ordinal`. This is without regard to which buffer

removals had a corresponding `RemoveBuffer` completion.

* If a client wishes to (optionally) validate this server

behavior, the client can rely on the server to not complete a

`RemoveBuffer` until after completion of buffer removal

server-side (else the server is failing to conform to

`RemoveBuffer` semantics or failing to conform to this limit).

For input, the client chooses an available `packet_index` value

arbitrarily when sending an input packet with `QueueInputPacket`, and

the client doesn't re-use the value until the server has sent

`OnFreeInputPacket` with that `packet_index` value.

For output, the server chooses an available `packet_index` value

arbitrarily (among all uint32 values) when sending an output packet with

`OnOutputPacket`, and doesn't re-use the value until the client has sent

`RecycleOutputPacket` with that `packet_index` value.

Available `packet_index` values can be queued in arbitrary order.

Both the client and server should validate the packet_index against the

known bound (if any; see above) and disconnect if it's out of bounds.

The packet_index values don't imply anything about order of use of

packets. The client should not expect the ordering to remain the same

over time - the stream processor is free to hold on to an input or

output packet for a while during which some other packet_index values

may be re-used multiple times.

For a given properly-functioning StreamProcessor instance, output

packet_index values will be unique among concurrently-outstanding

packets.

Servers should validate that a client isn't double-using a packet and

clients may similarly validate `packet_index` values from the server.

When using `SetInputBufferPartialSettings` or

`SetOutputBufferPartialSettings` to allocate buffers, the valid range of

`packet_index` is from 0..buffer_count-1, where buffer_count is the

length of `[fuchsia.sysmem2/BufferCollectionInfo.buffers]`, considering

input and output separately.

When using `ParticipateInBufferAllocation` and `AddBuffer` to allocate

and add buffers, the valid range of `packet_index` is unconstrained (any

uint32 value). The client and server must still ensure that

`packet_index` values aren't re-used until the other end has indicated

the `packet_index` value is again available and can be re-used.

The number of concurrently in-flight `packet_index` values is limited

per port (input vs. output) and `buffer_lifetime_ordinal`. If a client

never puts the same input buffer in flight using more than one input

packet concurrently, this inherently ensures the client will conform to

this limit. Most clients can safely ignore this limit for output from

the server. The limit is as follows:

* When sending a packet, the sender must ensure that the number of

concurrently in-flight `packet_index` values under the port (input

or output) and `buffer_lifetime_ordinal` does not exceed the

high-water-mark number of buffers that have concurrently existed

from the server's point of view under the `buffer_lifetime_ordinal`

so far. When using `SetInputBufferPartialSettings`, this is

buffer_count as defined above.

* When using `AddBuffer`, the high-water-mark value is determined

slightly differently for input vs. output.

* For input, this high-water-mark value is the maximum value so far

under the `buffer_lifetime_ordinal` of the total number of

`AddBuffer` messages regarding the `buffer_lifetime_ordinal` minus

the total number of `RemoveBuffer` messages regarding the

`buffer_lifetime_ordinal`.

* If a client never puts an input buffer in flight more than once

concurrently using multiple different input `packet_index`

values, then the client will inherently stay under this limit

for input.

* For output, this high-water-mark value is the maximum so far under

the `buffer_lifetime_ordinal` of the total number of `AddBuffer`

messages regarding the `buffer_lifetime_ordinal` minus the total

number of completed buffer removals under the

`buffer_lifetime_ordinal`. This is without regard to which buffer

removals had a corresponding `RemoveBuffer` completion.

* If a client wishes to (optionally) validate this server

behavior, the client can rely on the server to not complete a

`RemoveBuffer` until after completion of buffer removal

server-side (else the server is failing to conform to

`RemoveBuffer` semantics or failing to conform to this limit).

For input, the client chooses an available `packet_index` value

arbitrarily when sending an input packet with `QueueInputPacket`, and

the client doesn't re-use the value until the server has sent

`OnFreeInputPacket` with that `packet_index` value.

For output, the server chooses an available `packet_index` value

arbitrarily (among all uint32 values) when sending an output packet with

`OnOutputPacket`, and doesn't re-use the value until the client has sent

`RecycleOutputPacket` with that `packet_index` value.

Available `packet_index` values can be queued in arbitrary order.

Both the client and server should validate the packet_index against the

known bound (if any; see above) and disconnect if it's out of bounds.

The packet_index values don't imply anything about order of use of

packets. The client should not expect the ordering to remain the same

over time - the stream processor is free to hold on to an input or

output packet for a while during which some other packet_index values

may be re-used multiple times.

For a given properly-functioning StreamProcessor instance, output

packet_index values will be unique among concurrently-outstanding

packets.

Servers should validate that a client isn't double-using a packet and

clients may similarly validate `packet_index` values from the server.

When using `SetInputBufferPartialSettings` or

`SetOutputBufferPartialSettings` to allocate buffers, the valid range of

`packet_index` is from 0..buffer_count-1, where buffer_count is the

length of `[fuchsia.sysmem2/BufferCollectionInfo.buffers]`, considering

input and output separately.

When using `ParticipateInBufferAllocation` and `AddBuffer` to allocate

and add buffers, the valid range of `packet_index` is unconstrained (any

uint32 value). The client and server must still ensure that

`packet_index` values aren't re-used until the other end has indicated

the `packet_index` value is again available and can be re-used.

The number of concurrently in-flight `packet_index` values is limited

per port (input vs. output) and `buffer_lifetime_ordinal`. If a client

never puts the same input buffer in flight using more than one input

packet concurrently, this inherently ensures the client will conform to

this limit. Most clients can safely ignore this limit for output from

the server. The limit is as follows:

* When sending a packet, the sender must ensure that the number of

concurrently in-flight `packet_index` values under the port (input

or output) and `buffer_lifetime_ordinal` does not exceed the

high-water-mark number of buffers that have concurrently existed

from the server's point of view under the `buffer_lifetime_ordinal`

so far. When using `SetInputBufferPartialSettings`, this is

buffer_count as defined above.

* When using `AddBuffer`, the high-water-mark value is determined

slightly differently for input vs. output.

* For input, this high-water-mark value is the maximum value so far

under the `buffer_lifetime_ordinal` of the total number of

`AddBuffer` messages regarding the `buffer_lifetime_ordinal` minus

the total number of `RemoveBuffer` messages regarding the

`buffer_lifetime_ordinal`.

* If a client never puts an input buffer in flight more than once

concurrently using multiple different input `packet_index`

values, then the client will inherently stay under this limit

for input.

* For output, this high-water-mark value is the maximum so far under

the `buffer_lifetime_ordinal` of the total number of `AddBuffer`

messages regarding the `buffer_lifetime_ordinal` minus the total

number of completed buffer removals under the

`buffer_lifetime_ordinal`. This is without regard to which buffer

removals had a corresponding `RemoveBuffer` completion.

* If a client wishes to (optionally) validate this server

behavior, the client can rely on the server to not complete a

`RemoveBuffer` until after completion of buffer removal

server-side (else the server is failing to conform to

`RemoveBuffer` semantics or failing to conform to this limit).

For input, the client chooses an available `packet_index` value

arbitrarily when sending an input packet with `QueueInputPacket`, and

the client doesn't re-use the value until the server has sent

`OnFreeInputPacket` with that `packet_index` value.

For output, the server chooses an available `packet_index` value

arbitrarily (among all uint32 values) when sending an output packet with

`OnOutputPacket`, and doesn't re-use the value until the client has sent

`RecycleOutputPacket` with that `packet_index` value.

Available `packet_index` values can be queued in arbitrary order.

Both the client and server should validate the packet_index against the

known bound (if any; see above) and disconnect if it's out of bounds.

The packet_index values don't imply anything about order of use of

packets. The client should not expect the ordering to remain the same

over time - the stream processor is free to hold on to an input or

output packet for a while during which some other packet_index values

may be re-used multiple times.

For a given properly-functioning StreamProcessor instance, output

packet_index values will be unique among concurrently-outstanding

packets.

Servers should validate that a client isn't double-using a packet and

clients may similarly validate `packet_index` values from the server.