struct CoreCodecGetBufferCollectionConstraints3Result

All codecs must implement this (or deprecated

CoreCodecGetBufferCollectionConstraints2) for both ports. The returned

structure will be sent to sysmem in a SetConstraints() call. This method

can be called on the FIDL thread or the StreamControl domain (thread for

now).

For codecs with DetailedCodecDescription.supports_dynamic_buffers true,

this call is also used for ParticipateInBufferAllocation. There is

intentionally no mechanism for the CodecAdapter sub-class to detect whether

this call is driven by non-dynamic buffer allocation or dynamic buffer

allocation. The CodecAdapter should always set buffer count fields assuming

non-dynamic buffer allocation. For example, min_buffer_count_for_camping

should be set assuming non-dynamic buffer allocation. The caller

(CodecImpl) will fix up the buffer count fields to ensure that dynamic

buffer allocation isn't forced to allocate more buffers than the

StreamProcessor client is indicating.

Input:

For now, a core codec has no way to trigger being asked for new input

constraints, so the input constraints (for now) need to be generally

applicable to any potential setting/property of the input.

A decoder should permit a fairly wide range of buffer space, without

worrying whether the min is enough to efficiently handle a high bitrate.

The CodecImpl will own bumping up the min based on approximate bitrate

provided in the initial decoder creation parameters and/or per-stream input

format details (this logic is shared because it can reasonably be shared).

A core codec that has special requirements for extra input buffer space

given a particular bitrate can take it upon itself to set the input min

buffer space, but the idea is that typically it won't be necessary for a

decoder to increase the min based on input bitrate beyond what CodecImpl

does, so needing to do this should be fairly rare.

A video encoder which needs to vary it's input BufferCollectionConstraints

based on encoder settings can do so, using the data provided to

CoreCodecInit(). If later use of QueueInputFormatDetails() (per-stream)

results in an input packet that conforms to the old

BufferCollectionConstraints but does not conform to the effective new

BufferCollectionConstraints, the core codec can use

CodecAdapterEvents::onCoreCodecFailCodec() (the core codec should fail the

codec instance in this case rather than attempt to handle input data that

is outside the bounds that would have been indicated by the core codec had

the current input format details been used as the initial format details).

Clients that change the input format details on the fly should be willing

to re-request a new codec instance at least once starting with the new

input format details via the CodecFactory. This is true for additional

reasons beyond this paragraph involving the possibility of accelerated but

partial codec implementations. If a client needs to change input format

details but doesn't want to concern itself with tracking whether the

current codec was created with the current input format details, a client

can instead choose to always create a new codec via CodecFactory on any

change to the input format details.

Output:

A CodecAdapter can trigger this method to get called again by indicating an

output format detection/change with action_required true via

CoreCodecEvents::onCoreCodecMidStreamOutputConstraintsChange().

Filling out the usage bits is optional. If the usage bits are not filled

out (all still 0), the caller will fill them out based on

IsCoreCodecMappedBufferUseful() and IsCoreCodecHwBased(). The core codec

must either leave usage set to all 0, or completely fill them out.

The CodecAdapter must not set must_match_vmo (at least for now). The intent

of this rule is to avoid the CodecAdapter unnecessarily constraining new

buffers of a new buffer_lifetime_ordinal to have the same

SingleBufferSettings as buffers of a previous buffer_lifetime_ordinal.

All buffers of a given buffer_lifetime_ordinal are are guaranteed to have

the same sysmem SingleBufferSettings. This is enforced by CodecImpl.

For decoder output, if a stream is active, the CodecAdapter needs to make

sure that the constraints are set such that the stream can continue

decoding correctly given buffers that conform to the returned constraints.

This may imply tighter constraints than would be returned if a stream

weren't active. There is no requirement that a video decoder be able to

handle switching PixelFormatAndModifier mid-stream, but if a CodecAdapter

doesn't prevent that using the constraints here, that can happen, and then

the CodecAdapter is expected to correctly handle it without dropping any

output frames specified by the bitstream.

If an uncompressed video port is listing more than one

PixelFormatAndModifier, and has at least one linear pixel_format_modifier,

the most widely compatible pixel_format and pixel_format_modifier should be

at index 0 under image_format_constraints. The index 0 PixelFormat will be

sent to the StreamProcessor client in StreamBufferConstraints.pixel_format.

See doc comments on that field for more.

CodecImpl will try this method before falling back to

CoreCodecGetBufferCollectionConstraints2 if !result.has_value().

CodecAdapter(s) with IsSupportsDynamicBuffers() true must override this

method and CoreCodecGetConstraintsVersion, and must not return

std::nullopt.