IAMVideoAccelerator Interface

The IAMVideoAccelerator interface enables a video decoder to access video accelerator functionality during video decoding. IAMVideoAccelerator provides several advantages: promoting device independence, separating flip pipelining from video accelerator logistics, implementing bob and weave support independently of video accelerator hardware, and supplying built-in benefits by using Microsoft® DirectShow® to access the decompressed pixels.

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

The overlay mixer's input pin supports the IAMVideoAccelerator interface, and the decoder's output pin supports the IAMVideoAcceleratorNotify interface. The sequence of events for connecting the filter pins is as follows:

The video decoder filter's output pin IPin::Connect method is called to connect it to the overlay mixer filter's input pin.
The video decoder calls the overlay mixer input pin's IPin::ReceiveConnection method, specifying a video accelerator GUID as the subtype of the media type.
The overlay mixer calls IAMVideoAcceleratorNotify::GetUncompSurfacesInfo to determine how many output surfaces to create. Note that this call and the following two calls may occur inside the decoder pin's call to ReceiveConnection.
The output pin on the video decoder calls GetVideoAcceleratorGUIDs and GetUncompFormatsSupported to determine what video accelerator formats are supported. Then, it calls GetCompBufferInfo to determine a suitable pixel format to propose.
The overlay mixer calls IAMVideoAcceleratorNotify::SetUncompSurfacesInfo to tell the video decoder how many surfaces were allocated. Currently, this call is not implemented.
The overlay mixer calls IAMVideoAcceleratorNotify::GetCreateVideoAcceleratorData to get the video accelerator creation data to pass to the driver and creates its internal video accelerator object.

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

Then, for each video frame:

The video decoder calls BeginFrame.
The video decoder calls a sequence of GetBuffer, Execute, ReleaseBuffer, QueryRenderStatus.
The video decoder calls EndFrame.
The video decoder calls DisplayFrame. It is possible that this method is called for a frame other than the one just decoded.

Note Other calls can precede the call to BeginFrame, provided those calls do no update the output frame.

Locking and Sequencing

All hardware decoding operations are assumed to be sequential. The Execute method can return a cookie, which can be used in a call to QueryRenderStatus to determine whether an operation is complete. If the cookie passed to QueryRenderStatus is not in the driver's list, the operation is assumed to be complete.

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.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMVideoAccelerator methods Description

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.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMVideoAccelerator methods	Description
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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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] If pamvaComBufferInfo is not NULL, the number of uncompressed buffer types is returned. Otherwise, on input this parameter specifies the maximum number of compressed buffer types to return, and on output is updated with 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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] If pamvaCompBufferInfo is not NULL, this parameter is the number of uncompressed buffer types. Otherwise, on input this parameter specifies the maximum number of compressed buffer types to return, and on output is updated with 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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 *amvaBeginFrameInfo
    );

Parameters

pamvaBeginFrameInfo
[in] Pointer to an AMVABeginFrameInfo structure containing the information needed to begin processing the frame. This argument gives the destination surface index, and the miscellaneous input and output data pointers to pass directly to 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method is not supported.

E_POINTER Null pointer argument.

S_OK Success.

Remarks

This method can only be called after the pins are connected. When frame processing begins, miscellaneous information contained in the AMVABeginFrameInfo structure is passed directly to the hardware abstraction layer (HAL).

Calling this method notifies the overlay mixer which frame is the destination as a frame index. Valid indices range 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 may not be the same as the memory last used with this frame index.

A call to this method may 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method is not supported.

E_POINTER Null pointer argument.

S_OK Success.

Remarks

When frame processing is completed, miscellaneous data contained in the AMVAEndFrameInfo structure is passed directly to the hardware abstraction layer (HAL).

IAMVideoAccelerator::GetBuffer

IAMVideoAccelerator

Retrieves the compressed buffer of a specified index and type.

Syntax

HRESULT GetBuffer(
    DWORD dwTypeIndex,
    DWORD dwBufferIndex,
    BOOL bReadOnly,
    LPVOID *ppBuffer,
    LPLONG *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.

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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method is not supported.

E_POINTER Null pointer argument.

S_OK Success.

Remarks

This method locks and obtains access to a single buffer. It is only valid after pins are connected. Buffers are identified by type and by index within that type. Specifying read-only, through the bReadOnly parameter, allows access to busy reference frames. Output (uncompressed) frames use a type index of 0xFFFFFFFF.

Calling this method retrieves the compressed buffer of index dwBufferIndex of type dwTypeIndex. The type index can be from zero up to the value of pdwNumTypesCompBuffers returned by the GetInternalCompBufferInfo method. Alternatively, a type index of 0xFFFFFFFF specifies that a pointer to an output buffer is returned. Currently, the special type value 0xFFFFFFFF can only be used between calls to BeginFrame and EndFrame, and when dwBufferIndex is the same as the dwDestSurfaceIndex member of the AMVABeginFrameInfo structure that was passed to the last BeginFrame call.

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

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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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] A 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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_FAIL Failure.

E_INVALIDARG Argument is invalid.

E_NOTIMPL Method 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.

E_FAIL	Failure.
E_INVALIDARG	Argument is invalid.
E_NOTIMPL	Method is not supported.
E_POINTER	Null pointer argument.
S_OK	Success.