.rst .pdf

open issue suggest edit

Contents

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.

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.

Parameters

• [in] pthis: Pointer to the allocator object.

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

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

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

Locks a frame and returns its pointer.

Return

MFX_ERR_NONE The function successfully locked the memory block.

MFX_ERR_LOCK_MEMORY This function failed to lock the frame.

Parameters

• [in] pthis: Pointer to the allocator object.

• [in] mid: Memory block ID.

• [out] ptr: Pointer to the returned frame structure.

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

Unlocks a frame and invalidates the specified frame structure.

Return

MFX_ERR_NONE The function successfully locked the memory block.

Parameters

• [in] pthis: Pointer to the allocator object.

• [in] mid: Memory block ID.

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

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.

Return

MFX_ERR_NONE The function successfully returned the OS-specific handle.

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

Parameters

• [in] pthis: Pointer to the allocator object.

• [in] mid: Memory block ID.

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

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

De-allocates all allocated frames.

Return

MFX_ERR_NONE The function successfully de-allocated the memory block.

Parameters

• [in] pthis: Pointer to the allocator object.

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

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).

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.

mfxU16 CropY

Y coordinate.

mfxU16 CropW

Width in pixels.

mfxU16 CropH

Height in pixels.

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.

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.

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 (*Release) function. (*AddRef) should be used each time a new link to the surface is created (for example, copy structure) for proper surface management.

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.

Parameters

• [in] surface: Valid surface.

mfxStatus (*Release)(mfxFrameSurface1 *surface)

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

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.

Parameters

• [in] surface: Valid surface.

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

Returns current reference counter of mfxFrameSurface1 structure.

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.

Parameters

• [in] surface: Valid surface.

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

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.

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.

Parameters

• [in] surface: Valid surface.

• [out] flags: Specify mapping mode.

• [out] surface->Info.Data: Pointers set to actual pixel data.

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.

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.

Parameters

• [in] surface: Valid surface.

• [out] surface->Info.Data: Pointers set to NULL.

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 (*Release).

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.

Parameters

• [in] surface: Valid surface.

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

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

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 (*Release).

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.

Parameters

• [in] surface: Valid surface.

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

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

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 (*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.

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.

Parameters

• [in] surface: Valid surface.

• [out] wait: Wait time in milliseconds.

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.

Parameters

• [in] sts: The status of completed operation.

Type Definitions Implementation Management