Encoder API

The Encoder API provides a uniform interface for configuring software and hardware encoders. Applications can use the Encoder API to configure an encoder and to store the configuration settings. Encoder vendors can use the Encoder API to expose the capabilities of an encoder. Although the Encoder API is designed primarily for encoders, it is general enough that decoders can support it as well.

The Encoder API is exposed to applications through the ICodecAPI interface, which is exposed by the encoder filter. The encoder filter may be a native DirectShow filter, a hardware encoder, or a DirectX Media Object (DMO).

• Software filters: An encoder that is implemented as a native DirectShow filter should expose the ICodecAPI directly.
• Hardware encoders: The encoding device is exposed through one or more AVStream minidrivers, which are represented in user mode by KSProxy. KSProxy translates ICodecAPI method calls into KS property sets. For more information, see "Encoder Minidrivers" in the DDK.
• DMOs: The DMO should expose the ICodecAPI interface. DirectShow applications can query the DMO Wrapper filter, which exposes the interface by aggregating the DMO. Applications not based on DirectShow can query the DMO directly.

Encoder Capabilties

An encoder can register a list of high-level capabilities by storing them in the system registry. Each capability is identified by a GUID. To enumerate the capabilities of a particular encoder, do the following:

1. Create the moniker that represents the encoder filter. (See Using the System Device Enumerator.)
2. Query the filter moniker for the IGetCapabilitiesKey interface.
3. Call IGetCapabilitiesKey::GetCapabilitiesKey. The method returns a handle to the registry key that contains the filter's capabilities list.
4. Call RegEnumValue to enumerate the values for the returned key.

If you are devloping an encoder, create the registry entries for the capabilities when the filter is registered. For software filters, create a key named Capabilities that is adjacent to the FilterData and FriendlyName keys. Typically, you would add this information after calling AMovieDllRegisterServer2 to register the standard filter data. For more information, see How to Register DirectShow Filters. Alternatively, you can create a CapabilitiesLocation key that contains a string giving the location of the Capabilities key in the registry. The string should start with "HKLM\", "HKCR\", or "HKCU\" to indicate the registry subtree. For Plug and Play devices, the driver's setup files should create a Capabilities key adjacent to the filter's FriendlyName key, or it can use a CapabilitiesLocation key as described for software filters.

Once you have created the Capabilities key, create a value for each capability GUID. The name of the value should be the string form of the GUID, in the form {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}. Each value type should be one of the following:

• Single numerical value. Use a DWORD value.
• GUID. Use the string form of the GUID.
• Numeric pairs. Use a string with the form "a,b" to represent pairs of values, such as width and height, or numerator and denominator for fractions.
• Arrays of values. Use multi-strings (REG_SZ_MULTI) to represent more than one value.

The following example shows the registry layout for a software filter:

\HKCR\CLSID\Filter Category\Instance\Filter CLSID\Capabilities\
    Values: 
    guid1: 1234 (REG_DWORD)   
    guid2: "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}" (REG_SZ)
    guid3: "2","4","6" (REG_SZ_MULTI)
    guid4: "720,480" (REG_SZ) 

Encoder Profiles

An encoder profile is a fixed list of configuration settings that can be applied to an encoder at run time. Profiles are independent of the encoder; an application can select an encoder, then select a profile and apply the profile settings to the encoder. Profiles are identified by GUID and should be stored in the following location in the registry:

\HKLM\Software\Microsoft\EncoderProfiles\Profile GUID\

where Profile GUID is the string form of the GUID that identifies the profile. Create values for each setting. Also create a value named FriendlyName whose data contains a printable string identifying the profile (such as "LowBandwidthVideo").