Contents

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 output structure has a non-zero value in each field that the implementation can configure using 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.

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

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

Since

This function is available since API version 1.0.

Parameters

  • [in] session: 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.

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.

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

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

Since

This function is available since API version 1.0.

Parameters

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.

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

Since

This function is available since API version 1.0.

Parameters

  • [in] session: Session handle.

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

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.

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

Since

This function is available since API version 1.0.

Parameters

  • [in] session: Session handle.

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

MFXVideoENCODE_Close

mfxStatus MFXVideoENCODE_Close(mfxSession session)

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

Return

MFX_ERR_NONE The function completed successfully.

Since

This function is available since API version 1.0.

Parameters

  • [in] session: Session handle.

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.

Return

MFX_ERR_NONE The function completed successfully.

Since

This function is available since API version 1.0.

Parameters

  • [in] session: Session handle.

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

MFXVideoENCODE_GetEncodeStat

mfxStatus MFXVideoENCODE_GetEncodeStat(mfxSession session, mfxEncodeStat *stat)

Obtains statistics collected during encoding.

Return

MFX_ERR_NONE The function completed successfully.

Since

This function is available since API version 1.0.

Parameters

  • [in] session: Session handle.

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

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.

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

Since

This function is available since API version 1.0.

Parameters

  • [in] session: 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 VideoVPP