class RemoveBuffer

When using dynamic buffers, this call removes a buffer as soon as the

buffer can be removed without adversely impacting any ongoing processing

or an in-flight output packet referring to the buffer.

If a client wants to remove a buffer with an in-flight output packet

referring to the buffer, the client must RecycleOutputPacket for that

in-flight output packet before the RemoveBuffer will complete.

When using SetInputBufferPartialSettings /

SetOutputBufferPartialSettings, this call doesn't initiate removal of

the buffer. This call will complete when the buffer is done removing due

to other reasons, such as a new buffer_lifetime_ordinal starting.

Until RemoveBuffer completes, the codec is still allowed to send

OnOutputPacket messages referencing the buffer, and the codec may still

have a VMO handle open to the buffer. After RemoveBuffer completes, the

codec guarantees that no subsequent output packet will reference the

buffer, and that the server holds no VMO handles to the buffer.

The client may need to recycle an output packet before the RemoveBuffer

call can complete. Clients should take care to avoid blocking packet

recycling while the RemoveBuffer request is in progress, since this

would create a potential deadlock.

The server closing any VMO handles to the buffer prior to completing

this call is important for the client's ability to prevent memory usage

spikes.

If the client has "paused" processing by not providing any more input,

the client will potentially need to send CloseCurrentStream before

RemoveBuffer will complete. When using dynamic buffers, setting

release_input_buffers or release_output_buffers to true is not

necessary; the RemoveBuffer is explicitly telling the codec to release a

specific buffer. When not using dynamic buffers, the client will need to

set release_input_buffers or release_output_buffers to true, since

RemoveBuffer alone doesn't initiate removal when not using dynamic

buffers. A current "paused" stream needs to be stopped because frames

can be held as reference frames, and codecs are never reqiured to copy

their output data.

For any video decoder output buffers being removed while there's an

active stream (being fed input or not), it's typically best for the

client to assume that removal of a video decoder output buffer may take

a very long duration. This is because bitstreams, especially

non-standard-compliant bitstreams, but in some cases potentially even

standard-compliant bitstreams, can keep a video decoder output buffer in

the set of active reference frames (aka DPB) indefinitely. The server is

not required to notice that a stream is not conforming to a bitstream

standard in this regard.

In the case of h.264 decode, a standard-complient bitstream will limit

the reorder delay to no longer than the max DPB occupancy. However, a

server is not required to detect or reject non-compliant streams that

potentially keep a frame in the DPB for longer.

For HEVC, the situation is similar to h.264 (IIUC).

In the case of VP9, there is nothing in the bitstream spec that limits

the reorder delay (IIUC), meaning a frame can potentially stay in VP9's

set of 8 reference frames (aka DPB) indefinitely. The server is not

required to detect or mitigate this.

Until this call completes, the server may still be using the buffer. For

output buffers, the server can still send OnOutputPacket message(s) that

references this buffer, but only up until the RemoveBuffer completion

message is sent by the server. The client must continue to

RecycleOutputPacket for packets that reference the buffer, until

RemoveBuffer completes.

When using dynamic buffers, upon receiving this message, the server will

stop selecting the buffer for any new usage (as in, for any usage that

moves the buffer from "free" to "not free" within the server). This

applies even if the server has no other buffers available for use (aka

no other "free" buffers). Any existing usage of the buffer is not ended

early by this call alone.

When not using dynamic buffers, upon receiving this message, the server

will just remember to complete this call shortly after the buffer has

completed removal triggered by some other cause (removal is not

triggered/caused by this call).

For video decoders, when using dynamic buffers, typically the client

should take care to avoid removing too many output buffers for continued

decode to be possible. If this occurs, the decoder will wait until the

client adds another output buffer with AddBuffer. This can be a deadlock

if the client never sends that AddBuffer. Due to DPB mechanism(s) and

frame reordering, sending a single AddBuffer doesn't necessarily

guarantee another OnOutputPacket, since additional output buffers can be

needed before the server can send OnOutputPacket.

The client must not call RemoveBuffer on the same buffer more than once,

whether overlapping in time or not. The server should enforce this when

not enforcing would require tracking additional concurrent requests. The

server is not required to enforce this when enforcing would use more

server memory.

The server is allowed to complete this request quickly with success for

buffer_lifetime_ordinal and buffer_index combinations that were never

real buffers, but must close the channel if the buffer_lifetime_ordinal

hasn't been started by the client yet (no removing potential future

buffers).

When using dynamic buffers, a buffer_lifetime_ordinal and buffer_index

combination may be re-used after completion of RemoveBuffer, but only if

the buffer_lifetime_ordinal is the current buffer_lifetime_ordinal. In

other words, no adding buffers under an old buffer_lifetime_ordinal.

Assuming a valid historical buffer is specified, successful completion

of this call means the buffer has been fully released by the server and

won't be referenced in any subsequent OnOutputPacket.