class ParticipateInBufferAllocation

This message results in channel closure unless supports_dynamic_buffers

is set to true.

This participates in allocation of buffers to be used with AddBuffer

later. The client can get VMO handles for these buffers by also

participating in the sysmem allocation, using the client's own related

sysmem token (associated with the same logical buffer collection). It's

up to the client to separately set any constraints needed by the client

using the client's own related sysmem token, if any.

Some clients may prefer to use SetInputBufferPartialSettings and/or

SetOutputBufferPartialSettings. Servers must support those messages.

In handling this message, if `allow_single_buffer` is set to true, the

server must not constrain the number of buffers allocated. The server

must set min_buffer_count to 1, and must leave max_buffer_count un-set

or set it to 0xFFFFFFFF, and must leave all min_buffer_count_* fields

un-set. The sender can set min_buffer_count and max_buffer_count to the

same value if the intent is to allocate exactly that many buffers. If

`allow_single_buffer` is un-set or set to false, the server will

indicate needed buffer counts to sysmem.

The server's BufferCollection channel (created from the passed-in

sysmem2_token) may see ZX_CHANNEL_PEER_CLOSED at any time, but in

particular, the server shouldn't expect the BufferCollection channel to

remain connected to sysmem beyond the server sending SetConstraints. For

this reason, the server may not be able to call

WaitForAllBuffersAllocated or similar, so the server should just send

SetConstraints, Close, then close the server's BufferCollection

client_end. This means the server in general shouldn't attempt to get

VMO handles for these buffers while processing this message.

The server should not assume that these buffers will necessarily ever be

added with AddBuffer to this StreamProcessor instance or any other

StreamProcessor instance (owned by the server or not). These buffers may

instead be dropped, or as a less-common example, possibly added to a

different codec served by a different server implementation which also

participated in the same sysmem buffer collection allocation.

For input buffers, AddBuffer of the allocated buffer(s) to a different

StreamProcessor instance of the same codec (same per CodecFactory) is

likely to work, but using the same StreamProcessor instance is

recommended when feasible.

In contrast, for output buffers, AddBuffer of the allocated buffer(s) to

a different StreamProcessor instance of the same codec (same per

CodecFactory) can't (within reason) be made work in general, especially

for video decoders. Therefore, for output buffers, the same

StreamProcessor instance must be used for this message and AddBuffer.

While a client may currently be able to get away with using different

StreamProcessor instances for this message and AddBuffer for output

buffers for some codecs, this may break at any time without it being

considered a server-side bug.

The allocated buffers can later be added using AddBuffer (piecemeal),

and can be removed (piecemeal) using RemoveBuffer.

Multiple different ParticipateInBufferAllocation messages can have their

buffers later added to the same StreamProcessor instance using the same

buffer_lifetime_ordinal. This can be useful if the client wants to

allocate buffers incrementally, or dynamically adjust the number of

buffers, potentially while actively processing. See also the

`buffer_lifetime_ordinal` field of this message.

Server implementations may use sysmem to help verify buffer

compatibility later when buffers are added with AddBuffer.