Session Management#

Functions to manage sessions.

API#

MFXInit#

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

Creates and initializes a session in the legacy mode for compatibility with Intel(r) Media SDK applications. This function is deprecated starting from API version 2.0, applications must use MFXLoad with mfxCreateSession to select the implementation and initialize the session.

Call this function before calling any other API function. If the desired implementation specified by impl is MFX_IMPL_AUTO, the function will search for the platform-specific implementation. If the function cannot find the platform-specific implementation, it will use the software implementation instead.

The ver argument indicates the desired version of the library implementation. The loaded implementation 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 library release with which an application is built.

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

Deprecated:

Deprecated in API version 2.3. Use MFXLoad and MFXCreateSession to initialize the session. Use MFX_DEPRECATED_OFF macro to turn off the deprecation message visualization.

Since

This function is available since API version 1.0.

Parameters

  • impl – [in] mfxIMPL enumerator that indicates the desired legacy Intel(r) Media SDK implementation.

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

  • session – [out] Pointer to the legacy Intel(r) Media SDK session handle.

Returns

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 legacy Intel(r) Media SDK implementation or version.

MFXInitEx#

mfxStatus MFXInitEx(mfxInitParam par, mfxSession *session)#

Creates and initializes a session in the legacy mode for compatibility with Intel(r) Media SDK applications. This function is deprecated starting from API version 2.0, applications must use MFXLoad with mfxCreateSession to select the implementation and initialize the session.

Call this function before calling any other API functions. If the desired implementation specified by par is MFX_IMPL_AUTO, the function will search for the platform-specific implementation. If the function cannot find the platform-specific implementation, it will use the software implementation instead.

The argument par.Version indicates the desired version of the implementation. The loaded implementation 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 library release with which an application is built.

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

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

Deprecated:

Deprecated in API version 2.3. Use MFXLoad and MFXCreateSession to initialize the session. Use MFX_DEPRECATED_OFF macro to turn off the deprecation message visualization.

Since

This function is available since API version 1.14.

Parameters

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

  • session – [out] Pointer to the session handle.

Returns

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 implementation or version.

MFXInitialize#

mfxStatus MFXInitialize(mfxInitializationParam par, mfxSession *session)#

Creates and initializes a session starting from API version 2.0. This function is used by the dispatcher. The dispatcher creates and fills the mfxInitializationParam structure according to mfxConfig values set by an application. Calling this function directly is not recommended. Instead, applications must call the mfxCreateSession function.

Since

This function is available since API version 2.0.

Parameters

  • par – [in] mfxInitializationParam structure that indicates the minimum library version and acceleration type.

  • session – [out] Pointer to the session handle.

Returns

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 implementation or version.

Important

The MFXInitialize() function is mandatory for any implementation.

MFXClose#

mfxStatus MFXClose(mfxSession session)#

Completes and deinitializes a session. Any active tasks in execution or in queue are aborted. The application cannot call any API function after calling this function.

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

Since

This function is available since API version 1.0.

Parameters

session – [in] session handle.

Returns

MFX_ERR_NONE The function completed successfully.

Important

The MFXClose() function is mandatory for any implementation.

MFXQueryIMPL#

mfxStatus MFXQueryIMPL(mfxSession session, mfxIMPL *impl)#

Returns the implementation type of a given session.

Since

This function is available since API version 1.0.

Parameters

  • session – [in] Session handle.

  • impl – [out] Pointer to the implementation type

Returns

MFX_ERR_NONE The function completed successfully.

MFXQueryVersion#

mfxStatus MFXQueryVersion(mfxSession session, mfxVersion *version)#

Returns the implementation version.

Since

This function is available since API version 1.0.

Parameters

  • session – [in] Session handle.

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

Returns

MFX_ERR_NONE The function completed successfully.

MFXJoinSession#

mfxStatus MFXJoinSession(mfxSession session, mfxSession child)#

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.

Since

This function is available since API version 1.1.

Parameters

  • session – [inout] The current session handle.

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

Returns

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.

MFXDisjoinSession#

mfxStatus MFXDisjoinSession(mfxSession session)#

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 API function.

Since

This function is available since API version 1.1.

Parameters

session – [inout] The current session handle.

Returns

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.

MFXCloneSession#

mfxStatus MFXCloneSession(mfxSession session, mfxSession *clone)#

Creates a clean copy of the current session. 

   The cloned session is an independent session and 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.

Since

This function is available since API version 1.1.

Parameters

  • session – [in] The current session handle.

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

Returns

MFX_ERR_NONE The function completed successfully.

MFXSetPriority#

mfxStatus MFXSetPriority(mfxSession session, mfxPriority priority)#

Sets the current session priority.

Since

This function is available since API version 1.1.

Parameters

  • session – [in] The current session handle.

  • priority – [in] Priority value.

Returns

MFX_ERR_NONE The function completed successfully.

MFXGetPriority#

mfxStatus MFXGetPriority(mfxSession session, mfxPriority *priority)#

Returns the current session priority.

Since

This function is available since API version 1.1.

Parameters

  • session – [in] The current session handle.

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

Returns

MFX_ERR_NONE The function completed successfully.