VideoENCODE#

Functions that perform the entire encoding pipeline from the input video frames to the output bitstream.

API#

MFXVideoENCODE_Query#

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

Works in either of four modes:

  • If the in parameter is zero, the function returns the class configurability in the output structure. The application must set to zero the fields it wants to check for support. If the field is supported, function sets non-zero value to this field, otherwise it would be ignored. It indicates 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 implementation supports certain profiles, levels or bitrates.

  • If the in parameter is non-zero and mfxExtEncoderResetOption structure is attached to it, 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 a reset is possible and returns an error otherwise. Unlike other modes that are independent of the encoder state, this one checks if reset is possible in the present encoder state. This mode also requires a 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, the function returns encoder capability in the mfxExtEncoderCapability structure attached to out. It is recommended to fill in the mfxVideoParam structure and set the 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.

Since

This function is available since API version 1.0.

Parameters:

  • session – [in] Session handle.

  • in – [in] Pointer to the mfxVideoParam structure as input.

  • out – [out] Pointer to the mfxVideoParam structure as output.

Returns:

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 hardware implementations may return this status code.

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

Important

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

MFXVideoENCODE_QueryIOSurf#

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

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. This function does not validate I/O parameters except those used in calculating the number of input surfaces.

The use of this function is recommended.

For more information, see the Working with Hardware Acceleration section.

Since

This function is available since API version 1.0.

Parameters:

  • session – [in] Session handle.

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

  • request – [in] Pointer to the mfxFrameAllocRequest structure as output.

Returns:

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 hardware implementations may return this status code.

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

MFXVideoENCODE_Init#

mfxStatus MFXVideoENCODE_Init(mfxSession session, mfxVideoParam *par)#

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.

Since

This function is available since API version 1.0.

Parameters:

  • session – [in] Session handle.

  • par – [in] Pointer to the mfxVideoParam structure.

Returns:

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 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;

Important

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

MFXVideoENCODE_Reset#

mfxStatus MFXVideoENCODE_Reset(mfxSession session, mfxVideoParam *par)#

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

Since

This function is available since API version 1.0.

Parameters:

  • session – [in] Session handle.

  • par – [in] Pointer to the mfxVideoParam structure.

Returns:

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 video parameters provided by the application are incompatible with initialization parameters. Reset requires additional memory allocation and cannot be executed. The application should close the component and then reinitialize it.

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

MFXVideoENCODE_Close#

mfxStatus MFXVideoENCODE_Close(mfxSession session)#

Terminates the current encoding operation and de-allocates any internal tables or structures.

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 MFXVideoENCODE_Close() function is mandatory when implementing an encoder.

MFXVideoENCODE_GetVideoParam#

mfxStatus MFXVideoENCODE_GetVideoParam(mfxSession session, mfxVideoParam *par)#

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.

Since

This function is available since API version 1.0.

Parameters:

  • session – [in] Session handle.

  • par – [in] Pointer to the corresponding parameter structure.

Returns:

MFX_ERR_NONE The function completed successfully.

MFXVideoENCODE_GetEncodeStat#

mfxStatus MFXVideoENCODE_GetEncodeStat(mfxSession session, mfxEncodeStat *stat)#

Obtains statistics collected during encoding.

Since

This function is available since API version 1.0.

Parameters:

  • session – [in] Session handle.

  • stat – [in] Pointer to the mfxEncodeStat structure.

Returns:

MFX_ERR_NONE The function completed successfully.

MFXVideoENCODE_EncodeFrameAsync#

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

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’s 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 the MFXVideoENCODE_GetVideoParam function 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.

Since

This function is available since API version 1.0.

Parameters:

  • session – [in] Session handle.

  • ctrl – [in] 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. ctrl can be freed right after successful MFXVideoENCODE_EncodeFrameAsync (it is copied inside), but not the ext buffers attached to this ctrl. If the ext buffers are allocated by the user, do not move, alter or delete unless surface.Data.Locked is zero.

  • surface – [in] Pointer to the frame surface structure. For surfaces allocated by oneAPI Video Processing Library (oneVPL) RT it is safe to call mfxFrameSurface1::FrameInterface->Release after successful MFXVideoENCODE_EncodeFrameAsync. If it is allocated by user, do not move, alter or delete unless surface.Data.Locked is zero.

  • bs – [out] Pointer to the output bitstream.

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

Returns:

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 the Working with Microsoft* DirectX* Applications section for further information.

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

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM Inconsistent parameters detected not conforming to Configuration Parameter Constraints.

Important

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