Microsoft DirectX 8.0 |
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:
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.
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 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.
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.
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_FAIL Failure. E_INVALIDARG Argument is invalid. E_NOTIMPL Method is not supported. E_POINTER Null pointer argument. S_OK Success.
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.
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_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).
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_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.)
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_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.
The AMVABeginFrameInfo structure contains an index to the destination buffer. Valid index values are from zero to
dwActualUncompSurfacesAllocated1)
, 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.
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.
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_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. 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.
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.
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.
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_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.
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.