MFE API

Note: this is just informational page, if it somehow contradicts with mediasdk-man, mediasdk-man will be right source of information

Media SDK API

MFXJoinSession usage

mfxStatus MFX_CDECL MFXJoinSession(mfxSession session, mfxSession child) existing API.

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.

• Multi-Frame Encode put a requirement to share common objects between sessions and access common resources, thus Application need to Join encoder(or FEI) sessions to share scheduler, UMD context and core. Join Session API not MFE specific, but required for MFE.

Parameters

mfxSession session - current session or parent session.

mfxSession child - child session;

Restrictions

MFXVideoCORE_SetHandle have to be called before this call for both parent and child session with the same handle and handle type for MFE.

Child session can't be joined to parent session after components were initialized, this limitation related to architecture: scheduler of child session will be destroyed, so when components are initialized they require scheduler to allocate threads associated with component, once scheduler removed - threads being de-allocated. 

Number of joined sessions does not affect number of frames except case when number of session is less than number of possible frames to combine.

Encoder initialization changes

Extended buffers added:

mfxExtMultiFrameParams

Definition:

typedef struct {

    mfxExtBuffer Header;

    mfxU16      MFMode;

    mfxU16      MaxNumFrames; 

    mfxU16      reserved[58];

} mfxExtMultiFrameParams;

Description:

This structure used to query supported parameters for MFE operation and encoder initialization parameters.

MFXVideoENCODE_Query or MFXVideoENC_Query function helps to identify maximum number of frames supported for particular codec set in MaxNumFrames and supported MFEMode.

MFXVideoENCODE_Init or MFXVideoENC_Init function enables maximum number of frames to be used in all encoder sessions joined together according to MaxNumFrames and MFEMode enabled.

Members:

Mode - Multi frame encode scheduling mode.

MaxNumFrames - maximum number of frames to be used in MFE pipeline.

Limitations:

Each encoder joined for MFE workload have to enable the same MFE mode and MaxNumFrames, as they share the same ISL which use those parameters to perform scheduling.

MaxNumFrames returned from query will depend on platform, codec, as well as can depend on resolution and other parameters, returned value will be aligned with assumption all encoders are running with the same parameters as current encoder.

Multi Frame Encode Scheduling Modes

Definition:

/* Multi Frame Encode Mode */
enum {
    MFX_MF_DEFAULT = 0,

    MFX_MF_DISABLED = 1,

    MFX_MF_AUTO = 2,
    MFX_MF_MANUAL = 3,

};

Entries:

MFX_MF_DEFAULT - Media SDK decide what operation mode to choose.

MFX_MF_AUTO - Automatic, Media SDK decide what and how many frames to submit as well as how long to wait for frames from different streams.

MFX_MF_MANUAL - Application use per frame control to manage submission described in frame management, no timeouts inside MediaSDK, Application fully controls when frame buffer is ready to be submitted.

MFX_MF_DISABLED - MFE explicitly disabled.

Frame Management

Definition:

typedef struct {

    mfxExtBuffer Header;

    mfxU16      Flush;                //flush internal frame buffer, e.g. submit all frames.

    mfxU32      timeout;           //timeout in millisecond.

    mfxU16      reserved[57];

} mfxExtMultiFrameControl;

Description

Used by application on Initialization and per frame basis to either:

• When passed to MFXVideoENCODE_Init timeout will be used for all frames in current stream(session).

• When passed to MFXVideoENCODE_EncodeFrameAsync - used as per frame management control over MFE submission.

Members:

Flush - when mode MFX_MF_MANUAL used, if enabled will force ISL internal frame buffer to submit all frames within current frame. Otherwise current frame will wait for MaxFrameNum to be buffered in ISL or flush from another stream.

timeout - when MFX_MF_AUTO is enabled, used as time in milliseconds this particular frame can wait for