Memory Structures

Structures used for memory.

API

mfxBitstream

struct mfxBitstream

Defines the buffer that holds compressed video data.

Public Members

mfxEncryptedData *EncryptedData

Reserved and must be zero.

mfxExtBuffer **ExtParam

Array of extended buffers for additional bitstream configuration. See the ExtendedBufferID enumerator for a complete list of extended buffers.

mfxU16 NumExtParam

The number of extended buffers attached to this structure.

mfxU32 CodecId

Specifies the codec format identifier in the FourCC code. See the CodecFormatFourCC enumerator for details. This optional parameter is required for the simplified decode initialization.

mfxI64 DecodeTimeStamp

Decode time stamp of the compressed bitstream in units of 90KHz. A value of MFX_TIMESTAMP_UNKNOWN indicates that there is no time stamp.

This value is calculated by the encoder from the presentation time stamp provided by the application in the mfxFrameSurface1 structure and from the frame rate provided by the application during the encoder initialization.

mfxU64 TimeStamp

Time stamp of the compressed bitstream in units of 90KHz. A value of MFX_TIMESTAMP_UNKNOWN indicates that there is no time stamp.

mfxU8 *Data

Bitstream buffer pointer, 32-bytes aligned.

mfxU32 DataOffset

Next reading or writing position in the bitstream buffer.

mfxU32 DataLength

Size of the actual bitstream data in bytes.

mfxU32 MaxLength

Allocated bitstream buffer size in bytes.

mfxU16 PicStruct

Type of the picture in the bitstream. Output parameter.

mfxU16 FrameType

Frame type of the picture in the bitstream. Output parameter.

mfxU16 DataFlag

Indicates additional bitstream properties. See the BitstreamDataFlag enumerator for details.

mfxU16 reserved2

Reserved for future use.

mfxFrameAllocator

struct mfxFrameAllocator

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

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

Behavior is undefined when using an incompletely defined external allocator.

See the Memory Allocation and External Allocators section for additional information.

Public Members

mfxHDL pthis

Pointer to the allocator object.

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

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 library components must share DirectX* surfaces, this function should pass the pre-allocated surface chain to the library instead of allocating new DirectX surfaces.

See the Surface Pool Allocation section for additional information.

Param pthis:

[in] Pointer to the allocator object.

Param request:

[in] Pointer to the mfxFrameAllocRequest structure that specifies the type and number of required frames.

Param response:

[out] Pointer to the mfxFrameAllocResponse structure that retrieves frames actually allocated.

Return:

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.

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

Locks a frame and returns its pointer.

Param pthis:

[in] Pointer to the allocator object.

Param mid:

[in] Memory block ID.

Param ptr:

[out] Pointer to the returned frame structure.

Return:

MFX_ERR_NONE The function successfully locked the memory block.

MFX_ERR_LOCK_MEMORY This function failed to lock the frame.

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

Unlocks a frame and invalidates the specified frame structure.

Param pthis:

[in] Pointer to the allocator object.

Param mid:

[in] Memory block ID.

Param ptr:

[out] Pointer to the frame structure. This pointer can be NULL.

Return:

MFX_ERR_NONE The function successfully locked the memory block.

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

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

Param pthis:

[in] Pointer to the allocator object.

Param mid:

[in] Memory block ID.

Param handle:

[out] Pointer to the returned OS-specific handle.

Return:

MFX_ERR_NONE The function successfully returned the OS-specific handle.

MFX_ERR_UNSUPPORTED The function does not support obtaining OS-specific handle..

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

De-allocates all allocated frames.

Param pthis:

[in] Pointer to the allocator object.

Param response:

[in] Pointer to the mfxFrameAllocResponse structure returned by the Alloc function.

Return:

MFX_ERR_NONE The function successfully de-allocated the memory block.

mfxFrameAllocRequest

struct mfxFrameAllocRequest

Describes multiple frame allocations when initializing encoders, decoders, and video preprocessors. A range specifies the number of video frames. Applications are free to allocate additional frames. In all cases, the minimum number of frames must be at least NumFrameMin or the called API function will return an error.

Public Members

mfxU32 AllocId

Unique (within the session) ID of component requested the allocation.

mfxFrameInfo Info

Describes the properties of allocated frames.

mfxU16 Type

Allocated memory type. See the ExtMemFrameType enumerator for details.

mfxU16 NumFrameMin

Minimum number of allocated frames.

mfxU16 NumFrameSuggested

Suggested number of allocated frames.

mfxFrameAllocResponse

struct mfxFrameAllocResponse

Describes the response to multiple frame allocations. The calling API function returns the number of video frames actually allocated and pointers to their memory IDs.

Public Members

mfxU32 AllocId

Unique (within the session) ID of component requested the allocation.

mfxMemId *mids

Pointer to the array of the returned memory IDs. The application allocates or frees this array.

mfxU16 NumFrameActual

Number of frames actually allocated.

mfxFrameData

struct mfxY410

Specifies “pixel” in Y410 color format.

Public Members

mfxU32 U

U component.

mfxU32 Y

Y component.

mfxU32 V

V component.

mfxU32 A

A component.

struct mfxY416

Specifies “pixel” in Y416 color format.

Public Members

mfxU32 U

U component.

mfxU32 Y

Y component.

mfxU32 V

V component.

mfxU32 A

A component.

struct mfxA2RGB10

Specifies “pixel” in A2RGB10 color format

Public Members

mfxU32 B

B component.

mfxU32 G

G component.

mfxU32 R

R component.

mfxU32 A

A component.

struct mfxFrameData

Describes frame buffer pointers.

Extension Buffers

mfxU16 NumExtParam

The number of extra configuration structures attached to this structure.

General members

mfxU16 reserved[9]

Reserved for future use.

mfxU16 MemType

Allocated memory type. See the ExtMemFrameType enumerator for details. Used for better integration of 3rd party plugins into the pipeline.

mfxU16 PitchHigh

Distance in bytes between the start of two consecutive rows in a frame.

mfxU64 TimeStamp

Time stamp of the video frame in units of 90KHz. Divide TimeStamp by 90,000 (90 KHz) to obtain the time in seconds. A value of MFX_TIMESTAMP_UNKNOWN indicates that there is no time stamp.

mfxU32 FrameOrder

Current frame counter for the top field of the current frame. An invalid value of MFX_FRAMEORDER_UNKNOWN indicates that API functions that generate the frame output do not use this frame.

mfxU16 Locked

Counter flag for the application. If Locked is greater than zero then the application locks the frame or field pair. Do not move, alter or delete the frame.

Color Planes

Data pointers to corresponding color channels (planes). The frame buffer pointers must be 16-byte aligned. The application has to specify pointers to all color channels even for packed formats. For example, for YUY2 format the application must specify Y, U, and V pointers. For RGB32 format, the application must specify R, G, B, and A pointers.

mfxU8 *A

A channel.

mfxMemId MemId

Memory ID of the data buffers. Ignored if any of the preceding data pointers is non-zero.

Additional Flags

mfxU16 Corrupted

Some part of the frame or field pair is corrupted. See the Corruption enumerator for details.

mfxU16 DataFlag

Additional flags to indicate frame data properties. See the FrameDataFlag enumerator for details.

Public Members

mfxExtBuffer **ExtParam

Points to an array of pointers to the extra configuration structures. See the ExtendedBufferID enumerator for a list of extended configurations.

mfxU16 PitchLow

Distance in bytes between the start of two consecutive rows in a frame.

mfxU8 *Y

Y channel.

mfxU16 *Y16

Y16 channel.

mfxU8 *R

R channel.

mfxU8 *UV

UV channel for UV merged formats.

mfxU8 *VU

YU channel for VU merged formats.

mfxU8 *CbCr

CbCr channel for CbCr merged formats.

mfxU8 *CrCb

CrCb channel for CrCb merged formats.

mfxU8 *Cb

Cb channel.

mfxU8 *U

U channel.

mfxU16 *U16

U16 channel.

mfxU8 *G

G channel.

mfxY410 *Y410

T410 channel for Y410 format (merged AVYU).

mfxY416 *Y416

This format is a packed 16-bit representation that includes 16 bits of alpha.

mfxU8 *Cr

Cr channel.

mfxU8 *V

V channel.

mfxU16 *V16

V16 channel.

mfxU8 *B

B channel.

mfxA2RGB10 *A2RGB10

A2RGB10 channel for A2RGB10 format (merged ARGB).

mfxABGR16FP *ABGRFP16

ABGRFP16 channel for half float ARGB format (use this merged one due to no separate FP16 Alpha Channel).

mfxFrameInfo

struct mfxFrameInfo

Specifies properties of video frames. See also “Configuration Parameter Constraints” chapter.

FrameRate

Specify the frame rate with the following formula: FrameRateExtN / FrameRateExtD.

For encoding, frame rate must be specified. For decoding, frame rate may be unspecified (FrameRateExtN and FrameRateExtD are all zeros.) In this case, the frame rate is defaulted to 30 frames per second.

mfxU32 FrameRateExtN

Frame rate numerator.

mfxU32 FrameRateExtD

Frame rate denominator.

AspectRatio

AspectRatioW and AspectRatioH are used to specify the sample aspect ratio. If sample aspect ratio is explicitly defined by the standards (see Table 6-3 in the MPEG-2 specification or Table E-1 in the H.264 specification), AspectRatioW and AspectRatioH should be the defined values. Otherwise, the sample aspect ratio can be derived as follows:

• AspectRatioW=display_aspect_ratio_width*display_height

• AspectRatioH=display_aspect_ratio_height*display_width

For MPEG-2, the above display aspect ratio must be one of the defined values in Table 6-3 in the MPEG-2 specification. For H.264, there is no restriction on display aspect ratio values.

If both parameters are zero, the encoder uses the default value of sample aspect ratio.

mfxU16 AspectRatioW

Aspect Ratio for width.

mfxU16 AspectRatioH

Aspect Ratio for height.

ROI

The region of interest of the frame. Specify the display width and height in mfxVideoParam.

mfxU16 CropX

X coordinate. In case of fused operation of decode plus VPP it can be set to zero to signalize that cropping operation is not requested.

mfxU16 CropY

Y coordinate. In case of fused operation of decode plus VPP it can be set to zero to signalize that cropping operation is not requested.

mfxU16 CropW

Width in pixels. In case of fused operation of decode plus VPP it can be set to zero to signalize that cropping operation is not requested.

mfxU16 CropH

Height in pixels. In case of fused operation of decode plus VPP it can be set to zero to signalize that cropping operation is not requested.

Public Members

mfxU32 reserved[4]

Reserved for future use.

mfxU16 ChannelId

The unique ID of each VPP channel set by application. It’s required that during Init/Reset application fills ChannelId for each mfxVideoChannelParam provided by the application and the SDK sets it back to the correspondent mfxSurfaceArray::mfxFrameSurface1 to distinguish different channels. It’s expected that surfaces for some channels might be returned with some delay so application has to use mfxFrameInfo::ChannelId to distinguish what returned surface belongs to what VPP channel. Decoder’s initialization parameters are always sent through channel with mfxFrameInfo::ChannelId equals to zero. It’s allowed to skip setting of decoder’s parameters for simplified decoding procedure

mfxU16 BitDepthLuma

Number of bits used to represent luma samples.

Note

Not all codecs and implementations support this value. Use the Query API function to check if this feature is supported.

mfxU16 BitDepthChroma

Number of bits used to represent chroma samples.

Note

Not all codecs and implementations support this value. Use the Query API function to check if this feature is supported.

mfxU16 Shift

When the value is not zero, indicates that values of luma and chroma samples are shifted. Use BitDepthLuma and BitDepthChroma to calculate shift size. Use zero value to indicate absence of shift. See example data alignment below.

Note

Not all codecs and implementations support this value. Use the Query API function to check if this feature is supported.

mfxFrameId FrameId

Describes the view and layer of a frame picture.

mfxU32 FourCC

FourCC code of the color format. See the ColorFourCC enumerator for details.

mfxU16 Width

Width of the video frame in pixels. Must be a multiple of 16. In case of fused operation of decode plus VPP it can be set to zero to signalize that scaling operation is not requested.

mfxU16 Height

Height of the video frame in pixels. Must be a multiple of 16 for progressive frame sequence and a multiple of 32 otherwise. In case of fused operation of decode plus VPP it can be set to zero to signalize that scaling operation is not requested.

mfxU64 BufferSize

Size of frame buffer in bytes. Valid only for plain formats (when FourCC is P8). In this case, Width, Height, and crop values are invalid.

mfxU16 PicStruct

Picture type as specified in the PicStruct enumerator.

mfxU16 ChromaFormat

Color sampling method. Value is the same as that of ChromaFormatIdc. ChromaFormat is not defined if FourCC is zero.

Note

Example data alignment for Shift = 0:

Example data alignment for Shift != 0:

mfxFrameSurface1

struct mfxFrameSurface1

Defines the uncompressed frames surface information and data buffers. The frame surface is in the frame or complementary field pairs of pixels up to four color-channels, in two parts: mfxFrameInfo and mfxFrameData.

Public Members

struct mfxFrameSurfaceInterface *FrameInterface

Specifies interface to work with surface.

mfxFrameInfo Info

Specifies surface properties.

mfxFrameData Data

Describes the actual frame buffer.

mfxFrameSurfaceInterface

struct mfxFrameSurfaceInterface

Public Members

mfxHDL Context

The context of the memory interface. User should not touch (change, set, null) this pointer.

mfxStructVersion Version

The version of the structure.

mfxStatus (*AddRef)(mfxFrameSurface1 *surface)

Increments the internal reference counter of the surface. The surface is not destroyed until the surface is released using the mfxFrameSurfaceInterface::Release function. mfxFrameSurfaceInterface::AddRef should be used each time a new link to the surface is created (for example, copy structure) for proper surface management.

Param surface:

[in] Valid surface.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If mfxFrameSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Release)(mfxFrameSurface1 *surface)

Decrements the internal reference counter of the surface. mfxFrameSurfaceInterface::Release should be called after using the mfxFrameSurfaceInterface::AddRef function to add a surface or when allocation logic requires it. For example, call mfxFrameSurfaceInterface::Release to release a surface obtained with the GetSurfaceForXXX function.

Param surface:

[in] Valid surface.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If mfxFrameSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNDEFINED_BEHAVIOR If Reference Counter of surface is zero before call.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetRefCounter)(mfxFrameSurface1 *surface, mfxU32 *counter)

Returns current reference counter of mfxFrameSurface1 structure.

Param surface:

[in] Valid surface.

Param counter:

[out] Sets counter to the current reference counter value.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface or counter is NULL.

MFX_ERR_INVALID_HANDLE If mfxFrameSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Map)(mfxFrameSurface1 *surface, mfxU32 flags)

Sets pointers of surface->Info.Data to actual pixel data, providing read-write access.

In case of video memory, the surface with data in video memory becomes mapped to system memory. An application can map a surface for read access with any value of mfxFrameSurface1::Data::Locked, but can map a surface for write access only when mfxFrameSurface1::Data::Locked equals to 0.

Note: A surface allows shared read access, but exclusive write access. Consider the following cases:

• Map with Write or Read|Write flags. A request during active another read or write access returns MFX_ERR_LOCK_MEMORY error immediately, without waiting. MFX_MAP_NOWAIT does not impact behavior. This type of request does not lead to any implicit synchronizations.

• Map with Read flag. A request during active write access will wait for resource to become free, or exits immediately with error if MFX_MAP_NOWAIT flag was set. This request may lead to the implicit synchronization (with same logic as Synchronize call) waiting for surface to become ready to use (all dependencies should be resolved and upstream components finished writing to this surface).

It is guaranteed that read access will be acquired right after synchronization without allowing another thread to acquire this surface for writing.

If MFX_MAP_NOWAIT was set and the surface is not ready yet (for example the surface has unresolved data dependencies or active processing), the read access request exits immediately with error.

Read-write access with MFX_MAP_READ_WRITE provides exclusive simultaneous reading and writing access.

Note

Bitwise copying of mfxFrameSurface1 object between map / unmap calls may result in having dangling data pointers in copies.

Param surface:

[in] Valid surface.

Param flags:

[out] Specify mapping mode.

Param surface->Info.Data:

[out] Pointers set to actual pixel data.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If mfxFrameSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNSUPPORTED If flags are invalid.

MFX_ERR_LOCK_MEMORY If user wants to map the surface for write and surface->Data.Locked does not equal to 0.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Unmap)(mfxFrameSurface1 *surface)

Invalidates pointers of surface->Info.Data and sets them to NULL. In case of video memory, the underlying texture becomes unmapped after last reader or writer unmap.

Param surface:

[in] Valid surface.

Param surface->Info.Data:

[out] Pointers set to NULL.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If mfxFrameSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNSUPPORTED If surface is already unmapped.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetNativeHandle)(mfxFrameSurface1 *surface, mfxHDL *resource, mfxResourceType *resource_type)

Returns a native resource’s handle and type. The handle is returned as-is, meaning that the reference counter of base resources is not incremented. The native resource is not detached from surface and the library still owns the resource. User must not destroy the native resource or assume that the resource will be alive after mfxFrameSurfaceInterface::Release.

Param surface:

[in] Valid surface.

Param resource:

[out] Pointer is set to the native handle of the resource.

Param resource_type:

[out] Type of native resource. See mfxResourceType enumeration).

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If any of surface, resource or resource_type is NULL.

MFX_ERR_INVALID_HANDLE If any of surface, resource or resource_type is not valid object (no native resource was allocated).

MFX_ERR_UNSUPPORTED If surface is in system memory.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetDeviceHandle)(mfxFrameSurface1 *surface, mfxHDL *device_handle, mfxHandleType *device_type)

Returns a device abstraction that was used to create that resource. The handle is returned as-is, meaning that the reference counter for the device abstraction is not incremented. The native resource is not detached from the surface and the library still has a reference to the resource. User must not destroy the device or assume that the device will be alive after mfxFrameSurfaceInterface::Release.

Param surface:

[in] Valid surface.

Param device_handle:

[out] Pointer is set to the device which created the resource

Param device_type:

[out] Type of device (see mfxHandleType enumeration).

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If any of surface, device_handle or device_type is NULL.

MFX_ERR_INVALID_HANDLE If any of surface, resource or resource_type is not valid object (no native resource was allocated).

MFX_ERR_UNSUPPORTED If surface is in system memory.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Synchronize)(mfxFrameSurface1 *surface, mfxU32 wait)

Guarantees readiness of both the data (pixels) and any frame’s meta information (for example corruption flags) after a function completes.

Instead of MFXVideoCORE_SyncOperation, users may directly call the mfxFrameSurfaceInterface::Synchronize function after the corresponding Decode or VPP function calls (MFXVideoDECODE_DecodeFrameAsync or MFXVideoVPP_RunFrameVPPAsync). The prerequisites to call the functions are:

• The main processing functions return MFX_ERR_NONE.

• A valid mfxFrameSurface1 object.

Param surface:

[in] Valid surface.

Param wait:

[out] Wait time in milliseconds.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If any of surface is not valid object .

MFX_WRN_IN_EXECUTION If the given timeout is expired and the surface is not ready.

MFX_ERR_ABORTED If the specified asynchronous function aborted due to data dependency on a previous asynchronous function that did not complete.

MFX_ERR_UNKNOWN Any internal error.

void (*OnComplete)(mfxStatus sts)

The library calls the function after complete of associated video operation notifying the application that frame surface is ready.

It is expected that the function is low-intrusive designed otherwise it may impact performance.

Attention

This is callback function and intended to be called by the library only.

Note

The library calls this callback only when this surface is used as the output surface.

Param sts:

[in] The status of completed operation.

mfxStatus (*QueryInterface)(mfxFrameSurface1 *surface, mfxGUID guid, mfxHDL *iface)

Returns an interface defined by the GUID. If the returned interface is a reference counted object the caller should release the obtained interface to avoid memory leaks.

Param surface:

[in] Valid surface.

Param guid:

[in] GUID of the requested interface.

Param iface:

[out] Interface.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If interface or surface is NULL.

MFX_ERR_UNSUPPORTED If requested interface is not supported.

MFX_ERR_NOT_IMPLEMENTED If requested interface is not implemented.

MFX_ERR_NOT_INITIALIZED If requested interface is not available (not created or already deleted).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Export)(mfxFrameSurface1 *surface, mfxSurfaceHeader export_header, mfxSurfaceHeader **exported_surface)

If successful returns an exported surface, which is a refcounted object allocated by runtime. It could be exported with or without copy, depending on export flags and the possibility of such export. Exported surface is valid throughout the session, as long as the original mfxFrameSurface1 object is not closed and the refcount of exported surface is not zero.

Param surface:

[in] Valid surface.

Param export_header:

[in] Description of export: caller should fill in SurfaceType (type to export to) and SurfaceFlags (allowed export modes).

Param exported_surface:

[out] Exported surface, allocated by runtime, user needs to decrement refcount after usage for object release. After successful export, the value of mfxSurfaceHeader::SurfaceFlags will contain the actual export mode.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If export surface or surface is NULL.

MFX_ERR_UNSUPPORTED If requested export is not supported.

MFX_ERR_NOT_IMPLEMENTED If requested export is not implemented.

MFX_ERR_UNKNOWN Any internal error.

mfxSurfacePoolInterface

struct mfxSurfacePoolInterface

Specifies the surface pool interface.

Public Members

mfxHDL Context

The context of the surface pool interface. User should not touch (change, set, null) this pointer.

mfxStatus (*AddRef)(struct mfxSurfacePoolInterface *pool)

Increments the internal reference counter of the mfxSurfacePoolInterface. The mfxSurfacePoolInterface is not destroyed until the mfxSurfacePoolInterface is destroyed with mfxSurfacePoolInterface::Release function. mfxSurfacePoolInterface::AddRef should be used each time a new link to the mfxSurfacePoolInterface is created for proper management.

Param pool:

[in] Valid pool.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If pool is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Release)(struct mfxSurfacePoolInterface *pool)

Decrements the internal reference counter of the mfxSurfacePoolInterface. mfxSurfacePoolInterface::Release should be called after using the mfxSurfacePoolInterface::AddRef function to add a mfxSurfacePoolInterface or when allocation logic requires it. For example, call mfxSurfacePoolInterface::Release to release a mfxSurfacePoolInterface obtained with the mfxFrameSurfaceInterface::QueryInterface function.

Param pool:

[in] Valid pool.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If pool is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_ERR_UNDEFINED_BEHAVIOR If Reference Counter of

mfxSurfacePoolInterface

is zero before call.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetRefCounter)(struct mfxSurfacePoolInterface *pool, mfxU32 *counter)

Returns current reference counter of mfxSurfacePoolInterface structure.

Param pool:

[in] Valid pool.

Param counter:

[out] Sets counter to the current reference counter value.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If pool or counter is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*SetNumSurfaces)(struct mfxSurfacePoolInterface *pool, mfxU32 num_surfaces)

The function should be called by oneAPI Video Processing Library (oneVPL) components or application to specify how many surfaces it will use concurrently. Internally, oneVPL allocates surfaces in the shared pool according to the component’s policy set by mfxPoolAllocationPolicy. The exact moment of surfaces allocation is defined by the component and generally independent from that call.

Param pool:

[in] Valid pool.

Param num_surfaces:

[in] The number of surfaces required by the component.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If pool is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM If pool has MFX_ALLOCATION_UNLIMITED or MFX_ALLOCATION_LIMITED policy.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*RevokeSurfaces)(struct mfxSurfacePoolInterface *pool, mfxU32 num_surfaces)

The function should be called by oneVPL components when component is closed or reset and doesn’t need to use pool more. It helps to manage memory accordingly and release redundant memory. Important to specify the same number of surfaces which is requested during SetNumSurfaces call, otherwise it may lead to the pipeline stalls.

Param pool:

[in] Valid pool.

Param num_surfaces:

[in] The number of surfaces used by the component.

Return:

MFX_ERR_NONE If no error.

MFX_WRN_OUT_OF_RANGE If num_surfaces doesn’t equal to num_surfaces requested during SetNumSurfaces call.

MFX_ERR_NULL_PTR If pool is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM If pool has MFX_ALLOCATION_UNLIMITED or MFX_ALLOCATION_LIMITED policy.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetAllocationPolicy)(struct mfxSurfacePoolInterface *pool, mfxPoolAllocationPolicy *policy)

Returns current allocation policy.

Param pool:

[in] Valid pool.

Param policy:

[out] Sets policy to the current allocation policy value.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If pool or policy is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetMaximumPoolSize)(struct mfxSurfacePoolInterface *pool, mfxU32 *size)

Returns maximum pool size. In case of mfxPoolAllocationPolicy::MFX_ALLOCATION_UNLIMITED policy 0xFFFFFFFF will be returned.

Param pool:

[in] Valid pool.

Param size:

[out] Sets size to the maximum pool size value.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If pool or size is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetCurrentPoolSize)(struct mfxSurfacePoolInterface *pool, mfxU32 *size)

Returns current pool size.

Param pool:

[in] Valid pool.

Param size:

[out] Sets size to the current pool size value.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If pool or size is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfacePoolInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxHDL reserved[4]

Reserved for future use.

mfxMemoryInterface

struct mfxMemoryInterface

Public Members

mfxHDL Context

The context of the memory interface. User should not touch (change, set, null) this pointer.

mfxStructVersion Version

The version of the structure.

mfxStatus (*ImportFrameSurface)(struct mfxMemoryInterface *memory_interface, mfxSurfaceComponent surf_component, mfxSurfaceHeader *external_surface, mfxFrameSurface1 **imported_surface)

Imports an application-provided surface into mfxFrameSurface1 which may be used as input for encoding or video processing.

Since

This function is available since API version 2.10.

Param memory_interface:

[in] Valid memory interface.

Param surf_component:

[in] Surface component type. Required for allocating new surfaces from the appropriate pool.

Param external_surface:

[inout] Pointer to the mfxSurfaceXXX object describing the surface to be imported. All fields in mfxSurfaceHeader must be set by the application. mfxSurfaceHeader::SurfaceType is read by oneVPL runtime to determine which particular mfxSurfaceXXX structure is supplied. For example, if mfxSurfaceXXX::SurfaceType == MFX_SURFACE_TYPE_D3D11_TEX2D, then the handle will be interpreted as an object of type mfxSurfaceD3D11Tex2D. The application should set or clear other fields as specified in the corresponding structure description. After successful import, the value of mfxSurfaceHeader::SurfaceFlags will be replaced with the actual import type. It can be used to determine which import type (with or without copy) took place in the case of initial default setting, or if multiple import flags were OR’ed. All external sync operations on the ext_surface must be completed before calling this function.

Param imported_surface:

[out] Pointer to a valid mfxFrameSurface1 object containing the imported frame. imported_surface may be passed as an input to Encode or VPP processing operations.

Return:

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR If ext_surface or imported_surface are NULL.

MFX_ERR_INVALID_HANDLE If the corresponding session was not initialized.

MFX_ERR_UNSUPPORTED If surf_component is not one of [MFX_SURFACE_COMPONENT_ENCODE, MFX_SURFACE_COMPONENT_VPP_INPUT], or if

mfxSurfaceHeader::SurfaceType is not supported by oneVPL runtime for this operation.

mfxSurfaceTypesSupported

struct mfxSurfaceTypesSupported

This structure describes the supported surface types and modes.

Public Members

mfxStructVersion Version

Version of the structure.

mfxU16 NumSurfaceTypes

Number of supported surface types.

mfxU32 reserved[4]

Reserved for future use.

struct surftype

Public Members

mfxSurfaceType SurfaceType

Supported surface type.

mfxU32 reserved[6]

Reserved for future use.

mfxU16 NumSurfaceComponents

Number of supported surface components.

struct surfcomp

Public Members

mfxSurfaceComponent SurfaceComponent

Supported surface component.

mfxU32 SurfaceFlags

Supported surface flags for this component (may be OR’d).

mfxU32 reserved[7]

Reserved for future use.

mfxSurfaceHeader

struct mfxSurfaceHeader

Public Members

mfxSurfaceType SurfaceType

Set to the MFX_SURFACE_TYPE enum corresponding to the specific structure.

mfxU32 SurfaceFlags

Set to the MFX_SURFACE_FLAG enum (or combination) corresponding to the allowed import / export mode(s). Multiple flags may be combined with OR. Upon a successful Import or Export operation, this field will indicate the actual mode used.

mfxU32 StructSize

Size in bytes of the complete mfxSurfaceXXX structure.

mfxU16 NumExtParam

The number of extra configuration structures attached to the structure.

mfxExtBuffer **ExtParam

Points to an array of pointers to the extra configuration structures; see the ExtendedBufferID enumerator for a list of extended configurations.

mfxSurfaceInterface

struct mfxSurfaceInterface

Contains mfxSurfaceHeader and the callback functions AddRef, Release and GetRefCounter that the application may use to manage access to exported surfaces. These interfaces are only valid for surfaces obtained by mfxFrameSurfaceInterface::Export. They are not used for surface descriptions passed to function mfxMemoryInterface::ImportFrameSurface.

Public Members

mfxSurfaceHeader Header

Exported surface header. Contains description of current surface.

mfxStructVersion Version

The version of the structure.

mfxHDL Context

The context of the exported surface interface. User should not touch (change, set, null) this pointer.

mfxStatus (*AddRef)(struct mfxSurfaceInterface *surface)

Increments the internal reference counter of the surface. The surface is not destroyed until the surface is released using the mfxSurfaceInterface::Release function. mfxSurfaceInterface::AddRef should be used each time a new link to the surface is created (for example, copy structure) for proper surface management.

Param surface:

[in] Valid surface.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Release)(struct mfxSurfaceInterface *surface)

Decrements the internal reference counter of the surface. mfxSurfaceInterface::Release should be called after using the mfxSurfaceInterface::AddRef function to add a surface or when allocation logic requires it. For example, call mfxSurfaceInterface::Release to release a surface obtained with the mfxFrameSurfaceInterface::Export function.

Param surface:

[in] Valid surface.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNDEFINED_BEHAVIOR If Reference Counter of surface is zero before call.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetRefCounter)(struct mfxSurfaceInterface *surface, mfxU32 *counter)

Returns current reference counter of exported surface.

Param surface:

[in] Valid surface.

Param counter:

[out] Sets counter to the current reference counter value.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface or counter is NULL.

MFX_ERR_INVALID_HANDLE If mfxSurfaceInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Synchronize)(struct mfxSurfaceInterface *surface, mfxU32 wait)

This function is only valuable for surfaces which were exported in sharing mode (without a copy). Guarantees readiness of both the data (pixels) and any original mfxFrameSurface1 frame’s meta information (for example corruption flags) after a function completes.

Instead of MFXVideoCORE_SyncOperation, users may directly call the mfxSurfaceInterface::Synchronize function after the corresponding Decode or VPP function calls (MFXVideoDECODE_DecodeFrameAsync or MFXVideoVPP_RunFrameVPPAsync). The prerequisites to call the functions are:

• The main processing functions return MFX_ERR_NONE.

• A valid surface object.

Param surface:

[in] Valid surface.

Param wait:

[out] Wait time in milliseconds.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If any of surface is not valid object .

MFX_WRN_IN_EXECUTION If the given timeout is expired and the surface is not ready.

MFX_ERR_ABORTED If the specified asynchronous function aborted due to data dependency on a previous asynchronous function that did not complete.

MFX_ERR_UNKNOWN Any internal error.

mfxSurfaceD3D11Tex2D

struct mfxSurfaceD3D11Tex2D

Public Members

mfxHDL texture2D

Pointer to texture, type ID3D11Texture2D

mfxSurfaceVAAPI

struct mfxSurfaceVAAPI

Public Members

mfxHDL vaDisplay

Object of type VADisplay.

mfxU32 vaSurfaceID

Object of type VASurfaceID.

mfxSurfaceOpenCLImg2D

struct mfxSurfaceOpenCLImg2D

Public Members

mfxHDL ocl_context

Pointer to OpenCL context, type cl_context

mfxHDL ocl_command_queue

Pointer to OpenCL command queue, type cl_command_queue

mfxHDL ocl_image[4]

Pointer to OpenCL 2D images, type cl_mem

mfxU32 ocl_image_num

Number of valid images (planes), depends on color format

mfxExtSurfaceOpenCLImg2DExportDescription

struct mfxExtSurfaceOpenCLImg2DExportDescription

Optional extension buffer, which can be attached to mfxSurfaceHeader::ExtParam (second parameter of mfxFrameSurfaceInterface::Export) in order to pass OCL parameters during mfxFrameSurface1 exporting to OCL surface. If buffer is not provided all resources will be created by oneAPI Video Processing Library (oneVPL) RT internally.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_EXPORT_SHARING_DESC_OCL.

mfxHDL ocl_context

Pointer to OpenCL context, type cl_context

mfxHDL ocl_command_queue

Pointer to OpenCL command queue, type cl_command_queue