class OnOutputFormat

This message is sent by the server before the first output packet of any

stream, and potentially mid-stream between output packets of the stream,

ordered with respect to output packets, and ordered with respect to

OnOutputConstraints().

The server guarantees that the first packet of every stream will be

preceeded by an OnOutputFormat().

The server guarantees that there will be an OnOutputFormat() between an

OnOutputConstraints() with buffer_constraints_action_required true and an

OnOutputPacket(). In other words, the client is essentially allowed to

forget what the output format is on any OnOutputConstraints() with

buffer_constraints_action_required true, because the server promises a

subsequent OnOutputFormat() before any OnOutputPacket().

If the server sets buffer_constraints_action_required true in

OnOutputConstraints(), the server won't send OnOutputFormat() (and

therefore also won't send OnOutputPacket()) until the client has

re-configured output buffers.

The server is allowed to send an OnOutputFormat() mid-stream between two

output packets.

A server won't send two adjacent OnOutputFormat() messages without any

output packet in between. However an OnOutputFormat() message doesn't

guarantee a subsequent packet, because for example the server could send

OnOutputEndOfStream() or OnStreamFailed() instead.

A client that does not wish to seamlessly handle mid-stream output format

changes should either ensure that no stream processed by the client

ever has any mid-stream format change, or the client should ensure that

any retry of processing starts the new attempt at a point logically at or

after the point where the old format has ended and the new format starts,

else the client could just hit the same mid-stream format change again.

An example of this message being sent mid-stream is mid-stream change

of dimensions of video frames output from a video decoder.

Not all servers will support seamless handling of format change. Those

that do support seamless handling of format change may require that the

format change not also require output buffer re-config, in order for the

handling to be seamless. See the comment block for OnOutputConstraints()

for more discussion of how servers and clients should behave - in

particular when they don't seamlessly handle output constraint change

and/or output format change.

If this message isn't being sent by the server when expected at the

start of a stream, the most common reason is that a OnOutputConstraints()

with buffer_constraints_action_required true hasn't been processed by the

client (by configuring output buffers using

SetOutputBufferPartialSettings() etc).