class CodecFactory

A client should call |GetDetailedCodecDescriptions()| to get a list of

codecs supported either by software implementations or by underlying hardware.

CreateDecoder:

decoder_params - See CreateDecoder_Params comments for required

and optional parameters for creating a decoder.

decoder - a Codec.NewRequest() which will hopefully be connected to

a Codec server, or the Codec channel will get closed if no suitable

codec can be found. We don't return any additional Codec-specific

status here because finding the Codec is allowed to be fully async, so

we don't necessarily yet know on return from this method which Codec

will be selected, if any.

Rough sequence to create a decoder:

factory = ConnectToEnvironmentService(CodecFactory);

CreateDecoder_Params params;

[fill out params]

CreateDecoder(params, decoder_request);

See use_media_decoder code for more detail.

CreateEncoder:

encoder_params - See CreateEncoder_Params comments for required

and optional parameters for creating a decoder.

encoder - a Codec.NewRequest() which will hopefully be connected to

a Codec server, or the Codec channel will get closed if no suitable

codec can be found. We don't return any additional Codec-specific

status here because finding the Codec is allowed to be fully async, so

we don't necessarily yet know on return from this method which Codec

will be selected, if any.

AttachLifetimeTracking:

Attach an eventpair endpoint to the next Create{X}(), so that the

codec_end will be closed when the number of buffers allocated reaches

'buffers_remaining'. Multiple eventpair endpoints can be attached per

create, with an enforced limit of

CODEC_FACTORY_LIFETIME_TRACKING_EVENTPAIR_PER_CREATE_MAX.

The lifetime signalled by this event is intended to track all resources

used by the codec, including sysmem-allocated buffers created internally

by the codec. The sysmem buffer collections visible to the client, for

input and output buffers, are not included in the resources tracked

here, because those can be tracked separately via

fuchsia.sysmem.BufferCollection.AttachLifetimeTracking(). It is

permitted to send a duplicate of codec_end to both this

AttachLifetimeTracking() and also to

fuchsia.sysmem.BufferCollection.AttachLifetimeTracking().

The ZX_EVENTPAIR_PEER_CLOSED will happen when both/all lifetimes are

fully over. This conveniently avoids needing multiple separate async

waits by the client.

In the case of server process crashes, or failure of a codec to plumb

codec_end to sysmem, ZX_EVENTPAIR_PEER_CLOSED signalled on the peer of

codec_end may occur shortly before all resources are freed.

A maximum of CODEC_FACTORY_LIFETIME_TRACKING_EVENTPAIR_PER_CREATE_MAX

calls to AttachLifetimeTracking() are allowed

before any Create{X}(). There is no way to cancel an attach short of

closing the CodecFactory channel. Closing the client end of the

eventpair doesn't subtract from the number of pending attach(es). For

this reason, it can be good to only send attach message(s) immediately

before the relevant Create{X}(), when it's known by the client that both

the attach message(s) and the Create{X}() messages will be sent.

Closing the client's end doesn't result in any action by the server.

If the server listens to events from the client end at all, it is for

debug logging only.

The server intentionally doesn't "trust" any bits signalled by the

client. This mechanism intentionally uses only ZX_EVENTPAIR_PEER_CLOSED

which can't be triggered early, and is only triggered when all handles

to codec_end are closed. No meaning is associated with any of the other

signal bits, and clients should functionally ignore any other signal

bits on either end of the eventpair or its peer.

The codec_end may lack ZX_RIGHT_SIGNAL or ZX_RIGHT_SIGNAL_PEER, but must

have ZX_RIGHT_DUPLICATE (and must have ZX_RIGHT_TRANSFER to transfer

without causing CodecFactory channel failure).