mfxFrameAllocator

Definition

 

 

typedef struct {

      mfxU32      reserved[4];

      mfxHDL      pthis;

      mfxStatus   (*Alloc)(mfxHDL pthis, mfxFrameAllocRequest *request,                   mfxFrameAllocResponse *response);

      mfxStatus   (*Lock)(mfxHDL pthis, mfxMemId mid, mfxFrameData *ptr);

      mfxStatus   (*Unlock)(mfxHDL pthis, mfxMemId mid, mfxFrameData *ptr);

      mfxStatus   (*GetHDL)(mfxHDL pthis, mfxMemId mid, mfxHDL *handle);

      mfxStatus   (*Free)(mfxHDL pthis, mfxFrameAllocResponse *response);

} mfxFrameAllocator;

 

Description

 

 

The mfxFrameAllocator structure describes the callback functions Alloc, Lock, Unlock, GetHDL and Free that the SDK implementation might use for allocating internal frames. Applications that operate on OS-specific video surfaces must implement these callback functions.

Using the default allocator implies that frame data passes in or out of SDK functions through pointers, as opposed to using memory IDs.

The SDK behavior is undefined when using an incompletely defined external allocator. See the section  Memory Allocation and External Allocators for additional information.

 

Members

 

 

pthis

Pointer to the allocator object

 

 

Alloc

Pointer to the function that allocates frames

 

 

Lock

Pointer to the function that locks a frame and obtain its pointers

 

 

Unlock

Pointer to the function that unlocks a frame; after unlocking, any pointers to the frame are invalid.

 

 

GetHDL

Pointer to the function that obtains the OS-specific handle

 

 

Free

Pointer to the function that de-allocates a frame

 

Change History

 

 

This structure is available since SDK API 1.0.

 

 

 

 

Syntax

 

 

mfxStatus (*Alloc)(mfxHDL pthis, mfxFrameAllocRequest *request, mfxFrameAllocResponse *response);

 

Parameters

 

 

pthis

Pointer to the allocator object

 

 

request

Pointer to the mfxFrameAllocRequest structure that specifies the type and number of required frames

 

 

response

Pointer to the mfxFrameAllocResponse structure that retrieves frames actually allocated

 

Description

 

 

This function allocates surface frames. For decoders, MFXVideoDECODE_Init calls Alloc only once. That call includes all frame allocation requests. For encoders, MFXVideoENCODE_Init calls Alloc twice: once for the input surfaces and again for the internal reconstructed surfaces.

If two SDK components must share DirectX* surfaces, this function should pass the pre-allocated surface chain to SDK instead of allocating new DirectX surfaces. See the Error! Reference source not found. section for additional information.

 

Return Status

 

 

MFX_ERR_NONE

The function successfully allocated the memory block.

 

 

MFX_ERR_MEMORY_ALLOC

The function failed to allocate the video frames.

 

 

MFX_ERR_UNSUPPORTED

The function does not support allocating the specified type of memory.

 

Change History

 

This function is available since SDK API 1.0.

 

 

 

 

 

Syntax

 

 

mfxStatus (*Free)(mfxHDL pthis, mfxFrameAllocResponse *response);

 

Parameters

 

 

pthis

Pointer to the allocator object

 

 

response

Pointer to the mfxFrameAllocResponse structure returned by the Alloc function

 

Description

 

 

This function de-allocates all allocated frames.

 

Return Status

 

 

MFX_ERR_NONE

The function successfully de-allocated the memory block.

 

Change History

 

This function is available since SDK API 1.0.

 

 

 

 

 

Syntax

 

 

mfxStatus (*Lock)(mfxHDL pthis, mfxMemId mid, mfxFrameData *ptr);

 

Parameters

 

 

pthis

Pointer to the allocator object

 

 

mid

Memory block ID

 

 

ptr

Pointer to the returned frame structure

 

Description

 

 

This function locks a frame and returns its pointer.

 

Return Status

 

 

MFX_ERR_NONE

The function successfully locked the memory block.

 

 

MFX_ERR_LOCK_MEMORY

This function failed to lock the frame.

 

Change History

 

This function is available since SDK API 1.0.

 

 

 

 

 

Syntax

 

 

mfxStatus (*Unlock)(mfxHDL pthis, mfxMemId mid, mfxFrameData *ptr);

 

Parameters

 

 

pthis

Pointer to the allocator object

 

 

mid

Memory block ID

 

 

ptr

Pointer to the frame structure; This pointer can be NULL.

 

Description

 

 

This function unlocks a frame and invalidates the specified frame structure.

 

Return Status

 

 

MFX_ERR_NONE

The function successfully unlocked the frame.

 

Change History

 

This function is available since SDK API 1.0.

 

 

 

 

 

Syntax

 

 

mfxStatus (*GetHDL)(mfxHDL pthis, mfxMemId mid, mfxHDL *hdl);

 

Parameters

 

 

pthis

Pointer to the allocator object

 

 

mid

Memory block ID

 

 

hdl

Pointer to the returned OS-specific handle

 

Description

 

 

This function returns the OS-specific handle associated with a video frame. If the handle is a COM interface, the reference counter must increase. The SDK will release the interface afterward.

 

Return Status

 

 

MFX_ERR_NONE

The function successfully returned the OS-specific handle.

 

 

MFX_ERR_UNSUPPORTED

The function does not support obtaining OS-specific handle.

 

Change History

 

This function is available since SDK API 1.0.

 

 

 

 

 

For more complete information about compiler optimizations, see our Optimization Notice.