Global Functions

Global functions initialize and de-initialize the SDK library and perform query functions on a global scale within an application.

Member Functions

Description

MFXInit

Initializes an SDK session

MFXQueryIMPL

Queries the implementation type

MFXQueryVersion

Queries the implementation version

MFXJoinSession

Join two sessions together

MFXCloneSession

Clone the current session

MFXSetPriority

Set session priority

MFXGetPriority

Obtain session priority

MFXDisjoinSession

Remove the join state of the current session

MFXClose

De-initializes an SDK session

 

Syntax

 

mfxStatus MFXCloneSession(mfxSession session, mfxSession *clone);

Parameters

 

session

SDK session handle

 

clone

Pointer to the cloned session handle

Description

 

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 Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.1.

 

 

Syntax

 

mfxStatus MFXClose(mfxSession session);

Parameters

 

session

SDK session handle

Description

 

This function completes and de-initializes 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 Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXDoWork(mfxSession session);

Parameters

 

session

SDK session handle

Description

 

This function complements MFXInitEx with external threading mode on. Application expected to create no less than two work threads per session and pass them to SDK via this function. This function won’t return control to application unless session is closed.

In case of joined sessions, application should call MFXDoWork only for parent session.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.14.

Syntax

 

mfxStatus MFXDisjoinSession(mfxSession session);

Parameters

 

session

SDK session handle

Description

 

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 Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_WRN_IN_EXECUTION

Active tasks are in execution or in queue. Wait for the completion of the tasks and then call this function again.

 

MFX_ERR_UNDEFINED_BEHAVIOR

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

Change History

 

This function is available since SDK API 1.1.

 

 

 

Syntax

 

mfxStatus MFXGetPriority(mfxSession session, mfxPriority *priority);

Parameters

 

session

SDK session handle

 

priority

Pointer to the priority value

Description

 

This function returns the current session priority.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.1.

 

 

 

Syntax

 

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

Parameters

 

impl

mfxIMPL enumerator that indicates the desired SDK implementation

 

ver

Pointer to the minimum library version or zero, if not specified

 

session

Pointer to the SDK session handle

Description

 

This function creates and initializes an SDK session. Call this function before calling any other SDK functions. 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 argument ver 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 Status

 

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.

Change History

 

 

This function is available since SDK API 1.0.

 

 

 

 

Syntax

 

mfxStatus MFXInitEx(mfxInitParam par, mfxSession *session);

Parameters

 

par

mfxInitParam structure that indicates the desired SDK implementation, minimum library version and desired threading mode

 

session

Pointer to the SDK session handle

Description

 

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). If this parameter set to 1 then SDK will expect that application should create work threads and pass them to SDK via single-entry function MFXDoWork. Setting par.ExternalThreads to 1 requires setting minimum API version to 1.14, as previous versions of SDK didn’t have such functionality.

Return Status

 

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.

Change History

 

 

This function is available since SDK API 1.14.

 

Syntax

 

mfxStatus MFXJoinSession(mfxSession session, mfxSession child);

Parameters

 

session

The current session handle

 

child

The child session handle to be joined

Description

 

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 Status

 

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.

Change History

 

 

This function is available since SDK API 1.1.

 

 

 

 

Syntax

 

mfxStatus MFXQueryIMPL(mfxSession session, mfxIMPL *impl);

Parameters

 

session

SDK session handle

 

impl

Pointer to the implementation type

Description

 

This function returns the implementation type of a given session.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXQueryVersion(mfxSession session, mfxVersion *version);

Parameters

 

session

SDK session handle

 

version

Pointer to the returned implementation version

Description

 

This function returns the SDK implementation version.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXSetPriority(mfxSession session, mfxPriority priority);

Parameters

 

session

SDK session handle

 

priority

Priority value

Description

 

This function sets the current session priority.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.1.

 

 

 

 

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