Microsoft DirectX 8.0 |
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. }
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IDMOVideoOutputOptimizations methods Description QueryOperationModePreferences Retrieves the DMO's preferred optimization features. SetOperationMode Notifies the DMO of the optimization features in effect. GetCurrentOperationMode Retrieves the optimization features in effect. GetCurrentSampleRequirements Retrieves the optimization features required to process the next sample, given the features already agreed to by the application.
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_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index E_POINTER NULL pointer argument
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_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index E_INVALIDARG Invalid 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.
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_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index E_POINTER NULL pointer argument
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_OK Success DMO_E_INVALIDSTREAMINDEX Invalid stream index E_POINTER NULL 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.