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() and an OnOutputPacket(). In other words, the

client is essentially allowed to forget what the output format is on any

OnOutputConstraints(), because the server promises a subsequent

OnOutputFormat() before any OnOutputPacket().

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, or the client can move on

to a new stream and the server may not send a packet from the old stream

despite having sent OnOutputFormat.

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() hasn't been processed by the client (by

configuring output buffers using SetOutputBufferPartialSettings or

AddBuffer).