MFXVideoENCODE

This class of functions performs the entire encoding pipeline from the input video frames to the output bitstream.

Member Functions

 

MFXVideoENCODE_Query

Queries the feature capability

MFXVideoENCODE_QueryIOSurf

Queries the number of input surface frames required for encoding

MFXVideoENCODE_Init

Initializes the encoding operation

MFXVideoENCODE_Reset

Resets the current encoding operation and prepares for the next encoding operation

MFXVideoENCODE_Close

Terminates the encoding operation and de-allocates any internal memory

MFXVideoENCODE_GetVideoParam

Obtains the current working parameter set

MFXVideoENCODE_GetEncodeStat

Obtains the statistics collected during encoding

MFXVideoENCODE_EncodeFrameAsync

Performs the encoding and returns the compressed bitstream

 

 

Syntax

 

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

Parameters

 

session

SDK session handle

 

in

Pointer to the mfxVideoParam structure as input

 

out

Pointer to the mfxVideoParam structure as output

Description

 

This function works in either of four modes:

  1. If the in pointer is zero, the function returns the class configurability in the output mfxVideoParam structure. A non-zero value in each field of the output structure indicates that the SDK implementation can configure the field with Init.

  2. If the in parameter is non-zero, the function checks the validity of the fields in the input mfxVideoParam structure. Then the function returns the corrected values in the output mfxVideoParam 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 SDK implementation supports certain profiles, levels or bitrates.

  3. If the in parameter is non-zero and mfxExtEncoderResetOption structure is attached to it, then 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 such reset is possible and returns error otherwise. Unlike other modes that are independent of the SDK encoder state, this one checks if reset is possible in the present SDK encoder state. This mode also requires completely defined mfxVideoParam structure, unlike other modes that support partially defined configurations. See mfxExtEncoderResetOption description for more details.

  4. If the in parameter is non-zero and mfxExtEncoderCapability structure is attached to it, then the function returns encoder capability in mfxExtEncoderCapability structure attached to out. It is recommended to fill in mfxVideoParam structure and set 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 mfxVideoParam structure is a mandated field (to be filled by the application) to identify the coding standard.

Return Status

 

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

 

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM

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

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

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

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure as input

 

request

Pointer to the mfxFrameAllocRequest structure as output

Description

 

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

The use of this function is recommended. For more information, see the section Working with hardware acceleration.

This function does not validate I/O parameters except those used in calculating the number of input surfaces.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_WRN_PARTIAL_ACCELERATION

The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only SDK HW implementations may return this status code.

 

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_INCOMPATIBLE_VIDEO_PARAM

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

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXVideoENCODE_Init(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure

Description

 

This function 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 Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_WRN_PARTIAL_ACCELERATION

The underlying hardware does not fully support the specified video parameters. The encoding may be partially accelerated. Only SDK HW implementations may return this status code.

 

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

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXVideoENCODE_Reset(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the mfxVideoParam structure

Description

 

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

Return Status

 

MFX_ERR_NONE

The function completed successfully.

 

MFX_ERR_INVALID_VIDEO_PARAM

The function detected that video parameters are wrong or they conflict with initialization parameters. Reset is impossible.

 

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM

The function detected that provided by the application video parameters are incompatible with initialization parameters. Reset requires additional memory allocation and cannot be executed. The application should close the SDK component and then reinitialize it.

 

MFX_WRN_INCOMPATIBLE_VIDEO_PARAM

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

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXVideoENCODE_Close(mfxSession session);

Parameters

 

session

SDK session handle

Description

 

This function terminates the current encoding operation and de-allocates any internal tables or structures.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXVideoENCODE_GetVideoParam(mfxSession session, mfxVideoParam *par);

Parameters

 

session

SDK session handle

 

par

Pointer to the corresponding parameter structure

Description

 

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

Returned information

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

mfxStatus MFXVideoENCODE_GetEncodeStat(mfxSession session, mfxEncodeStat *stat);

Parameters

 

session

SDK session handle

 

stat

Pointer to the mfxEncodeStat structure

Description

 

This function obtains statistics collected during encoding.

Return Status

 

MFX_ERR_NONE

The function completed successfully.

Change History

 

This function is available since SDK API 1.0.

 

 

 

Syntax

 

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

Parameters

 

Session

SDK session handle

 

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.

 

surface

Pointer to the frame surface structure

 

bs

Pointer to the output bitstream

 

syncp

Pointer to the returned sync point associated with this operation

Description

 

This function 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 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 MFXVideoENCODE_GetVideoParam 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 Status

 

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

 

MFX_WRN_DEVICE_BUSY

Hardware device is currently busy. Call this function again in a few milliseconds.

 

MFX_ERR_INCOMPATIBLE_VIDEO_PARAM

Inconsistent parameters detected not conforming to Appendix A.

Change History

 

This function is available since SDK API 1.0.

Remarks

 

If the EncodedOrder field in the mfxInfoMFX structure is true, input frames enter the encoder in the order of their encoding. However, the FrameOrder field in the mfxFrameData structure of each frame must be set to the display order. If EncodedOrder is false, the function ignores the FrameOrder field.

 

 

 

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