class AddBuffer

Add buffers previously created with the help of

ParticipateInBufferAllocation.

For input buffers, the client can send QueueInputFormatDetails or

QueueInputEndOfStream before any AddBuffer messages. At least one input

buffer must be added before a valid QueueInputPacket can be sent. Most

clients will want to continue quickly adding buffers up to at least

buffer_count_for_server_current to avoid the codec potentially stalling,

and typically a low number of buffers beyond that to keep the pipeline

running smoothly. Input buffers beyond the first input buffer can be

added after the first QueueInputPacket.

Even if buffer_constraints_version_ordinal is current, the server must

not close the channel if the buffer isn't consistent with the current

buffer_constraints_version_ordinal (per sysmem GetVmoInfo given

consistent StreamProcessor constraints). Instead, the server must send a

new OnOutputConstraints. This simplifies some edge cases for some

clients, particularly when a client can't reliably detect whether a

newly-obtained buffer was actually allocated after

buffer_constraints_version_ordinal changed, or may have been cached from

before.

The client can add additional buffers to the same port and

buffer_lifetime_ordinal at any time using this message. If the

buffer_lifetime_ordinal is no longer the most recent, the message will

be ignored, the handle to the buffer dropped, and any later RemoveBuffer

message re. the same buffer will complete immediately.

If dynamic_buffers_input_max or dynamic_buffers_output_max is exceeded

by the sum of buffers added by all AddBuffer calls with the same

buffer_lifetime_ordinal, the server may close the channel. Servers are

required to close the channel in this case if performance degradation or

un-tested behavior would result from adding too many buffers.

Switching to a new buffer_lifetime_ordinal starts the process of

removing buffers associated with an old buffer_lifetime_ordinal.

However, until the remove is complete, those buffers can still be used

by the codec as normal. See also RemoveBuffer, which can be used to

detect when removal is complete, regardless of whether the RemoveBuffer

started the removal (including when not using dynamic buffers).

The buffer stays added until removal later completes. The buffer remains

added across potentially multiple buffer re-uses. Removal can be

initiated (and/or confirmed/fenced) by the client using RemoveBuffer.

The codec server can unilaterally initiate buffer removal; if the server

does this, it must send a new buffer_constraints_version_ordinal with

action_required true. Some other client-initiated messages can also

begin buffer removal, such as CloseCurrentStream with

release_input_buffers and/or release_output_buffers. The buffers are

also automatically removed and released if the client closes the

StreamProcessor client_end or the server closes the StreamProcessor

server_end.

Mixing of AddBuffer and SetInputBufferPartialSettings /

SetOutputBufferPartialSettings is not allowed while there are any

buffers still active on the port. To successfully switch modes for a

port, most clients will want to just start over with a new

StreamProcessor instance. This can also be done reliably by first

ensuring that every added buffer under the port up to "now" (including

those with older buffer_lifetime_ordinal) has completed a RemoveBuffer

request. Only then is it known ok to switch modes for that port under

the same StreamProcessor. Most clients will just use one way or the

other to add buffers and never need to switch to the other way,

especially within the same StreamProcessor.

If a client might plausibly "spam" creation of many new

buffer_lifetime_ordinal values without the buffers seeing any actual

usage in between, the client should consider starting a Sync every few

buffer_lifetime_ordinal(s) to fence cleanup of old

buffer_lifetime_ordinal values, and avoid getting ahead of Sync

completions by more than 16 buffer_lifetime_ordinal values. Else the

channel may close from a backlog of new buffer_lifetime_ordinal(s)

getting too far ahead of closing out old ones. The threshold of 16 is

well below the enforcement threshold. Clients don't need to Sync if they

won't be spamming new buffer_lifetime_ordinal values, or if added

buffers will see at least some actual usage visible to the client before

being replaced again.

All buffers of the same port and buffer_lifetime_ordinal must share the

same `[fuchsia.sysmem2/SingleBufferSetttings]`. The client can ensure

this in various ways. One way is to use ParticipateInBufferAllocation

then AddBuffer for at least the first buffer, before

ParticipateInBufferAllocation for any subsequent buffers. Another way is

to observe a mismatch in `SingleBufferSettings` before sending AddBuffer

and bump to the next odd buffer_lifetime_ordinal value for the

AddBuffer.