Microsoft DirectX 8.0 |
This interface provides methods for processing data in place. A Microsoft® DirectX® Media Object (DMO) can expose this interface if it meets the following conditions:
This interface provides an optimized way to process data. The application calls a single Process method instead of the IMediaObject::ProcessInput and IMediaObject::ProcessOutput methods. However, any DMO that implements this interface must also implement the IMediaObject interface. Therefore, an application is never obligated to use this interface, and a DMO is never guaranteed to implement it.
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMediaObjectInPlace methods Description Process Processes a block of data. Clone Creates a copy of the DMO in its current state. GetLatency Retrieves the latency introduced by this DMO.
Processes a block of data. The application supplies a pointer to a block of input data. The DMO processes the data in place.
Syntax
HRESULT Process( ULONG ulSize, BYTE *pData REFERENCE_TIME refTimeStart, DWORD dwFlags );
Parameters
- ulSize
- [in] Size of the data, in bytes.
- pData
- [in, out] Pointer to a buffer of size ulSize. On input, the buffer holds the input data. If the method returns successfully, the buffer contains the output data.
- refTimeStart
- [in] Start time of the data.
- dwFlags
- [in] Either DMO_INPLACE_NORMAL or DMO_INPLACE_ZERO. See Remarks for more information.
Return Value
Returns an HRESULT value. Possible values include those listed in the following table.
S_FALSE Success. There is still data to process. S_TRUE Success. There is no remaining data to process. E_FAIL Failure.
Remarks
If the method fails, the buffer might contain garbage. The application should not use the contents of the buffer.
The DMO might produce output data beyond the length of the input data. This is called an effect tail. For example, a reverb effect continues after the input reaches silence. If the DMO has an effect tail, this method returns S_FALSE.
While the application has input data for processing, call the Process method with the dwFlags parameter set to DMO_INPLACE_NORMAL. If the last such call returns S_FALSE, call Process again, this time with a zeroed input buffer and the DMO_INPLACE_ZERO flag. The DMO will now fill the zeroed buffer with the effect tail. Continue calling Process in this way until the return value is S_TRUE, indicating that the DMO has finished processing the effect tail.
If the DMO has no effect tail, this method always returns S_TRUE (or an error code).
Creates a copy of the DMO in its current state.
Syntax
HRESULT Clone( IMediaObjectInPlace **ppMediaObject );
Parameters
- ppMediaObject
- [out] Address of a pointer to receive the new DMO's IMediaObjectInPlace interface.
Return Value
Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.
Remarks
If the method succeeds, the IMediaObjectInPlace interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.
Retrieves the latency introduced by this DMO.
Syntax
HRESULT GetLatency( REFERENCE_TIME *pLatencyTime );
Parameters
- pLatencyTime
- [out] Pointer to a variable that receives the latency, in 100-nanosecond units.
Return Value
Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error.
Remarks
This method returns the average time required to process each buffer. This value usually depends on factors in the run-time environment, such as the processor speed and the CPU load. One possible way to implement this method is for the DMO to keep a running average based on historical data.