Microsoft DirectX 8.0

IAMVideoAccelerator Interface

The IAMVideoAccelerator interface enables a video decoder filter to access video accelerator functionality. The Overlay Mixer filter's input pin supports this interface. If a video decoder filter calls methods on this interface, the decoder should support the IAMVideoAcceleratorNotify interface on its output pin. Applications should not call methods on this interface.

Note This interface is available in Microsoft® Windows® 2000.

The sequence of events for connecting the video decoder filter is as follows:

  1. The filter graph manager calls the IPin::Connect method on the video decoder filter's output pin.
  2. The video decoder can call IAMVideoAccelerator::GetVideoAcceleratorGUIDs on the Overlay Mixer's input pin to retrieve a list of video accelerator GUIDs, which specify the video accelerator formats accepted by the Overlay Mixer.
  3. For a given video accelerator GUID, the video decoder can call IAMVideoAccelerator::GetUncompFormatsSupported to determine a suitable pixel format to propose.
  4. The video decoder calls the IPin::ReceiveConnection method on the Overlay Mixer's input pin, specifying a video accelerator GUID as the subtype of the media type. Within this call, the Overlay Mixer calls several methods on the decoder filter's output pin:
  5. The video decoder calls IAMVideoAccelerator::GetCompBufferInfo to retrieve information about the compressed data buffers associated with the video acceleration GUID previously specified.

To support dynamic format changes, this sequence can also occur while the filters are connected and running.

During operation, the video decoder performs the following steps.

  1. For each uncompressed data buffer, it calls IAMVideoAccelerator::BeginFrame to begin processing the output frame.
  2. To send uncompressed data to the video accelerator, the decoder calls the following methods.
  3. To end frame processing, it calls IAMVideoAccelerator::EndFrame.
  4. To display a frame, it calls IAMVideoAccelerator::DisplayFrame.

Before locking a buffer with the GetBuffer method, the video decoder should verify that any decompression operations that update that buffer are complete. Similarly for DisplayFrame, the video decoder must check that all decompression operations that update that frame are complete.

Requirements

Requires Videoacc.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IAMVideoAccelerator methodsDescription
GetVideoAcceleratorGUIDs Retrieves a list of the GUIDs for the video accelerator formats accepted.
GetUncompFormatsSupported Retrieves a list of pixel formats that can be used to render a specified video accelerator format.
GetInternalMemInfo Retrieves information about the uncompressed data memory requirements, based on the video accelerator GUID, the uncompressed size, and the pixel format.
GetCompBufferInfo Retrieves compressed buffer information.
GetInternalCompBufferInfo Called after the pins are connected, retrieving compressed buffer information given the connected type.
BeginFrame Begins frame processing.
EndFrame Ends frame processing and passes miscellaneous data to the video accelerator driver.
GetBuffer Retrieves the compressed buffer of a specified index and type.
ReleaseBuffer Releases a compressed buffer after processing.
Execute Performs a decompression operation.
QueryRenderStatus Queries the decode status of a set of macro blocks.
DisplayFrame Displays a decoded frame.

IAMVideoAccelerator::GetVideoAcceleratorGUIDs

IAMVideoAccelerator

Retrieves a list of the GUIDs for the video accelerator formats accepted.

Syntax

HRESULT GetVideoAcceleratorGUID(
  LPDWORD pdwNumGuidsSupported,
  LPGUID pGuidsSupported
);

Parameters

pdwNumGuidsSupported
[in] [out] If pGuidsSupported is NULL, pdwNumGuidsSupported returns with the number of video accelerator format GUIDs supported. Otherwise, this parameter is a pointer to the maximum number of GUIDs to return in pGuidsSupported. If fewer than this number are supported, pdwNumGuidsSupported is updated to be the number of GUIDs actually returned.
pGuidsSupported
[in] [out] If this parameter is not NULL, the GUIDs supported are returned in this array, whose size in bytes is at least sizeof(GUID) * (*pdwNumGuidsSupported).

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

IAMVideoAccelerator::GetUncompFormatsSupported

IAMVideoAccelerator

Retrieves a list of pixel formats that can be used to render a specified video accelerator format.

Syntax

HRESULT GetUncompFormatsSupported(
    const GUID *pGuid,
    LPDWORD pdwNumFormatsSupported,
    LPDDPIXELFORMAT pFormatsSupported
);

Parameters

pGuid
[in] Pointer to a video accelerator GUID.
pdwNumFormatsSupported
[in] [out] If pFormatsSupported is NULL, pdwNumFormatsSupported returns with the number of pixel formats to which the video accelerator format, defined by pGuid, can be converted. Otherwise, this parameter is the number of pixel formats to return in pFormatsSupported. When the method returns, this parameter is the actual number of pixel formats returned.
pFormatsSupported
[in] [out] Pointer to a DDPIXELFORMAT structure. If this parameter is not NULL, up to *pdwNumFormatsSupported pixel formats are copied into this array. The size of the buffer should be at least *pdwNumFormatsSupported * sizeof(DDPIXELFORMAT).

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

IAMVideoAccelerator::GetInternalMemInfo

IAMVideoAccelerator

Retrieves information about the uncompressed data memory requirements, based on the video accelerator GUID, the uncompressed size, and the pixel format.

Syntax

HRESULT GetInternalMemInfo(
    const GUID *pGuid,
    const AMVAUncompDataInfo *pamvaUncompDataInfo,
    LPAMVAInternalMemInfo pamvaInternalMemInfo
);

Parameters

pGuid
[in] Pointer to a video accelerator GUID.
pamvaUncompDataInfo
[in] Pointer to an AMVAUncompDataInfo structure containing the size and pixel format of the uncompressed data.
pamvaInternalMemInfo
[in] [out] Pointer to an AMVAInternalMemInfo structure containing information on the scratch memory requirement.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

IAMVideoAccelerator::GetCompBufferInfo

IAMVideoAccelerator

Retrieves compressed buffer information.

Syntax

HRESULT GetCompBufferInfo(
    const GUID *pGuid,
    const AMVAUncompDataInfo *pamvaUncompDataInfo,
    LPDWORD pdwNumTypesCompBuffers,
    LPAMVACompBufferInfo pamvaCompBufferInfo
);

Parameters

pGuid
[in] Pointer to a video accelerator format GUID.
pamvaUncompDataInfo
[in] Pointer to an AMVAUncompDataInfo structure containing the size and pixel format of the uncompressed data.
pdwNumTypesCompBuffers
[in] [out] Pointer to a variable of type DWORD. If pamvaCompBufferInfo is not NULL, this parameter receives the number of uncompressed buffer types. Otherwise, on input this parameter specifies the maximum number of compressed buffer types to return, and on output receives the actual number of compressed buffer types.
pamvaCompBufferInfo
[out] If non-NULL, then up to pdwNumTypesCompBuffers AMVACompBufferInfo structures are returned. This data includes the width, height, pixel format, and DirectDraw capabilities to be used to create the surface and the size in bytes the surface will occupy.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

This method returns the information necessary to create a video accelerator surface of the required type using DirectDraw. A video accelerator driver may support multiple compressed buffer types (for instance, video accelerator data and Inverse Discrete Cosine Transfer [IDCT] data).

IAMVideoAccelerator::GetInternalCompBufferInfo

IAMVideoAccelerator

Called after the pins are connected, retrieving compressed buffer information given the connected type.

Syntax

HRESULT GetInternalCompBufferInfo(
    LPDWORD pdwNumTypesCompBuffers,
    LPAMVACompBufferInfo pamvaCompBufferInfo
);

Parameters

pdwNumTypesCompBuffers
[in] [out] Pointer to a variable of type DWORD. If pamvaCompBufferInfo is not NULL, this parameter receives the number of uncompressed buffer types. Otherwise, on input this parameter specifies the maximum number of compressed buffer types to return, and on output receives the actual number of compressed buffer types.
pamvaCompBufferInfo
[out] If non-NULL, then up to pdwNumTypesCompBuffers AMVACompBufferInfo structures are returned. This data includes the width, height, pixel format, and DirectDraw capabilities to be used to create the surface and the size in bytes the surface will occupy.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

A video accelerator driver may support multiple compressed buffer types (for instance, video accelerator data and Inverse Discrete Cosine Transfer [IDCT] data.)

IAMVideoAccelerator::BeginFrame

IAMVideoAccelerator

Begins frame processing.

Syntax

HRESULT BeginFrame(
    const AMVABeginFrameInfo *pamvaBeginFrameInfo
    );

Parameters

pamvaBeginFrameInfo
[in] Pointer to an AMVABeginFrameInfo structure containing the information needed to begin processing the frame.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

This method can only be called after the pins are connected.

The AMVABeginFrameInfo structure contains an index to the destination buffer. Valid index values are from zero to dwActualUncompSurfacesAllocated–1), obtained by calling IAMVideoAcceleratorNotify::SetUncompSurfacesInfo.

The decoder should not make any assumption about the initial contents of the frame, as the frame memory used might not be the same as the memory last used with this frame index.

A call to this method might block operation processing if no non-busy frame buffer is available.

IAMVideoAccelerator::EndFrame

IAMVideoAccelerator

Ends frame processing and passes miscellaneous data to the video accelerator driver.

Syntax

HRESULT EndFrame(
    const AMVAEndFrameInfo *pEndFrameInfo
);

Parameters

pEndFrameInfo
[in] Pointer to an AMVAEndFrameInfo structure containing miscellaneous data for the video accelerator driver.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

IAMVideoAccelerator::GetBuffer

IAMVideoAccelerator

Retrieves the compressed buffer of a specified index and type.

Syntax

HRESULT GetBuffer(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex,
    BOOL bReadOnly,
    LPVOID *ppBuffer,
    LONG *lpStride
);

Parameters

dwTypeIndex
[in] Zero-based index into the surface types supported by the video accelerator driver, or 0xFFFFFFFF. See Remarks.
dwBufferIndex
[in] Buffer index within the type. The valid range is from zero to the value of the dwNumCompBuffers member of the AMVACompBufferInfo structure.
bReadOnly
[in] Boolean value indicating whether the buffer will be updated. If TRUE, the buffer will not be updated, allowing access to busy reference frames.
ppBuffer
[out] Pointer to the buffer that will contain the compressed data. The size of this buffer is determined by the dwBytesToAllocate member of the AMVACompBufferInfo structure returned for the dwSurfaceTypeIndex entry from the GetInternalCompBufferInfo method.
lpStride
[out] Stride compatible with the compression type. Generally, this will be equal to the dwWidthToCreate member of the AMVACompBufferInfo structure. Note that this might not be equal to dwWidthToCreate for output display buffers or other uncompressed types.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

This method locks and obtains access to a single buffer. Buffers are identified by type and by index within that type. The IAMVideoAccelerator::GetInternalCompBufferInfo method returns the number of types in its pdwNumTypesCompBuffers parameter, which defines the valid range for dwTypeIndex. For each type, the dwNumCompBuffers member of the AMVACompBufferInfo structure gives the number of buffers, which defines the valid range for dwBufferIndex. Note that dwTypeIndex and dwBufferIndex both specify zero-based offsets.

Alternatively, use a type index of 0xFFFFFFFF to retrieve a pointer to an output buffer. Currently, this is only valid between calls to BeginFrame and EndFrame. In this case the buffer index must equal the dwDestSurfaceIndex member of the AMVABeginFrameInfo structure that was passed to the last BeginFrame call.

This method will fail if the filter's pins are not connected.

Until all compressed buffers are released, it is possible that this thread will hold the Win16 lock or the DirectDraw lock.

IAMVideoAccelerator::ReleaseBuffer

IAMVideoAccelerator

Releases a compressed buffer after processing.

Syntax

HRESULT ReleaseBuffer(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex
);

Parameters

dwTypeIndex
[in] Zero-based index into the surface types supported by the video accelerator driver, or 0xFFFFFFFF.
dwBufferIndex
[in] Buffer index within the type. The valid range is from zero to the value of the dwNumCompBuffers member of the AMVACompBufferInfo structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

It is only valid to call this method after the pins are connected. Calling this method unlocks a single buffer. The video decoder calls this method when the buffer is no longer required and after any calls to Execute have been made. Note that the buffer pointer is no longer valid after this call.

IAMVideoAccelerator::Execute

IAMVideoAccelerator

Performs a decompression operation.

Syntax

HRESULT Execute(
    DWORD dwFunction,
    LPVOID lpPrivateInputData,
    DWORD cbPrivateInputData,
    LPVOID lpPrivateOutputData,
    DWORD cbPrivateOutputData,
    DWORD dwNumBuffers,
    const AMVABUFFERINFO *pamvaBufferInfo
);

Parameters

dwFunction
[in] Function number. This can be zero if this argument is the default or is ignored.
lpPrivateInputData
[in] Pointer to private input data passed to the driver.
cbPrivateInputData
[in] Length of private input data.
lpPrivateOutputData
[in] Pointer to private output data passed to the driver.
cbPrivateOutputData
[in] Length of private data buffer.
dwNumBuffers
[in] Number of AMVABUFFERINFO structures.
pamvaBufferInfo
[in] Pointer to a list of AMVABUFFERINFO structures to be passed.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

It is only valid to call this method after the pins are connected.

The associated buffer list is passed along with a function number (defaulting to zero) and any necessary private data describing the decompression operation. For example, decompressed reference frame information is passed in the buffer list. The buffer list order is important and is defined by the particular decompression operation being performed.

Private data can be passed to and from a driver.

IAMVideoAccelerator::QueryRenderStatus

IAMVideoAccelerator

Queries the decode status of a set of macro blocks.

Syntax

HRESULT QueryRenderStatus(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex,
    DWORD dwFlags
);

Parameters

dwTypeIndex
[in] Type index for buffer to be tested.
dwBufferIndex
[in] Buffer index for buffer to be tested.
dwFlags
[in] Flag indicating the type of query to perform. If zero, this method tests whether the surface is safe to use for updates. If AMVA_QUERYRENDERSTATUSF_READ, this method tests whether the surface is safe to use for reading.

Return Value

Returns an HRESULT value. Returns S_OK if the operation is complete; returns E_PENDING if the operation is still in progress. If the operation failed, this method returns another failure code, which can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

Calling this method will report progress and failures.

IAMVideoAccelerator::DisplayFrame

IAMVideoAccelerator

Displays a decoded frame.

Syntax

HRESULT DisplayFrame(
    DWORD dwFlipToIndex,
    IMediaSample *pMediaSample
);

Parameters

dwFlipToIndex
[in] The surface index of the decompressed frame to display.
pMediaSample
[in] Pointer to an IMediaSample interface containing start and stop time stamps.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAILFailure.
E_INVALIDARG Argument is invalid.
E_NOTIMPLMethod is not supported.
E_POINTER Null pointer argument.
S_OK Success.

Remarks

It is only valid to call this method after all pins are connected. This call is non-blocking.

The video decoder invokes this method after calling EndFrame for the surface whose index is dwFlipToIndex. This index must have previously been the value of the dwDestSurfaceIndex member in the AMVABeginFrameInfo structure passed in a call to BeginFrame.