| Microsoft DirectX 8.1 (C++) |
A media type is a description of the format associated with a stream of media data. This article describes how Microsoft DirectX Media Objects (DMOs) handle media types. It is primarily intended for developers who are writing their own custom DMOs. For applications that use DMOs, see Using DirectX Media Objects.
Three main pieces of information describe a media type:
For more information, refer to the DMO_MEDIA_TYPE structure.
When an application first creates an instance of a DMO, the streams in the DMO have no particular media type. Before the application can use the DMO to process data, it must specify media types for all the streams. (Optional streams are an exception; see Discardable and Optional Streams.)
To find an acceptable media type for a particular stream, the application queries the DMO. The DMO enumerates possible types, and the application selects one. Setting a media type on one stream can change the possible types available for other streams. For example, an audio-effect DMO might support a range of sample rates, but require the output rate to match the input rate. Setting the input type would therefore restrict the set of possible output types.
Media Types in the Registry
The DMORegister function adds information about a DMO to the registry, including a list of media types for input and output. An application uses this information to find DMOs that match its requirements. The information is not meant to be comprehensive. Typically, you would include only the main types that the DMO supports.
Although the registry information lists input and output types, it does not distinguish among individual streams. For example, if a DMO has separate input streams for audio and video, the registry information would list them both under input types.
For the DMORegister function, media types are specified using a DMO_PARTIAL_MEDIATYPE structure. The function differs in this respect from the IMediaObject interface, which uses DMO_MEDIA_TYPE. The DMO_PARTIAL_MEDIATYPE structure contains only two fields, for the major type and the subtype. It does not have fields for format block. Typically, the format contains information that is too granular to include in the registry, such as the height and width of a video image.
Preferred Media Types
To query a DMO for its supported types, an application calls the IMediaObject::GetInputType and IMediaObject::GetOutputType methods. These two methods enumerate the preferred types on a specified stream, in order of preference. A stream's preferred types can change dynamically when the application sets media types on other streams. For example, the preferred output types might change depending on the input types, or vice versa. A stream might not even have a preferred type until other streams have types. However, the DMO is not required to update its preferred types in this way. The application cannot assume that every type it receives is valid. For this reason, the SetInputType and SetOutputType methods support a flag for testing a specific type.
Sometimes a fully specified media type is too specific to use as a preferred type. To indicate a more general type, the DMO can return an incomplete type. A media type is incomplete if it has the value GUID_NULL for the major type, the subtype, or the format type. The GetInputType and GetOutputType methods usually set the format type to GUID_NULL.
After the application has set all of the input types, however, the DMO should generally return at least one complete type for each output stream. Having a complete type facilitates testing, and applications can use it as a reasonable default. (Note that some media types are complete without a format type.) The DMO test application included with the SDK relies on the DMO behaving this way (see Using the DMO Test Application).
Setting the Media Types
Applications use the IMediaObject::SetInputType and IMediaObject::SetOutputType methods to test, set, or clear types on a stream. The types must be fully specified, so that the DMO can process the data correctly. For each stream, the DMO must verify that the proposed type is compatible with the types on other streams. The DMO_SET_TYPEF_CLEAR flag clears a stream's type, so that the application can "back out" and try another combination.
The following examples describe some typical scenarios, to illustrate the points made in the previous sections.
Decoders
In a typical video decoder, the output format is determined partly by the input format. For example, the output stream usually must have the same frame rate and video size as the input stream. One option is for the decoder to return no output types until the input type is set. Another option is to enumerate a set of incomplete types with no format block. In that case, use the subtype to indicate the supported uncompressed types, such as 16-bit RGB, 24-bit RGB, and so forth.
Also, video decoders generally do not support an application setting the output type before it sets the input type. The usual scenario is to decode from a known input format, so this limitation is reasonable.
An audio decoder might support a fixed set of output formats. If so, it might be able to enumerate output formats before the application sets the input format.
Compressors
Usually, a video compressor cannot fully specify its preferred output formats until the application sets the input format, and vice versa. Instead, it should return an incomplete type with no format block. For both audio and video compression, applications usually need to control various format parameters, such as the output bit rate. However, if the input type is set, the compressor should enumerate at least one complete output type, for the reasons mentioned previously.