Functions

Implementation Capabilities

mfxHDL *MFXQueryImplsDescription(mfxImplCapsDeliveryFormat format, mfxU32 *num_impls)

This function delivers implementation capabilities in the requested format according to the format value.

Return

Array of handles to the capability report or NULL in case of unsupported format or NULL num_impls pointer. Lenght of array equals to num_impls.

Parameters
  • [in] format: Format in which capabilities must be delivered. See mfxImplCapsDeliveryFormat for more details.

  • [out] num_impls: Number of the implementations.

Important

Function MFXQueryImplsDescription() is mandatory for any implementation.

mfxStatus MFXReleaseImplDescription(mfxHDL hdl)

This function destroys the handle allocated by the MFXQueryImplsCapabilities function. Implementation must remember which handles are released. Once th last handle is released, this function must release memory allocated for the array of handles.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] hdl: Handle to destroy. Can be equal to NULL.

Important

Function MFXReleaseImplDescription() is mandatory for any implementation.

Session Management

mfxStatus MFXInit(mfxIMPL impl, mfxVersion *ver, mfxSession *session)

This function creates and initializes an SDK session. Call this function before calling any other SDK function. If the desired implementation specified by impl is MFX_IMPL_AUTO, the function will search for the platform-specific SDK implementation. If the function cannot find it, it will use the software implementation.

The ver argument indicates the desired version of the library implementation. The loaded SDK will have an API version compatible to the specified version (equal in the major version number, and no less in the minor version number.) If the desired version is not specified, the default is to use the API version from the SDK release, with which an application is built.

We recommend that production applications always specify the minimum API version that meets their functional requirements. For example, if an application uses only H.264 decoding as described in API v1.0, have the application initialize the library with API v1.0. This ensures backward compatibility.

Return

MFX_ERR_NONE The function completed successfully. The output parameter contains the handle of the session.

MFX_ERR_UNSUPPORTED The function cannot find the desired SDK implementation or version.

Parameters
  • [in] impl: mfxIMPL enumerator that indicates the desired SDK implementation.

  • [in] ver: Pointer to the minimum library version or zero, if not specified.

  • [out] session: Pointer to the SDK session handle.

mfxStatus MFXInitEx(mfxInitParam par, mfxSession *session)

This function creates and initializes an SDK session. Call this function before calling any other SDK functions. If the desired implementation specified by par. Implementation is MFX_IMPL_AUTO, the function will search for the platform-specific SDK implementation. If the function cannot find it, it will use the software implementation.

The argument par.Version indicates the desired version of the library implementation. The loaded SDK will have an API version compatible to the specified version (equal in the major version number, and no less in the minor version number.) If the desired version is not specified, the default is to use the API version from the SDK release, with which an application is built.

We recommend that production applications always specify the minimum API version that meets their functional requirements. For example, if an application uses only H.264 decoding as described in API v1.0, have the application initialize the library with API v1.0. This ensures backward compatibility.

The argument par.ExternalThreads specifies threading mode. Value 0 means that SDK should internally create and handle work threads (this essentially equivalent of regular MFXInit). I

Return

MFX_ERR_NONE The function completed successfully. The output parameter contains the handle of the session.

MFX_ERR_UNSUPPORTED The function cannot find the desired SDK implementation or version.

Parameters
  • [in] par: mfxInitParam structure that indicates the desired SDK implementation, minimum library version and desired threading mode.

  • [out] session: Pointer to the SDK session handle.

Important

Function MFXInitEx() is mandatory for any implementation.

mfxStatus MFXClose(mfxSession session)

This function completes and deinitializes an SDK session. Any active tasks in execution or in queue are aborted. The application cannot call any SDK function after this function.

All child sessions must be disjoined before closing a parent session.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

Important

Function MFXClose() is mandatory for any implementation.

mfxStatus MFXQueryIMPL(mfxSession session, mfxIMPL *impl)

This function returns the implementation type of a given session.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [out] impl: Pointer to the implementation type

mfxStatus MFXQueryVersion(mfxSession session, mfxVersion *version)

This function returns the SDK implementation version.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [out] version: Pointer to the returned implementation version.

mfxStatus MFXJoinSession(mfxSession session, mfxSession child)

This function joins the child session to the current session.

After joining, the two sessions share thread and resource scheduling for asynchronous operations. However, each session still maintains its own device manager and buffer/frame allocator. Therefore, the application must use a compatible device manager and buffer/frame allocator to share data between two joined sessions.

The application can join multiple sessions by calling this function multiple times. When joining the first two sessions, the current session becomes the parent responsible for thread and resource scheduling of any later joined sessions.

Joining of two parent sessions is not supported.

Return

MFX_ERR_NONE The function completed successfully.

MFX_WRN_IN_EXECUTION Active tasks are executing or in queue in one of the sessions. Call this function again after all tasks are completed.

MFX_ERR_UNSUPPORTED The child session cannot be joined with the current session.

Parameters
  • [inout] session: The current session handle.

  • [in] child: The child session handle to be joined

mfxStatus MFXDisjoinSession(mfxSession session)

This function removes the joined state of the current session. After disjoining, the current session becomes independent. The application must ensure there is no active task running in the session before calling this function.

Return

MFX_ERR_NONE The function completed successfully.

MFX_WRN_IN_EXECUTION Active tasks are executing or in queue in one of the sessions. Call this function again after all tasks are completed.

MFX_ERR_UNDEFINED_BEHAVIOR The session is independent, or this session is the parent of all joined sessions.

Parameters
  • [inout] session: The current session handle.

mfxStatus MFXCloneSession(mfxSession session, mfxSession *clone)

This function creates a clean copy of the current session. The cloned session is an independent session. It does not inherit any user-defined buffer, frame allocator, or device manager handles from the current session. This function is a light-weight equivalent of MFXJoinSession after MFXInit.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: The current session handle.

  • [out] clone: Pointer to the cloned session handle.

mfxStatus MFXSetPriority(mfxSession session, mfxPriority priority)

This function sets the current session priority.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: The current session handle.

  • [in] priority: Priority value.

mfxStatus MFXGetPriority(mfxSession session, mfxPriority *priority)

This function returns the current session priority.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: The current session handle.

  • [out] priority: Pointer to the priority value.

VideoCORE

mfxStatus MFXVideoCORE_SetFrameAllocator(mfxSession session, mfxFrameAllocator *allocator)

This function sets the external allocator callback structure for frame allocation.If the allocator argument is NULL, the SDK uses the default allocator, which allocates frames from system memory or hardware devices.The behavior of the SDK is undefined if it uses this function while the previous allocator is in use.A general guideline is to set the allocator immediately after initializing the session.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [in] allocator: Pointer to the mfxFrameAllocator structure

mfxStatus MFXVideoCORE_SetHandle(mfxSession session, mfxHandleType type, mfxHDL hdl)

This function sets any essential system handle that SDK might use. If the specified system handle is a COM interface, the reference counter of the COM interface will increase. The counter will decrease when the SDK session closes.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_UNDEFINED_BEHAVIOR The same handle is redefined. For example, the function has been called twice with the same handle type or internal handle has been created by the SDK before this function call.

Parameters
  • [in] session: SDK session handle.

  • [in] type: Handle type

  • [in] hdl: Handle to be set

mfxStatus MFXVideoCORE_GetHandle(mfxSession session, mfxHandleType type, mfxHDL *hdl)

This function obtains system handles previously set by the MFXVideoCORE_SetHandle function. If the handler is a COM interface, the reference counter of the interface increases. The calling application must release the COM interface.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_UNDEFINED_BEHAVIOR Specified handle type not found.

Parameters
  • [in] session: SDK session handle.

  • [in] type: Handle type

  • [in] hdl: Pointer to the handle to be set

mfxStatus MFXVideoCORE_QueryPlatform(mfxSession session, mfxPlatform *platform)

This function returns information about current hardware platform.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [out] platform: Pointer to the mfxPlatform structure

mfxStatus MFXVideoCORE_SyncOperation(mfxSession session, mfxSyncPoint syncp, mfxU32 wait)

This function initiates execution of an asynchronous function not already started and returns the status code after the specified asynchronous operation completes. If wait is zero, the function returns immediately.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NONE_PARTIAL_OUTPUT The function completed successfully, bitstream contains a portion of the encoded frame according to required granularity.

MFX_WRN_IN_EXECUTION The specified asynchronous function is in execution.

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

Parameters
  • [in] session: SDK session handle.

  • [in] syncp: Sync point

  • [in] wait: wait time in milliseconds

Important

Function MFXVideoCORE_SyncOperation() is mandatory for any implementation.

Memory

mfxStatus MFXMemory_GetSurfaceForVPP(mfxSession session, mfxFrameSurface1 **surface)

This function returns surface which can be used as input for VPP. VPP should be initialized before this call. Surface should be released with mfxFrameSurface1::FrameInterface.Release(…) after usage. Value of mfxFrameSurface1::Data.Locked for returned surface is 0.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If session was not initialized.

MFX_ERR_NOT_INITIALIZED If VPP wasn’t initialized (allocator needs to know surface size from somewhere).

MFX_ERR_MEMORY_ALLOC In case of any other internal allocation error.

Parameters
  • [in] session: SDK session handle.

  • [out] surface: Pointer is set to valid mfxFrameSurface1 object.

mfxStatus MFXMemory_GetSurfaceForEncode(mfxSession session, mfxFrameSurface1 **surface)

This function returns surface which can be used as input for Encoder. Encoder should be initialized before this call. Surface should be released with mfxFrameSurface1::FrameInterface.Release(…) after usage. Value of mfxFrameSurface1::Data.Locked for returned surface is 0.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If session was not initialized.

MFX_ERR_NOT_INITIALIZED If Encoder wasn’t initialized (allocator needs to know surface size from somewhere).

MFX_ERR_MEMORY_ALLOC In case of any other internal allocation error.

Parameters
  • [in] session: SDK session handle.

  • [out] surface: Pointer is set to valid mfxFrameSurface1 object.

mfxStatus MFXMemory_GetSurfaceForDecode(mfxSession session, mfxFrameSurface1 **surface)

This function returns surface which can be used as input for Decoder. Decoder should be initialized before this call. Surface should be released with mfxFrameSurface1::FrameInterface.Release(…) after usage. Value of mfxFrameSurface1::Data.Locked for returned surface is 0.’ Note: this function was added to simplify transition from legacy surface management to proposed internal allocation approach. Previously, user allocated surfaces for working pool and fed decoder with them in DecodeFrameAsync calls. With MFXMemory_GetSurfaceForDecode it is possible to change the existing pipeline just changing source of work surfaces. Newly developed applications should prefer direct usage of DecodeFrameAsync with internal allocation.’.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR If surface is NULL.

MFX_ERR_INVALID_HANDLE If session was not initialized.

MFX_ERR_NOT_INITIALIZED If Decoder wasn’t initialized (allocator needs to know surface size from somewhere).

MFX_ERR_MEMORY_ALLOC In case of any other internal allocation error.

Parameters
  • [in] session: SDK session handle.

  • [out] surface: Pointer is set to valid mfxFrameSurface1 object.

VideoENCODE

mfxStatus MFXVideoENCODE_Query(mfxSession session, mfxVideoParam *in, mfxVideoParam *out)

This function works in either of four modes:

If the in pointer is zero, the function returns the class configurability in the output structure. A non-zero value in each field of the output structure that the SDK implementation can configure the field with Init.

If the in parameter is non-zero, the function checks the validity of the fields in the input structure. Then the function returns the corrected values in the output structure. If there is insufficient information to determine the validity or correction is impossible, the function zeroes the fields. This feature can verify whether the SDK implementation supports certain profiles, levels or bitrates.

If the in parameter is non-zero and mfxExtEncoderResetOption structure is attached to it, then the function queries for the outcome of the MFXVideoENCODE_Reset function and returns it in the mfxExtEncoderResetOption structure attached to out. The query function succeeds if such reset is possible and returns error otherwise. Unlike other modes that are independent of the SDK encoder state, this one checks if reset is possible in the present SDK encoder state. This mode also requires completely defined mfxVideoParam structure, unlike other modes that support partially defined configurations. See mfxExtEncoderResetOption description for more details.

If the in parameter is non-zero and mfxExtEncoderCapability structure is attached to it, then the function returns encoder capability in mfxExtEncoderCapability structure attached to out. It is recommended to fill in mfxVideoParam structure and set hardware acceleration device handle before calling the function in this mode.

The application can call this function before or after it initializes the encoder. The CodecId field of the output structure is a mandated field (to be filled by the application) to identify the coding standard.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_UNSUPPORTED The function failed to identify a specific implementation for the required features.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters
  • [in] session: SDK session handle.

  • [in] in: Pointer to the mfxVideoParam structure as input

  • [out] out: Pointer to the mfxVideoParam structure as output

Important

The MFXVideoENCODE_Query() function is mandatory when implementing an encoder.

mfxStatus MFXVideoENCODE_QueryIOSurf(mfxSession session, mfxVideoParam *par, mfxFrameAllocRequest *request)

This function returns minimum and suggested numbers of the input frame surfaces required for encoding initialization and their type. Init will call the external allocator for the required frames with the same set of numbers. The use of this function is recommended. For more information, see the section Working with hardware acceleration. This function does not validate I/O parameters except those used in calculating the number of input surfaces.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters

mfxStatus MFXVideoENCODE_Init(mfxSession session, mfxVideoParam *par)

This function allocates memory and prepares tables and necessary structures for encoding. This function also does extensive validation to ensure if the configuration, as specified in the input parameters, is supported.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

MFX_ERR_UNDEFINED_BEHAVIOR The function is called twice without a close;

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the mfxVideoParam structure

Important

The MFXVideoENCODE_Init() function is mandatory when implementing an encoder.

mfxStatus MFXVideoENCODE_Reset(mfxSession session, mfxVideoParam *par)

This function stops the current encoding operation and restores internal structures or parameters for a new encoding operation, possibly with new parameters.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM The function detected that provided by the application video parameters are incompatible with initialization parameters. Reset requires additional memory allocation and cannot be executed. The application should close the SDK component and then reinitialize it.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the mfxVideoParam structure

mfxStatus MFXVideoENCODE_Close(mfxSession session)

This function terminates the current encoding operation and de-allocates any internal tables or structures.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

Important

The MFXVideoENCODE_Close() function is mandatory when implementing an encoder.

mfxStatus MFXVideoENCODE_GetVideoParam(mfxSession session, mfxVideoParam *par)

This function retrieves current working parameters to the specified output structure. If extended buffers are to be returned, the application must allocate those extended buffers and attach them as part of the output structure. The application can retrieve a copy of the bitstream header, by attaching the mfxExtCodingOptionSPSPPS structure to the mfxVideoParam structure.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the corresponding parameter structure

mfxStatus MFXVideoENCODE_GetEncodeStat(mfxSession session, mfxEncodeStat *stat)

This function obtains statistics collected during encoding.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [in] stat: Pointer to the mfxEncodeStat structure

mfxStatus MFXVideoENCODE_EncodeFrameAsync(mfxSession session, mfxEncodeCtrl *ctrl, mfxFrameSurface1 *surface, mfxBitstream *bs, mfxSyncPoint *syncp)

This function takes a single input frame in either encoded or display order and generates its output bitstream. In the case of encoded ordering the mfxEncodeCtrl structure must specify the explicit frame type. In the case of display ordering, this function handles frame order shuffling according to the GOP structure parameters specified during initialization.

Since encoding may process frames differently from the input order, not every call of the function generates output and the function returns MFX_ERR_MORE_DATA. If the encoder needs to cache the frame, the function locks the frame. The application should not alter the frame until the encoder unlocks the frame. If there is output (with return status MFX_ERR_NONE), the return is a frame worth of bitstream.

It is the calling application’s responsibility to ensure that there is sufficient space in the output buffer. The value BufferSizeInKB in the mfxVideoParam structure at encoding initialization specifies the maximum possible size for any compressed frames. This value can also be obtained from MFXVideoENCODE_GetVideoParam after encoding initialization.

To mark the end of the encoding sequence, call this function with a NULL surface pointer. Repeat the call to drain any remaining internally cached bitstreams (one frame at a time) until MFX_ERR_MORE_DATA is returned.

This function is asynchronous.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NOT_ENOUGH_BUFFER The bitstream buffer size is insufficient.

MFX_ERR_MORE_DATA The function requires more data to generate any output.

MFX_ERR_DEVICE_LOST Hardware device was lost; See Working with Microsoft* DirectX* Applications section for further information.

MFX_WRN_DEVICE_BUSY Hardware device is currently busy. Call this function again in a few milliseconds.

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM Inconsistent parameters detected not conforming to Appendix A.

Parameters
  • [in] session: SDK session handle.

  • [in] ctrl: Pointer to the mfxEncodeCtrl structure for per-frame encoding control; this parameter is optional(it can be NULL) if the encoder works in the display order mode.

  • [in] surface: Pointer to the frame surface structure

  • [out] bs: Pointer to the output bitstream

  • [out] syncp: Pointer to the returned sync point associated with this operation

Important

The MFXVideoENCODE_EncodeFrameAsync() function is mandatory when implementing an encoder.

VideoDECODE

mfxStatus MFXVideoDECODE_Query(mfxSession session, mfxVideoParam *in, mfxVideoParam *out)

This function works in one of two modes:

1.If the in pointer is zero, the function returns the class configurability in the output structure. A non-zero value in each field of the output structure indicates that the field is configurable by the SDK implementation with the MFXVideoDECODE_Init function).

2.If the in parameter is non-zero, the function checks the validity of the fields in the input structure. Then the function returns the corrected values to the output structure. If there is insufficient information to determine the validity or correction is impossible, the function zeros the fields. This feature can verify whether the SDK implementation supports certain profiles, levels or bitrates.

The application can call this function before or after it initializes the decoder. The CodecId field of the output structure is a mandated field (to be filled by the application) to identify the coding standard.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_UNSUPPORTED The function failed to identify a specific implementation for the required features.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The decoding may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters
  • [in] session: SDK session handle.

  • [in] in: Pointer to the mfxVideoParam structure as input

  • [out] out: Pointer to the mfxVideoParam structure as output

Important

The MFXVideoDECODE_Query() is mandatory when implementing a decoder.

mfxStatus MFXVideoDECODE_DecodeHeader(mfxSession session, mfxBitstream *bs, mfxVideoParam *par)

This function parses the input bitstream and fills the mfxVideoParam structure with appropriate values, such as resolution and frame rate, for the Init function. The application can then pass the resulting structure to the MFXVideoDECODE_Init function for decoder initialization.

An application can call this function at any time before or after decoder initialization. If the SDK finds a sequence header in the bitstream, the function moves the bitstream pointer to the first bit of the sequence header. Otherwise, the function moves the bitstream pointer close to the end of the bitstream buffer but leaves enough data in the buffer to avoid possible loss of start code.

The CodecId field of the mfxVideoParam structure is a mandated field (to be filled by the application) to identify the coding standard.

The application can retrieve a copy of the bitstream header, by attaching the mfxExtCodingOptionSPSPPS structure to the mfxVideoParam structure.

Return

MFX_ERR_NONE The function successfully filled structure. It does not mean that the stream can be decoded by SDK. The application should call MFXVideoDECODE_Query function to check if decoding of the stream is supported.

MFX_ERR_MORE_DATA The function requires more bitstream data

MFX_ERR_UNSUPPORTED CodecId field of the

mfxVideoParam structure indicates some unsupported codec.

MFX_ERR_INVALID_HANDLE session is not initialized

MFX_ERR_NULL_PTR bs or par pointer is NULL.

Parameters
  • [in] session: SDK session handle.

  • [in] bs: Pointer to the bitstream

  • [in] par: Pointer to the mfxVideoParam structure

mfxStatus MFXVideoDECODE_QueryIOSurf(mfxSession session, mfxVideoParam *par, mfxFrameAllocRequest *request)

This function returns minimum and suggested numbers of the output frame surfaces required for decoding initialization and their type. Init will call the external allocator for the required frames with the same set of numbers. The use of this function is recommended. For more information, see the section Working with hardware acceleration. The CodecId field of the mfxVideoParam structure is a mandated field (to be filled by the application) to identify the coding standard. This function does not validate I/O parameters except those used in calculating the number of output surfaces.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters

mfxStatus MFXVideoDECODE_Init(mfxSession session, mfxVideoParam *par)

This function allocates memory and prepares tables and necessary structures for encoding. This function also does extensive validation to ensure if the configuration, as specified in the input parameters, is supported.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

MFX_ERR_UNDEFINED_BEHAVIOR The function is called twice without a close;

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the mfxVideoParam structure

Important

The MFXVideoDECODE_Init() is mandatory when implementing a decoder.

mfxStatus MFXVideoDECODE_Reset(mfxSession session, mfxVideoParam *par)

This function stops the current decoding operation and restores internal structures or parameters for a new decoding operation Reset serves two purposes: It recovers the decoder from errors. It restarts decoding from a new position The function resets the old sequence header (sequence parameter set in H.264, or sequence header in MPEG-2 and VC-1). The decoder will expect a new sequence header before it decodes the next frame and will skip any bitstream before encountering the new sequence header.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected that video parameters are wrong or they conflict with initialization parameters. Reset is impossible.

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM The function detected that provided by the application video parameters are incompatible with initialization parameters. Reset requires additional memory allocation and cannot be executed. The application should close the SDK component and then reinitialize it.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the mfxVideoParam structure

mfxStatus MFXVideoDECODE_Close(mfxSession session)

This function terminates the current decoding operation and de-allocates any internal tables or structures.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

Important

The MFXVideoDECODE_Close() is mandatory when implementing a decoder.

mfxStatus MFXVideoDECODE_GetVideoParam(mfxSession session, mfxVideoParam *par)

This function retrieves current working parameters to the specified output structure. If extended buffers are to be returned, the application must allocate those extended buffers and attach them as part of the output structure. The application can retrieve a copy of the bitstream header, by attaching the mfxExtCodingOptionSPSPPS structure to the mfxVideoParam structure.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the corresponding parameter structure

mfxStatus MFXVideoDECODE_GetDecodeStat(mfxSession session, mfxDecodeStat *stat)

This function obtains statistics collected during decoding.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [in] stat: Pointer to the mfxDecodeStat structure

mfxStatus MFXVideoDECODE_SetSkipMode(mfxSession session, mfxSkipMode mode)

This function sets the decoder skip mode. The application may use it to increase decoding performance by sacrificing output quality. The rising of skip level firstly results in skipping of some decoding operations like deblocking and then leads to frame skipping; firstly, B then P. Particular details are platform dependent.

Return

MFX_ERR_NONE The function completed successfully and the output surface is ready for decoding

MFX_WRN_VALUE_NOT_CHANGED The skip mode is not affected as the maximum or minimum skip range is reached.

Parameters
  • [in] session: SDK session handle.

  • [in] mode: Decoder skip mode. See the mfxSkipMode enumerator for details.

mfxStatus MFXVideoDECODE_GetPayload(mfxSession session, mfxU64 *ts, mfxPayload *payload)

This function extracts user data (MPEG-2) or SEI (H.264) messages from the bitstream. Internally, the decoder implementation stores encountered user data or SEI messages. The application may call this function multiple times to retrieve the user data or SEI messages, one at a time.

If there is no payload available, the function returns with payload->NumBit=0.

Return

MFX_ERR_NONE The function completed successfully and the output buffer is ready for decoding

MFX_ERR_NOT_ENOUGH_BUFFER The payload buffer size is insufficient.

Parameters
  • [in] session: SDK session handle.

  • [in] ts: Pointer to the user data time stamp in units of 90 KHz; divide ts by 90,000 (90 KHz) to obtain the time in seconds; the time stamp matches the payload with a specific decoded frame.

  • [in] payload: Pointer to the mfxPayload structure; the payload contains user data in MPEG-2 or SEI messages in H.264.

mfxStatus MFXVideoDECODE_DecodeFrameAsync(mfxSession session, mfxBitstream *bs, mfxFrameSurface1 *surface_work, mfxFrameSurface1 **surface_out, mfxSyncPoint *syncp)

This function decodes the input bitstream to a single output frame.

The surface_work parameter provides a working frame buffer for the decoder. The application should allocate the working frame buffer, which stores decoded frames. If the function requires caching frames after decoding, the function locks the frames and the application must provide a new frame buffer in the next call.

If, and only if, the function returns MFX_ERR_NONE, the pointer surface_out points to the output frame in the display order. If there are no further frames, the function will reset the pointer to zero and return the appropriate status code.

Before decoding the first frame, a sequence header(sequence parameter set in H.264 or sequence header in MPEG-2 and VC-1) must be present. The function skips any bitstreams before it encounters the new sequence header.

The input bitstream bs can be of any size. If there are not enough bits to decode a frame, the function returns MFX_ERR_MORE_DATA, and consumes all input bits except if a partial start code or sequence header is at the end of the buffer. In this case, the function leaves the last few bytes in the bitstream buffer. If there is more incoming bitstream, the application should append the incoming bitstream to the bitstream buffer. Otherwise, the application should ignore the remaining bytes in the bitstream buffer and apply the end of stream procedure described below.

The application must set bs to NULL to signal end of stream. The application may need to call this function several times to drain any internally cached frames until the function returns MFX_ERR_MORE_DATA.

If more than one frame is in the bitstream buffer, the function decodes until the buffer is consumed. The decoding process can be interrupted for events such as if the decoder needs additional working buffers, is readying a frame for retrieval, or encountering a new header. In these cases, the function returns appropriate status code and moves the bitstream pointer to the remaining data.

The decoder may return MFX_ERR_NONE without taking any data from the input bitstream buffer. If the application appends additional data to the bitstream buffer, it is possible that the bitstream buffer may contain more than 1 frame. It is recommended that the application invoke the function repeatedly until the function returns MFX_ERR_MORE_DATA, before appending any more data to the bitstream buffer. This function is asynchronous.

Return

MFX_ERR_NONE The function completed successfully and the output surface is ready for decoding

MFX_ERR_MORE_DATA The function requires more bitstream at input before decoding can proceed.

MFX_ERR_MORE_SURFACE The function requires more frame surface at output before decoding can proceed.

MFX_ERR_DEVICE_LOST Hardware device was lost; See the Working with Microsoft* DirectX* Applications section for further information.

MFX_WRN_DEVICE_BUSY Hardware device is currently busy. Call this function again in a few milliseconds.

MFX_WRN_VIDEO_PARAM_CHANGED The decoder detected a new sequence header in the bitstream. Video parameters may have changed.

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM The decoder detected incompatible video parameters in the bitstream and failed to follow them.

MFX_ERR_REALLOC_SURFACE Bigger surface_work required. May be returned only if

mfxInfoMFX::EnableReallocRequest was set to ON during initialization.

Parameters
  • [in] session: SDK session handle.

  • [in] bs: Pointer to the input bitstream

  • [in] surface_work: Pointer to the working frame buffer for the decoder

  • [out] surface_out: Pointer to the output frame in the display order

  • [out] syncp: Pointer to the sync point associated with this operation

Important

The MFXVideoDECODE_DecodeFrameAsync() is mandatory when implementing a decoder.

VideoVPP

mfxStatus MFXVideoVPP_Query(mfxSession session, mfxVideoParam *in, mfxVideoParam *out)

This function works in one of two modes:

1.If the in pointer is zero, the function returns the class configurability in the output structure. A non-zero value in a field indicates that the SDK implementation can configure it with Init.

2.If the in parameter is non-zero, the function checks the validity of the fields in the input structure. Then the function returns the corrected values to the output structure. If there is insufficient information to determine the validity or correction is impossible, the function zeroes the fields.

The application can call this function before or after it initializes the preprocessor.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_UNSUPPORTED The SDK implementation does not support the specified configuration.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The video processing may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters
  • [in] session: SDK session handle.

  • [in] in: Pointer to the mfxVideoParam structure as input

  • [out] out: Pointer to the mfxVideoParam structure as output

Important

The MFXVideoVPP_Query() function is mandatory when implementing a VPP filter.

mfxStatus MFXVideoVPP_QueryIOSurf(mfxSession session, mfxVideoParam *par, mfxFrameAllocRequest request[2])

This function returns minimum and suggested numbers of the input frame surfaces required for video processing initialization and their type. The parameter request[0] refers to the input requirements; request[1] refers to output requirements. Init will call the external allocator for the required frames with the same set of numbers. The use of this function is recommended. For more information, see the section Working with hardware acceleration. This function does not validate I/O parameters except those used in calculating the number of input surfaces.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The video processing may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the mfxVideoParam structure as input

  • [in] request: Pointer to the mfxFrameAllocRequest structure; use request[0] for input requirements and request[1] for output requirements for video processing.

mfxStatus MFXVideoVPP_Init(mfxSession session, mfxVideoParam *par)

This function allocates memory and prepares tables and necessary structures for video processing. This function also does extensive validation to ensure if the configuration, as specified in the input parameters, is supported.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected invalid video parameters. These parameters may be out of the valid range, or the combination of them resulted in incompatibility. Incompatibility not resolved.

MFX_WRN_PARTIAL_ACCELERATION The underlying hardware does not fully support the specified video parameters. The video processing may be partially accelerated. Only SDK hardware implementations may return this status code.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

MFX_ERR_UNDEFINED_BEHAVIOR The function is called twice without a close.

MFX_WRN_FILTER_SKIPPED The VPP skipped one or more filters requested by the application.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the mfxVideoParam structure

Important

The MFXVideoVPP_Init() function is mandatory when implementing a VPP filter.

mfxStatus MFXVideoVPP_Reset(mfxSession session, mfxVideoParam *par)

This function stops the current video processing operation and restores internal structures or parameters for a new operation.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_INVALID_VIDEO_PARAM The function detected that video parameters are wrong or they conflict with initialization parameters. Reset is impossible.

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM The function detected that provided by the application video parameters are incompatible with initialization parameters. Reset requires additional memory allocation and cannot be executed. The application should close the SDK component and then reinitialize it.

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM The function detected some video parameters were incompatible with others; incompatibility resolved.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the mfxVideoParam structure

mfxStatus MFXVideoVPP_Close(mfxSession session)

This function terminates the current video processing operation and de-allocates any internal tables or structures.

Return

MFX_ERR_NONE

The function completed successfully.

Parameters
  • [in] session: SDK session handle.

Important

The MFXVideoVPP_Close() function is mandatory when implementing a VPP filter.

mfxStatus MFXVideoVPP_GetVideoParam(mfxSession session, mfxVideoParam *par)

This function retrieves current working parameters to the specified output structure. If extended buffers are to be returned, the application must allocate those extended buffers and attach them as part of the output structure.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [in] par: Pointer to the corresponding parameter structure

mfxStatus MFXVideoVPP_GetVPPStat(mfxSession session, mfxVPPStat *stat)

This function obtains statistics collected during video processing.

Return

MFX_ERR_NONE The function completed successfully.

Parameters
  • [in] session: SDK session handle.

  • [in] stat: Pointer to the mfxVPPStat structure

mfxStatus MFXVideoVPP_RunFrameVPPAsync(mfxSession session, mfxFrameSurface1 *in, mfxFrameSurface1 *out, mfxExtVppAuxData *aux, mfxSyncPoint *syncp)

This function processes a single input frame to a single output frame. Retrieval of the auxiliary data is optional; the encoding process may use it. The video processing process may not generate an instant output given an input. See section Video Processing Procedures for details on how to correctly send input and retrieve output. At the end of the stream, call this function with the input argument in=NULL to retrieve any remaining frames, until the function returns MFX_ERR_MORE_DATA. This function is asynchronous.

Return

MFX_ERR_NONE The output frame is ready after synchronization.

MFX_ERR_MORE_DATA Need more input frames before VPP can produce an output

MFX_ERR_MORE_SURFACE The output frame is ready after synchronization. Need more surfaces at output for additional output frames available.

MFX_ERR_DEVICE_LOST Hardware device was lost; See the Working with Microsoft* DirectX* Applications section for further information.

MFX_WRN_DEVICE_BUSY Hardware device is currently busy. Call this function again in a few milliseconds.

Parameters
  • [in] session: SDK session handle.

  • [in] in: Pointer to the input video surface structure

  • [out] out: Pointer to the output video surface structure

  • [in] aux: Optional pointer to the auxiliary data structure

  • [out] syncp: Pointer to the output sync point

Important

The MFXVideoVPP_RunFrameVPPAsync() function is mandatory when implementing a VPP filter.

Adapters

mfxStatus MFXQueryAdapters(mfxComponentInfo *input_info, mfxAdaptersInfo *adapters)

This function returns a list of adapters that are suitable to handle workload input_info. The list is sorted in priority order, with iGPU given the highest precedence. This rule may change in the future. If input_info pointer is NULL, the list of all available adapters will be returned.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR input_info or adapters pointer is NULL.

MFX_ERR_NOT_FOUND No suitable adapters found.

MFX_WRN_OUT_OF_RANGE Not enough memory to report back entire list of adapters. In this case as many adapters as possible will be returned.

Parameters
  • [in] input_info: Pointer to workload description. See mfxComponentInfo description for details.

  • [out] adapters: Pointer to output description of all suitable adapters for input workload. See mfxAdaptersInfo description for details.

mfxStatus MFXQueryAdaptersDecode(mfxBitstream *bitstream, mfxU32 codec_id, mfxAdaptersInfo *adapters)

This function returns list of adapters that are suitable to decode input bitstream. The list is sorted in priority order, with iGPU given the highest precedence. This rule may change in the . This function is a simplification of MFXQueryAdapters, because bitstream is a description of the workload itself.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR bitstream or adapters pointer is NULL.

MFX_ERR_NOT_FOUND No suitable adapters found.

MFX_WRN_OUT_OF_RANGE Not enough memory to report back entire list of adapters. In this case as many adapters as possible will be returned.

Parameters
  • [in] bitstream: Pointer to bitstream with input data.

  • [in] codec_id: Codec ID to determine the type of codec for the input bitstream.

  • [out] adapters: Pointer to the output list of adapters. Memory should be allocated by user. See mfxAdaptersInfo description for details.

mfxStatus MFXQueryAdaptersNumber(mfxU32 *num_adapters)

This function returns the number of detected graphics adapters. It can be used before calling MFXQueryAdapters to determine the size of input data that the user will need to allocate.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR num_adapters pointer is NULL.

Parameters
  • [out] num_adapters: Pointer for the output number of detected graphics adapters.