IMediaObjectInPlace Interface

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:

• It has one input stream and one output stream.
• Both streams use the same media type.
• The output is produced in place on the buffer; that is, without copying data.

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.

Methods in Vtable Order

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.

IMediaObjectInPlace::Process

---

IMediaObjectInPlace Interface

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).

IMediaObjectInPlace::Clone

---

IMediaObjectInPlace Interface

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.

IMediaObjectInPlace::GetLatency

---

IMediaObjectInPlace Interface

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.