Microsoft DirectX 8.0

IDMOVideoOutputOptimizations Interface

Supports video optimizations on a Microsoft® DirectX® Media Object (DMO).

This interface enables an application to negotiate with a DMO about video output optimizations. A DMO exposes this interface when it can perform optimizations that require support from the application. The application can query the DMO for its preferred features, and then agree (or not agree) to provide them. The DMO must process output even if the application rejects the optimizations.

For example, a video decoder might generate an output frame by applying deltas to the previous output frame. When queried, it requests that the application supply the previous frame in the output buffer. The application can agree to this request or not.

Video optimizations are negotiated separately for each output stream.

The following psuedo-code shows how an application might negotiate with the DMO:

IDMOVideoOutputOptimizations *pVidOpt;
// Query the DMO for IDMOVideoOutputOptimizations (not shown).

BOOL  bWantsPreviousBuffer = FALSE;
DWORD wFlags;
pVidOpt->QueryOperationModePreferences(0,&dwFlags);

if (dwFlags & DMO_VOSF_NEEDS_PREVIOUS_SAMPLE) 
{
    // Agree to the request.		
    pVidOpt->SetOperationMode(0, DMO_VOSF_NEEDS_PREVIOUS_SAMPLE);
    bWantsPreviousBuffer = TRUE;
}

// Processing loop
while (there is input)
{
    ProcessInput(0, ...);
    if (bWantsPreviousBuffer)
        pDMO->ProcessOutput(0, ...) // Use the same buffer as last time.
    else
        pDMO->ProcessOutput(0, ...) // OK to use a new buffer.
}	

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IDMOVideoOutputOptimizations methodsDescription
QueryOperationModePreferencesRetrieves the DMO's preferred optimization features.
SetOperationModeNotifies the DMO of the optimization features in effect.
GetCurrentOperationModeRetrieves the optimization features in effect.
GetCurrentSampleRequirementsRetrieves the optimization features required to process the next sample, given the features already agreed to by the application.

IDMOVideoOutputOptimizations::QueryOperationModePreferences

IDMOVideoOutputOptimizations Interface

Retrieves the DMO's preferred optimization features.

Syntax

HRESULT QueryOperationModePreferences(
    ULONG ulOutputStreamIndex,
    DWORD *pdwRequestedCapabilities
);

Parameters

ulOutputStreamIndex
Zero-based index of an output stream on the DMO.
pdwRequestedCapabilities
Pointer to a variable that receives the DMO's requested features. The returned value is a bitwise combination of zero or more flags from the DMO_VIDEO_OUTPUT_STREAM_FLAGS enumeration.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess
DMO_E_INVALIDSTREAMINDEXInvalid stream index
E_POINTERNULL pointer argument

IDMOVideoOutputOptimizations::SetOperationMode

IDMOVideoOutputOptimizations Interface

Notifies the DMO of the optimization features in effect.

Syntax

HRESULT SetOperationMode(
    ULONG ulOutputStreamIndex,
    DWORD dwEnabledFeatures
);

Parameters

ulOutputStreamIndex
Zero-based index of an output stream on the DMO.
dwEnabledFeatures
Bitwise combination of zero or more flags from the DMO_VIDEO_OUTPUT_STREAM_FLAGS enumeration.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess
DMO_E_INVALIDSTREAMINDEXInvalid stream index
E_INVALIDARGInvalid argument

Remarks

Before calling this method, call the QueryOperationModePreferences method to determine which features the DMO requests. Then call this method to inform the DMO which of those features you are providing. If you are not providing any of them, it is not necessary to call this method. The DMO does not assume that any of them will be provided.

The application must provide all the features it has agreed to. For some features, however, the DMO might not require the feature on every sample. To determine if the DMO can dispense with any features on the next sample, call the GetCurrentSampleRequirements method. In effect, this enables the DMO to waive an agreed-upon feature for one sample.

Before streaming begins, subsequent calls to this method override earlier calls. To set multiple features, you must do so in a single method call. Once streaming begins, this method returns an error. Streaming begins when the applications calls IMediaObject::ProcessInput on at least one input stream.

When streaming ends, the application can renegotiate the features. Streaming ends if the application calls the IMediaObject::Flush method, or if the application calls IMediaObject::Discontinuity on all the input streams and then processes all of the remaining output.

IDMOVideoOutputOptimizations::GetCurrentOperationMode

IDMOVideoOutputOptimizations Interface

Retrieves the optimization features in effect.

Syntax

HRESULT GetCurrentOperationMode(
    ULONG ulOutputStreamIndex,
    DWORD *pdwEnabledFeatures
);

Parameters

ulOutputStreamIndex
Zero-based index of an output stream on the DMO.
pdwEnabledFeatures
Pointer to a variable that receives the current features. The returned value is a bitwise combination of zero or more flags from the DMO_VIDEO_OUTPUT_STREAM_FLAGS enumeration.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess
DMO_E_INVALIDSTREAMINDEXInvalid stream index
E_POINTERNULL pointer argument

IDMOVideoOutputOptimizations::GetCurrentSampleRequirements

IDMOVideoOutputOptimizations Interface

Retrieves the optimization features required to process the next sample, given the features already agreed to by the application.

Syntax

HRESULT GetCurrentSampleRequirements(
    ULONG ulOutputStreamIndex,
    DWORD *pdwRequestedFeatures
);

Parameters

ulOutputStreamIndex
Zero-based index of an output stream on the DMO.
pdwRequestedFeatures
Pointer to a variable that receives the required features. The returned value is a bitwise combination of zero or more flags from the DMO_VIDEO_OUTPUT_STREAM_FLAGS enumeration.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess
DMO_E_INVALIDSTREAMINDEXInvalid stream index
E_POINTERNULL pointer argument

Remarks

After an application calls the SetOperationMode method, it must provide all the features it has agreed to. However, the DMO might not require every feature on every sample. This method enables the DMO to waive an agreed-upon feature for one sample.

Before processing a sample, the application can call this method. If the DMO does not require a given feature in order to process the next sample, it omits the corresponding flag from the pdwRequestedFeatures parameter. For the next sample only, the application can ignore the feature. The results of this method are valid only for the next call to the IMediaObject::ProcessOutput method.

The DMO will return only the flags that were agreed to in the SetOperationMode method. In other words, you cannot dynamically enable new features with this method.