class StreamProcessor

Overview of operation:

1. Create

* create via CodecFactory - see CodecFactory

* create via LicenseSession - see LicenseSession

2. Get input constraints

* OnInputConstraints() - sent unsolicited by stream processor shortly after

stream processor creation.

3. Provide input buffers

* SetInputBufferPartialSettings()

4. Deliver input data

* QueueInputPacket() + OnFreeInputPacket(), for as long as it takes,

possibly working through all input packets repeatedly before...

5. Get output constraints and format

* OnOutputConstraints()

* This is not sent until after at least one QueueInput* message is sent by

the client, even if the underlying processor behind the StreamProcessor

doesn't fundamentally need any input data to determine its output

constraints. This server behavior prevents clients taking an incorrect

dependency on the output constraints showing up before input is

delivered.

* A client must tolerate this arriving as late as after substantial input

data has been delivered, including lots of input packet recycling via

OnFreeInputPacket().

* This message can arrive more than once before the first output data.

6. Provide output buffers

* SetOutputBufferPartialSettings() / CompleteOutputBufferPartialSettings()

7. Data flows, with optional EndOfStream

* OnOutputPacket() / RecycleOutputPacket() / QueueInputPacket() /

OnFreeInputPacket() / QueueInputEndOfStream() / OnOutputEndOfStream()

Semi-trusted StreamProcessor server - SW decoders run in an isolate (with

very few capabilities) just in case the decoding SW has a vulnerability

which could be used to take over the StreamProcessor server. Clients of the

stream processor interface using decoders and processing streams of separate

security contexts, to a greater extent than some other interfaces, need to

protect themselves against invalid server behavior, such as double-free of a

packet_index and any other invalid server behavior. Having fed in

compressed data of one security context, don't place too much trust in a

single StreamProcessor instance to not mix data among any buffers that

StreamProcessor server has ever been told about. Instead, create separate

StreamProcessor instances for use by security-separate client-side contexts.

While the picture for HW-based decoders looks somewhat different and is out

of scope of this paragraph, the client should always use separate

StreamProcessor instances for security-separate client-side contexts.

Descriptions of actions taken by methods of this protocol and the states of

things are given as if the methods are synchronously executed by the stream

processor server, but in reality, as is typical of FIDL interfaces, the

message processing is async. The states described are to be read as the

state from the client's point of view unless otherwise stated. Events

coming back from the server are of course delivered async, and a client that

processes more than one stream per StreamProcessor instance needs to care

whether a given event is from the current stream vs. some older

soon-to-be-gone stream.

The Sync() method's main purpose is to enable the client to robustly prevent

having both old and new buffers allocated in the system at the same time,

since media buffers can be significantly large, depending. The Sync() method

achieves this by only delivering it's response when all previous calls to

the StreamProcessor protocol have actually taken effect in the

StreamControl ordering domain. Sync() can also be used to wait for the

stream processor server to catch up if there's a possibility that a client

might otherwise get too far ahead of the StreamProcessor server, by for

example requesting creation of a large number of streams in a row. It can

also be used during debugging to ensure that a stream processor server

hasn't gotten stuck. Calling Sync() is entirely optional and never required

for correctness - only potentially required to de-overlap resource usage.

It's possible to re-use a StreamProcessor instance for another stream, and

doing so can sometimes skip over re-allocation of buffers. This can be a

useful thing to do for cases like seeking to a new location - at the

StreamProcessor interface that can look like switching to a new stream.