Cross-component Structures

Structures used across library components.

API

mfxComponentInfo

struct mfxComponentInfo

Contains workload description, which is accepted by MFXQueryAdapters function.

Public Members

mfxComponentType Type

Type of workload: Encode, Decode, VPP. See mfxComponentType enumerator for values.

mfxVideoParam Requirements

Detailed description of workload. See mfxVideoParam for details.

mfxExtHEVCParam

struct mfxExtHEVCParam

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_HEVC_PARAM.

mfxU16 PicWidthInLumaSamples

Specifies the width of each coded picture in units of luma samples.

mfxU16 PicHeightInLumaSamples

Specifies the height of each coded picture in units of luma samples.

mfxU64 GeneralConstraintFlags

Additional flags to specify exact profile and constraints. See the GeneralConstraintFlags enumerator for values of this field.

mfxU16 SampleAdaptiveOffset

Controls SampleAdaptiveOffset encoding feature. See the SampleAdaptiveOffset enumerator for supported values (bit-ORed). Valid during encoder Init and Runtime.

mfxU16 LCUSize

Specifies largest coding unit size (max luma coding block). Valid during encoder Init.

mfxExtJPEGHuffmanTables

struct mfxExtJPEGHuffmanTables

Specifies Huffman tables. The application may specify up to 2 quantization table pairs for baseline process. The encoder assigns an ID to each table. That ID is equal to the table index in the DCTables and ACTables arrays. Table “0” is used for encoding of the Y component and table “1” is used for encoding of the U and V component. The application may specify only one table, in which case the table will be used for all components in the image. The following table illustrates this behavior.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_JPEG_HUFFMAN.

mfxU16 NumDCTable

Number of DC quantization table in DCTables array.

mfxU16 NumACTable

Number of AC quantization table in ACTables array.

mfxU8 Bits[16]

Number of codes for each code length.

mfxU8 Values[12]

List of the 8-bit symbol values.

Array of AC tables.

struct mfxExtJPEGHuffmanTables::[anonymous] DCTables[4]

Array of DC tables.

struct mfxExtJPEGHuffmanTables::[anonymous] ACTables[4]

List of the 8-bit symbol values.

Table ID	0	1
Number of tables
0	Y, U, V
1	Y	U, V

mfxExtJPEGQuantTables

struct mfxExtJPEGQuantTables

Specifies quantization tables. The application may specify up to 4 quantization tables. The encoder assigns an ID to each table. That ID is equal to the table index in the Qm array. Table “0” is used for encoding of the Y component, table “1” for the U component, and table “2” for the V component. The application may specify fewer tables than the number of components in the image. If two tables are specified, then table “1” is used for both U and V components. If only one table is specified then it is used for all components in the image. The following table illustrates this behavior.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_JPEG_QT.

mfxU16 NumTable

Number of quantization tables defined in Qm array.

mfxU16 Qm[4][64]

Quantization table values.

Table ID	0	1	2
Number of tables
0	Y, U, V
1	Y	U, V
2	Y	U	V

mfxExtMVCSeqDesc

struct mfxExtMVCSeqDesc

Describes the MVC stream information of view dependencies, view identifiers, and operation points. See the ITU*-T H.264 specification chapter H.7.3.2.1.4 for details.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_MVC_SEQUENCE_DESCRIPTION.

mfxU32 NumView

Number of views.

mfxU32 NumViewAlloc

The allocated view dependency array size.

mfxMVCViewDependency *View

Pointer to a list of the mfxMVCViewDependency.

mfxU32 NumViewId

Number of view identifiers.

mfxU32 NumViewIdAlloc

The allocated view identifier array size.

mfxU16 *ViewId

Pointer to the list of view identifier.

mfxU32 NumOP

Number of operation points.

mfxU32 NumOPAlloc

The allocated operation point array size.

mfxMVCOperationPoint *OP

Pointer to a list of the mfxMVCOperationPoint structure.

mfxU16 NumRefsTotal

Total number of reference frames in all views required to decode the stream. This value is returned from the MFXVideoDECODE_Decodeheader function. Do not modify this value.

mfxExtMVCTargetViews

struct mfxExtMVCTargetViews

Configures views for the decoding output.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_MVC_TARGET_VIEWS.

mfxU16 TemporalId

The temporal identifier to be decoded.

mfxU32 NumView

The number of views to be decoded.

mfxU16 ViewId[1024]

List of view identifiers to be decoded.

mfxExtVideoSignalInfo

struct mfxExtVideoSignalInfo

Defines the video signal information.

For H.264, see Annex E of the ISO/IEC 14496-10 specification for the definition of these parameters.

For MPEG-2, see section 6.3.6 of the ITU* H.262 specification for the definition of these parameters. The field VideoFullRange is ignored.

For VC-1, see section 6.1.14.5 of the SMPTE* 421M specification. The fields VideoFormat and VideoFullRange are ignored.

Note

If ColourDescriptionPresent is zero, the color description information (including ColourPrimaries, TransferCharacteristics, and MatrixCoefficients) does not present in the bitstream.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_VIDEO_SIGNAL_INFO.

mfxU16 VideoFormat

mfxU16 VideoFullRange

mfxU16 ColourDescriptionPresent

mfxU16 ColourPrimaries

mfxU16 TransferCharacteristics

mfxU16 MatrixCoefficients

mfxExtVP9Param

struct mfxExtVP9Param

Structure attached to the mfxVideoParam structure. Extends the mfxVideoParam structure with VP9-specific parameters. Used by both decoder and encoder.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_VP9_PARAM.

mfxU16 FrameWidth

Width of the coded frame in pixels.

mfxU16 FrameHeight

Height of the coded frame in pixels.

mfxU16 WriteIVFHeaders

Set this option to ON to make the encoder insert IVF container headers to the output stream. The NumFrame field of the IVF sequence header will be zero. It is the responsibility of the application to update the NumFrame field with the correct value. See the CodingOptionValue enumerator for values of this option.

mfxI16 QIndexDeltaLumaDC

Specifies an offset for a particular quantization parameter.

mfxI16 QIndexDeltaChromaAC

Specifies an offset for a particular quantization parameter.

mfxI16 QIndexDeltaChromaDC

Specifies an offset for a particular quantization parameter.

mfxU16 NumTileRows

Number of tile rows. Should be power of two. The maximum number of tile rows is 4, per the VP9 specification. In addition, the maximum supported number of tile rows may depend on the underlying library implementation.

Use the Query API function to check if a particular pair of values (NumTileRows, NumTileColumns) is supported. In VP9, tile rows have dependencies and cannot be encoded or decoded in parallel. Therefore, tile rows are always encoded by the library in serial mode (one-by-one).

mfxU16 NumTileColumns

Number of tile columns. Should be power of two. Restricted with maximum and minimum tile width in luma pixels, as defined in the VP9 specification (4096 and 256 respectively). In addition, the maximum supported number of tile columns may depend on the underlying library implementation.

Use the Query API function to check if a particular pair of values (NumTileRows, NumTileColumns) is supported. In VP9, tile columns do not have dependencies and can be encoded/decoded in parallel. Therefore, tile columns can be encoded by the library in both parallel and serial modes.

Parallel mode is automatically utilized by the library when NumTileColumns exceeds 1 and does not exceed the number of tile coding engines on the platform. In other cases, serial mode is used. Parallel mode is capable of encoding more than 1 tile row (within limitations provided by VP9 specification and particular platform). Serial mode supports only tile grids 1xN and Nx1.

mfxFrameId

struct mfxFrameId

Describes the view and layer of a frame picture.

Public Members

mfxU16 TemporalId

The temporal identifier as defined in the annex H of the ITU*-T H.264 specification.

mfxU16 PriorityId

Reserved and must be zero.

mfxU16 DependencyId

Reserved for future use.

mfxU16 QualityId

Reserved for future use.

mfxU16 ViewId

The view identifier as defined in the annex H of the ITU-T H.264 specification.

mfxInfoMFX

struct mfxInfoMFX

Specifies configurations for decoding, encoding, and transcoding processes. A zero value in any of these fields indicates that the field is not explicitly specified.

Public Members

mfxU32 reserved[7]

Reserved for future use.

mfxU16 LowPower

Hint to enable low power consumption mode for encoders. See the CodingOptionValue enumerator for values of this option. Use the Query API function to check if this feature is supported.

mfxU16 BRCParamMultiplier

Specifies a multiplier for bitrate control parameters. Affects the following variables: InitialDelayInKB, BufferSizeInKB, TargetKbps, MaxKbps. If this value is not equal to zero, the encoder calculates BRC parameters as value * BRCParamMultiplier.

mfxFrameInfo FrameInfo

mfxFrameInfo structure that specifies frame parameters.

mfxU32 CodecId

Specifies the codec format identifier in the FourCC code; see the CodecFormatFourCC enumerator for details. This is a mandated input parameter for the QueryIOSurf and Init API functions.

mfxU16 CodecProfile

Specifies the codec profile; see the CodecProfile enumerator for details. Specify the codec profile explicitly or the API functions will determine the correct profile from other sources, such as resolution and bitrate.

mfxU16 CodecLevel

Codec level; see the CodecLevel enumerator for details. Specify the codec level explicitly or the functions will determine the correct level from other sources, such as resolution and bitrate.

mfxU16 TargetUsage

Target usage model that guides the encoding process; see the TargetUsage enumerator for details.

mfxU16 GopPicSize

Number of pictures within the current GOP (Group of Pictures); if GopPicSize = 0, then the GOP size is unspecified. If GopPicSize = 1, only I-frames are used. The following pseudo-code that shows how the library uses this parameter:

mfxU16 get_gop_sequence (...) {
   pos=display_frame_order;
   if (pos == 0)
       return MFX_FRAMETYPE_I | MFX_FRAMETYPE_IDR | MFX_FRAMETYPE_REF;

   If (GopPicSize == 1) // Only I-frames
       return MFX_FRAMETYPE_I | MFX_FRAMETYPE_REF;

   if (GopPicSize == 0)
               frameInGOP = pos;    //Unlimited GOP
           else
               frameInGOP = pos%GopPicSize;

   if (frameInGOP == 0)
       return MFX_FRAMETYPE_I | MFX_FRAMETYPE_REF;

   if (GopRefDist == 1 || GopRefDist == 0)    // Only I,P frames
               return MFX_FRAMETYPE_P | MFX_FRAMETYPE_REF;

   frameInPattern = (frameInGOP-1)%GopRefDist;
   if (frameInPattern == GopRefDist - 1)
       return MFX_FRAMETYPE_P | MFX_FRAMETYPE_REF;

   return MFX_FRAMETYPE_B;
 }

mfxU16 GopRefDist

Distance between I- or P (or GPB) - key frames; if it is zero, the GOP structure is unspecified. Note: If GopRefDist = 1, there are no regular B-frames used (only P or GPB); if mfxExtCodingOption3::GPB is ON, GPB frames (B without backward references) are used instead of P.

mfxU16 GopOptFlag

ORs of the GopOptFlag enumerator indicate the additional flags for the GOP specification.

mfxU16 IdrInterval

For H.264, specifies IDR-frame interval in terms of I-frames. For example:

• If IdrInterval = 0, then every I-frame is an IDR-frame.

• If IdrInterval = 1, then every other I-frame is an IDR-frame.

For HEVC, if IdrInterval = 0, then only first I-frame is an IDR-frame. For example:

• If IdrInterval = 1, then every I-frame is an IDR-frame.

• If IdrInterval = 2, then every other I-frame is an IDR-frame.

For MPEG2, IdrInterval defines sequence header interval in terms of I-frames. For example:

• If IdrInterval = 0 (default), then the sequence header is inserted once at the beginning of the stream.

• If IdrInterval = N, then the sequence header is inserted before every Nth I-frame.

If GopPicSize or GopRefDist is zero, IdrInterval is undefined.

mfxU16 InitialDelayInKB

Initial size of the Video Buffering Verifier (VBV) buffer.

Note

In this context, KB is 1000 bytes and Kbps is 1000 bps.

mfxU16 QPI

Quantization Parameter (QP) for I-frames for constant QP mode (CQP). Zero QP is not valid and means that the default value is assigned by the library. Non-zero QPI might be clipped to supported QPI range.

Note

In the HEVC design, a further adjustment to QPs can occur based on bit depth. Adjusted QPI value = QPI - (6 * (BitDepthLuma - 8)) for BitDepthLuma in the range [8,14]. For HEVC_MAIN10, we minus (6*(10-8)=12) on our side and continue.

Note

Default QPI value is implementation dependent and subject to change without additional notice in this document.

mfxU16 Accuracy

Specifies accuracy range in the unit of tenth of percent.

mfxU16 BufferSizeInKB

Represents the maximum possible size of any compressed frames.

mfxU16 TargetKbps

Constant bitrate TargetKbps. Used to estimate the targeted frame size by dividing the frame rate by the bitrate.

mfxU16 QPP

Quantization Parameter (QP) for P-frames for constant QP mode (CQP). Zero QP is not valid and means that the default value is assigned by the library. Non-zero QPP might be clipped to supported QPI range.

Note

In the HEVC design, a further adjustment to QPs can occur based on bit depth. Adjusted QPP value = QPP - (6 * (BitDepthLuma - 8)) for BitDepthLuma in the range [8,14]. For HEVC_MAIN10, we minus (6*(10-8)=12) on our side and continue.

Note

Default QPP value is implementation dependent and subject to change without additional notice in this document.

mfxU16 ICQQuality

Used by the Intelligent Constant Quality (ICQ) bitrate control algorithm. Values are in the 1 to 51 range, where 1 corresponds the best quality.

mfxU16 MaxKbps

The maximum bitrate at which the encoded data enters the Video Buffering Verifier (VBV) buffer.

mfxU16 QPB

Quantization Parameter (QP) for B-frames for constant QP mode (CQP). Zero QP is not valid and means that the default value is assigned by the library. Non-zero QPI might be clipped to supported QPB range.

Note

In the HEVC design, a further adjustment to QPs can occur based on bit depth. Adjusted QPB value = QPB - (6 * (BitDepthLuma - 8)) for BitDepthLuma in the range [8,14]. For HEVC_MAIN10, we minus (6*(10-8)=12) on our side and continue.

Note

Default QPB value is implementation dependent and subject to change without additional notice in this document.

mfxU16 Convergence

Convergence period in the unit of 100 frames.

mfxU16 NumSlice

Number of slices in each video frame. Each slice contains one or more macro-block rows. If NumSlice equals zero, the encoder may choose any slice partitioning allowed by the codec standard. See also mfxExtCodingOption2::NumMbPerSlice.

mfxU16 NumRefFrame

Max number of all available reference frames (for AVC/HEVC, NumRefFrame defines DPB size). If NumRefFrame = 0, this parameter is not specified. See also NumRefActiveP, NumRefActiveBL0, and NumRefActiveBL1 in the mfxExtCodingOption3 structure, which set a number of active references.

mfxU16 EncodedOrder

If not zero, specifies that ENCODE takes the input surfaces in the encoded order and uses explicit frame type control. The application must still provide GopRefDist and mfxExtCodingOption2::BRefType so the library can pack headers and build reference lists correctly.

mfxU16 DecodedOrder

For AVC and HEVC, used to instruct the decoder to return output frames in the decoded order. Must be zero for all other decoders. When enabled, correctness of mfxFrameData::TimeStamp and FrameOrder for output surface is not guaranteed, the application should ignore them.

mfxU16 ExtendedPicStruct

Instructs DECODE to output extended picture structure values for additional display attributes. See the PicStruct description for details.

mfxU16 TimeStampCalc

Time stamp calculation method. See the TimeStampCalc description for details.

mfxU16 SliceGroupsPresent

Nonzero value indicates that slice groups are present in the bitstream. Used only by AVC decoder.

mfxU16 MaxDecFrameBuffering

Nonzero value specifies the maximum required size of the decoded picture buffer in frames for AVC and HEVC decoders.

mfxU16 EnableReallocRequest

For decoders supporting dynamic resolution change (VP9), set this option to ON to allow MFXVideoDECODE_DecodeFrameAsync return MFX_ERR_REALLOC_SURFACE. See the CodingOptionValue enumerator for values of this option. Use the Query API function to check if this feature is supported.

mfxU16 FilmGrain

Special parameter for AV1 decoder. Indicates presence/absence of film grain parameters in bitstream. Also controls decoding behavior for streams with film grain parameters. MFXVideoDECODE_DecodeHeader returns nonzero FilmGrain for streams with film grain parameters and zero for streams w/o them. Decoding with film grain requires additional output surfaces. If FilmGrain` is non-zero then MFXVideoDECODE_QueryIOSurf will request more surfaces in case of external allocated video memory at decoder output. FilmGrain is passed to MFXVideoDECODE_Init function to control decoding operation for AV1 streams with film grain parameters. If FilmGrain is nonzero decoding of each frame require two output surfaces (one for reconstructed frame and one for output frame with film grain applied). The decoder returns MFX_ERR_MORE_SURFACE from MFXVideoDECODE_DecodeFrameAsync if it has insufficient output surfaces to decode frame. Application can forcibly disable the feature passing zero value of FilmGrain to MFXVideoDECODE_Init. In this case the decoder will output reconstructed frames w/o film grain applied. Application can retrieve film grain parameters for a frame by attaching extended buffer mfxExtAV1FilmGrainParam to mfxFrameSurface1. If stream has no film grain parameters FilmGrain passed to MFXVideoDECODE_Init is ignored by the decoder.

mfxU16 IgnoreLevelConstrain

If not zero, it forces SDK to attempt to decode bitstream even if a decoder may not support all features associated with given CodecLevel. Decoder may produce visual artifacts. Only AVC decoder supports this field.

mfxU16 SkipOutput

This flag is used to disable output of main decoding channel. When it’s ON SkipOutput = MFX_CODINGOPTION_ON decoder outputs only video processed channels. For pure decode this flag should be always disabled.

mfxU16 JPEGChromaFormat

Specify the chroma sampling format that has been used to encode a JPEG picture. See the ChromaFormat enumerator for details.

mfxU16 Rotation

Rotation option of the output JPEG picture. See the Rotation enumerator for details.

mfxU16 JPEGColorFormat

Specify the color format that has been used to encode a JPEG picture. See the JPEGColorFormat enumerator for details.

mfxU16 InterleavedDec

Specify JPEG scan type for decoder. See the JPEGScanType enumerator for details.

mfxU8 SamplingFactorH[4]

Horizontal sampling factor.

mfxU8 SamplingFactorV[4]

Vertical sampling factor.

mfxU16 Interleaved

Specify interleaved or non-interleaved scans. If it is equal to MFX_SCANTYPE_INTERLEAVED then the image is encoded as interleaved, all components are encoded in one scan. See the JPEG Scan Type enumerator for details.

mfxU16 Quality

Specifies the image quality if the application does not specified quantization table. The value is from 1 to 100 inclusive. “100” is the best quality.

mfxU16 RestartInterval

Specifies the number of MCU in the restart interval. “0” means no restart interval.

Note

The mfxInfoMFX::InitialDelayInKB, mfxInfoMFX::TargetKbps, mfxInfoMFX::MaxKbps parameters are used by the constant bitrate (CBR), variable bitrate control (VBR), and CQP HRD algorithms.

Encoders follow the Hypothetical Reference Decoding (HRD) model. The HRD model assumes that data flows into a buffer of the fixed size BufferSizeInKB with a constant bitrate of TargetKbps. (Estimate the targeted frame size by dividing frame rate by bitrate.)

The decoder starts decoding after the buffer reaches the initial size InitialDelayInKB, which is equivalent to reaching an initial delay of InitialDelayInKB*8000/TargetKbpsms. In this context, KB is 1000 bytes and Kbps is 1000 bps.

If InitialDelayInKB or BufferSizeInKB is equal to zero, the value is calculated using bitrate, frame rate, profile, level, and so on.

TargetKbps must be specified for encoding initialization.

For variable bitrate control, the MaxKbps parameter specifies the maximum bitrate at which the encoded data enters the Video Buffering Verifier (VBV) buffer. If MaxKbps is equal to zero, the value is calculated from bitrate, frame rate, profile, and level.

Note

The mfxInfoMFX::TargetKbps, mfxInfoMFX::Accuracy, mfxInfoMFX::Convergence parameters are used by the average variable bitrate control (AVBR) algorithm. The algorithm focuses on overall encoding quality while meeting the specified bitrate, TargetKbps, within the accuracy range, Accuracy, after a Convergence period. This method does not follow HRD and the instant bitrate is not capped or padded.

mfxMVCOperationPoint

struct mfxMVCOperationPoint

Describes the MVC operation point.

Public Members

mfxU16 TemporalId

Temporal identifier of the operation point.

mfxU16 LevelIdc

Level value signaled for the operation point.

mfxU16 NumViews

Number of views required for decoding the target output views that correspond to the operation point.

mfxU16 NumTargetViews

Number of target output views for the operation point.

mfxU16 *TargetViewId

Target output view identifiers for operation point.

mfxMVCViewDependency

struct mfxMVCViewDependency

Describes MVC view dependencies.

Public Members

mfxU16 ViewId

View identifier of this dependency structure.

mfxU16 NumAnchorRefsL0

Number of view components for inter-view prediction in the initial reference picture list RefPicList0 for anchor view components.

mfxU16 NumAnchorRefsL1

Number of view components for inter-view prediction in the initial reference picture list RefPicList1 for anchor view components.

mfxU16 AnchorRefL0[16]

View identifiers of the view components for inter-view prediction in the initial reference picture list RefPicList0 for anchor view components.

mfxU16 AnchorRefL1[16]

View identifiers of the view components for inter-view prediction in the initial reference picture list RefPicList1 for anchor view components.

mfxU16 NumNonAnchorRefsL0

Number of view components for inter-view prediction in the initial reference picture list RefPicList0 for non-anchor view components.

mfxU16 NumNonAnchorRefsL1

Number of view components for inter-view prediction in the initial reference picture list RefPicList1 for non-anchor view components.

mfxU16 NonAnchorRefL0[16]

View identifiers of the view components for inter-view prediction in the initial reference picture list RefPicList0 for non-anchor view components.

mfxPayload

struct mfxPayload

Describes user data payload in MPEG-2 or SEI message payload in H.264.

For encoding, these payloads can be inserted into the bitstream. The payload buffer must contain a valid formatted payload.

For H.264, this is the sei_message() as specified in the section 7.3.2.3.1 ‘Supplemental enhancement information message syntax’ of the ISO/IEC 14496-10 specification.

For MPEG-2, this is the section 6.2.2.2.2 ‘User data’ of the ISO/IEC 13818-2 specification, excluding the user data start_code.

For decoding, these payloads can be retrieved as the decoder parses the bitstream and caches them in an internal buffer.

Public Members

mfxU32 CtrlFlags

Additional payload properties. See the PayloadCtrlFlags enumerator for details.

mfxU8 *Data

Pointer to the actual payload data buffer.

mfxU32 NumBit

Number of bits in the payload data

mfxU16 Type

MPEG-2 user data start code or H.264 SEI message type.

mfxU16 BufSize

Payload buffer size in bytes.

Codec	Supported Types
MPEG2	0x01B2 //User Data
AVC	02 //pan_scan_rect 03 //filler_payload 04 //user_data_registered_itu_t_t35 05 //user_data_unregistered 06 //recovery_point 09 //scene_info 13 //full_frame_freeze 14 //full_frame_freeze_release 15 //full_frame_snapshot 16 //progressive_refinement_segment_start 17 //progressive_refinement_segment_end 19 //film_grain_characteristics 20 //deblocking_filter_display_preference 21 //stereo_video_info 45 //frame_packing_arrangement
HEVC	All

mfxVideoParam

struct mfxVideoParam

Configuration parameters for encoding, decoding, transcoding, and video processing.

Public Members

mfxU32 AllocId

Unique component ID that will be passed by the library to mfxFrameAllocRequest. Useful in pipelines where several components of the same type share the same allocator.

mfxU16 AsyncDepth

Specifies how many asynchronous operations an application performs before the application explicitly synchronizes the result. If zero, the value is not specified.

mfxInfoMFX mfx

Configurations related to encoding, decoding, and transcoding. See the definition of the mfxInfoMFX structure for details.

mfxInfoVPP vpp

Configurations related to video processing. See the definition of the mfxInfoVPP structure for details.

mfxU16 Protected

Specifies the content protection mechanism. See the Protected enumerator for a list of supported protection schemes.

mfxU16 IOPattern

Input and output memory access types for functions. See the enumerator IOPattern for details. The Query API functions return the natively supported IOPattern if the Query input argument is NULL. This parameter is a mandated input for QueryIOSurf and Init API functions. The output pattern must be specified for DECODE. The input pattern must be specified for ENCODE. Both input and output pattern must be specified for VPP.

mfxExtBuffer **ExtParam

Points to an array of pointers to the extra configuration structures. See the ExtendedBufferID enumerator for a list of extended configurations. The list of extended buffers should not contain duplicated entries, such as entries of the same type. If the mfxVideoParam structure is used to query library capability, then the list of extended buffers attached to the input and output mfxVideoParam structure should be equal, that is, it should contain the same number of extended buffers of the same type.

mfxU16 NumExtParam

The number of extra configuration structures attached to this structure.

mfxVP9SegmentParam

struct mfxVP9SegmentParam

Contains features and parameters for the segment.

Public Members

mfxU16 FeatureEnabled

Indicates which features are enabled for the segment. See the SegmentFeature enumerator for values for this option. Values from the enumerator can be bit-OR’ed. Support of a particular feature depends on underlying hardware platform. Application can check which features are supported by calling Query.

mfxI16 QIndexDelta

Quantization index delta for the segment. Ignored if MFX_VP9_SEGMENT_FEATURE_QINDEX isn’t set in FeatureEnabled. Valid range for this parameter is [-255, 255]. If QIndexDelta is out of this range, it will be ignored. If QIndexDelta is within valid range, but sum of base quantization index and QIndexDelta is out of [0, 255], QIndexDelta will be clamped.

mfxI16 LoopFilterLevelDelta

Loop filter level delta for the segment. Ignored if MFX_VP9_SEGMENT_FEATURE_LOOP_FILTER is not set in FeatureEnabled. Valid range for this parameter is [-63, 63]. If LoopFilterLevelDelta is out of this range, it will be ignored. If LoopFilterLevelDelta is within valid range, but sum of base loop filter level and LoopFilterLevelDelta is out of [0, 63], LoopFilterLevelDelta will be clamped.

mfxU16 ReferenceFrame

Reference frame for the segment. See VP9ReferenceFrame enumerator for values for this option. Ignored if MFX_VP9_SEGMENT_FEATURE_REFERENCE isn’t set in FeatureEnabled.

mfxExtAV1FilmGrainParam

struct mfxExtAV1FilmGrainParam

The structure is used by AV-1 decoder to report film grain parameters for decoded frame.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_AV1_FILM_GRAIN_PARAM.

mfxU16 FilmGrainFlags

Bit map with bit-ORed flags from FilmGrainFlags enum.

mfxU16 GrainSeed

Starting value for pseudo-random numbers used during film grain synthesis.

mfxU8 RefIdx

Indicate which reference frame contains the film grain parameters to be used for this frame.

mfxU8 NumYPoints

The number of points for the piece-wise linear scaling function of the luma component.

mfxU8 NumCbPoints

The number of points for the piece-wise linear scaling function of the Cb component.

mfxU8 NumCrPoints

The number of points for the piece-wise linear scaling function of the Cr component.

mfxAV1FilmGrainPoint PointY[14]

The array of points for luma component.

mfxAV1FilmGrainPoint PointCb[10]

The array of points for Cb component.

mfxAV1FilmGrainPoint PointCr[10]

The array of points for Cr component.

mfxU8 GrainScalingMinus8

The shift - 8 applied to the values of the chroma component. The grain_scaling_minus_8 can take values of 0..3 and determines the range and quantization step of the standard deviation of film grain.

mfxU8 ArCoeffLag

The number of auto-regressive coefficients for luma and chroma.

mfxU8 ArCoeffsYPlus128[24]

Auto-regressive coefficients used for the Y plane.

mfxU8 ArCoeffsCbPlus128[25]

Auto-regressive coefficients used for the Cb plane.

mfxU8 ArCoeffsCrPlus128[25]

The number of points for the piece-wise linear scaling function of the Cr component.

mfxU8 ArCoeffShiftMinus6

The range of the auto-regressive coefficients. Values of 0, 1, 2, and 3 correspond to the ranges for auto-regressive coefficients of [-2, 2), [-1, 1), [-0.5, 0.5) and [-0.25, 0.25) respectively.

mfxU8 GrainScaleShift

Downscaling factor of the grain synthesis process for the Gaussian random numbers .

mfxU8 CbMult

The multiplier for the Cb component used in derivation of the input index to the Cb component scaling function.

mfxU8 CbLumaMult

The multiplier for the average luma component used in derivation of the input index to the Cb component scaling function.

mfxU16 CbOffset

The offset used in derivation of the input index to the Cb component scaling function.

mfxU8 CrMult

The multiplier for the Cr component used in derivation of the input index to the Cr component scaling function.

mfxU8 CrLumaMult

The multiplier for the average luma component used in derivation of the input index to the Cr component scaling function.

mfxU16 CrOffset

The offset used in derivation of the input index to the Cr component scaling function.

mfxAV1FilmGrainPoint

struct mfxAV1FilmGrainPoint

Defines film grain point.

Public Members

mfxU8 Value

The x coordinate for the i-th point of the piece-wise linear scaling function for luma/Cb/Cr component.

mfxU8 Scaling

The scaling (output) value for the i-th point of the piecewise linear scaling function for luma/Cb/Cr component.

mfxRect

struct mfxRect

The structure describes rectangle coordinates that can be used for ROI or for Cropping.

Public Members

mfxU16 Left

X coordinate of region of top-left corner of rectangle.

mfxU16 Top

Y coordinate of region of top-left corner of rectangle.

mfxU16 Right

X coordinate of region of bottom-right corner of rectangle.

mfxU16 Bottom

Y coordinate of region of bottom-right corner of rectangle.

mfxExtHyperModeParam

struct mfxExtHyperModeParam

The structure is used for HyperMode initialization.

Public Members

mfxExtBuffer Header

Extension buffer header. BufferId must be equal to MFX_EXTBUFF_HYPER_MODE_PARAM.

mfxHyperMode Mode

HyperMode implementation behavior.

mfxGUID

struct mfxGUID

Represents Globally Unique Identifier (GUID) with memory layout compliant to RFC 4122. See https://www.rfc-editor.org/info/rfc4122 for details.

Public Members

mfxU8 Data[16]

Array to keep GUID.

mfxExtAllocationHints

struct mfxExtAllocationHints

The extension buffer specifies surface pool management policy. Absence of the attached buffer means MFX_ALLOCATION_UNLIMITED policy: each call of GetSurfaceForXXX leads to surface allocation.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_ALLOCATION_HINTS.

mfxPoolAllocationPolicy AllocationPolicy

Allocation policy.

mfxU32 NumberToPreAllocate

How many surfaces to allocate during Init. It’s applicable for any polices set by mfxPoolAllocationPolicy::AllocationPolicy even if the requested number exceeds recommended size of the pool.

mfxU32 DeltaToAllocateOnTheFly

DeltaToAllocateOnTheFly specifies how many surfaces are allocated in addition to NumberToPreAllocate in MFX_ALLOCATION_LIMITED mode. Maximum number of allocated frames will be NumberToPreAllocate + DeltaToAllocateOnTheFly.

mfxVPPPoolType VPPPoolType

Defines what VPP pool is targeted - input or output. Ignored for other components.

mfxU32 Wait

Time in milliseconds for GetSurfaceForXXX() and DecodeFrameAsync functions to wait until surface will be available.

mfxU32 reserved1[4]

Reserved for future use

mfxRefInterface

struct mfxRefInterface

The structure represents reference counted interface structure. The memory is allocated and released by the implementation.

Public Members

mfxHDL Context

The context of the container interface. User should not touch (change, set, null) this pointer.

mfxStructVersion Version

The version of the structure.

mfxStatus (*AddRef)(struct mfxRefInterface *ref_interface)

Increments the internal reference counter of the container. The container is not destroyed until the container is released using the mfxRefInterface::Release function. mfxRefInterface::AddRef should be used each time a new link to the container is created (for example, copy structure) for proper management.

Param ref_interface:

[in] Valid interface.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If interface is NULL.

MFX_ERR_INVALID_HANDLE If mfxRefInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*Release)(struct mfxRefInterface *ref_interface)

Decrements the internal reference counter of the container. mfxRefInterface::Release should be called after using the mfxRefInterface::AddRef function to add a container or when allocation logic requires it.

Param ref_interface:

[in] Valid interface.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If interface is NULL.

MFX_ERR_INVALID_HANDLE If mfxRefInterface->Context is invalid (for example NULL).

MFX_ERR_UNDEFINED_BEHAVIOR If Reference Counter of container is zero before call.

MFX_ERR_UNKNOWN Any internal error.

mfxStatus (*GetRefCounter)(struct mfxRefInterface *ref_interface, mfxU32 *counter)

Returns current reference counter of mfxRefInterface structure.

Param ref_interface:

[in] Valid interface.

Param counter:

[out] Sets counter to the current reference counter value.

Return:

MFX_ERR_NONE If no error.

MFX_ERR_NULL_PTR If interface or counter is NULL.

MFX_ERR_INVALID_HANDLE If mfxRefInterface->Context is invalid (for example NULL).

MFX_ERR_UNKNOWN Any internal error.

mfxExtMasteringDisplayColourVolume

struct mfxExtMasteringDisplayColourVolume

Handle the HDR SEI message.

During encoding: If the application attaches this structure to the mfxEncodeCtrl structure at runtime, the encoder inserts the HDR SEI message for the current frame and ignores InsertPayloadToggle. If the application attaches this structure to the mfxVideoParam structure during initialization or reset, the encoder inserts the HDR SEI message based on InsertPayloadToggle.

During video processing: If the application attaches this structure for video processing, InsertPayloadToggle will be ignored. And DisplayPrimariesX[3], DisplayPrimariesY[3] specify the color primaries where 0,1,2 specifies Red, Green, Blue respectively.

During decoding: If the application attaches this structure to the mfxFrameSurface1 structure at runtime which will seed to the MFXVideoDECODE_DecodeFrameAsync() as surface_work parameter, the decoder will parse the HDR SEI message if the bitstream include HDR SEI message per frame. The parsed HDR SEI will be attached to the ExtendBuffer of surface_out parameter of MFXVideoDECODE_DecodeFrameAsync() with flag InsertPayloadToggle to indicate if there is valid HDR SEI message in the clip. InsertPayloadToggle will be set to MFX_PAYLOAD_IDR if oneAPI Video Processing Library (oneVPL) gets valid HDR SEI, otherwise it will be set to MFX_PAYLOAD_OFF. This function is support for HEVC only now.

Encoding or Decoding, Field semantics are defined in ITU-T* H.265 Annex D, AV1 6.7.4 Metadata OBU semantics.

Video processing, DisplayPrimariesX[3] and WhitePointX are in increments of 0.00002, in the range of [5, 37000]. DisplayPrimariesY[3] and WhitePointY are in increments of 0.00002, in the range of [5, 42000]. MaxDisplayMasteringLuminance is in units of 1 candela per square meter. MinDisplayMasteringLuminance is in units of 0.0001 candela per square meter.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_MASTERING_DISPLAY_COLOUR_VOLUME.

mfxU16 InsertPayloadToggle

InsertHDRPayload enumerator value.

mfxU16 DisplayPrimariesX[3]

Color primaries for a video source. Consist of RGB x coordinates and define how to convert colors from RGB color space to CIE XYZ color space.

mfxU16 DisplayPrimariesY[3]

Color primaries for a video source. Consists of RGB y coordinates and defines how to convert colors from RGB color space to CIE XYZ color space.

mfxU16 WhitePointX

White point X coordinate.

mfxU16 WhitePointY

White point Y coordinate.

mfxU32 MaxDisplayMasteringLuminance

Specify maximum luminance of the display on which the content was authored.

mfxU32 MinDisplayMasteringLuminance

Specify minimum luminance of the display on which the content was authored.

mfxExtContentLightLevelInfo

struct mfxExtContentLightLevelInfo

Handle the HDR SEI message.

During encoding: If the application attaches this structure to the mfxEncodeCtrl structure at runtime, the encoder inserts the HDR SEI message for the current frame and ignores InsertPayloadToggle. If the application attaches this structure to the mfxVideoParam structure during initialization or reset, the encoder inserts the HDR SEI message based on InsertPayloadToggle.

During video processing: If the application attaches this structure for video processing, InsertPayloadToggle will be ignored.

During decoding: If the application attaches this structure to the mfxFrameSurface1 structure at runtime which will seed to the MFXVideoDECODE_DecodeFrameAsync() as surface_work parameter, the decoder will parse the HDR SEI message if the bitstream include HDR SEI message per frame. The parsed HDR SEI will be attached to the ExtendBuffer of surface_out parameter of MFXVideoDECODE_DecodeFrameAsync() with flag InsertPayloadToggle to indicate if there is valid HDR SEI message in the clip. InsertPayloadToggle will be set to MFX_PAYLOAD_IDR if oneVPL gets valid HDR SEI, otherwise it will be set to MFX_PAYLOAD_OFF. This function is support for HEVC only now.

Field semantics are defined in ITU-T* H.265 Annex D, AV1 6.7.3 Metadata high dynamic range content light level semantics.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to EXTBUFF_CONTENT_LIGHT_LEVEL_INFO.

mfxU16 InsertPayloadToggle

InsertHDRPayload enumerator value.

mfxU16 MaxContentLightLevel

Maximum luminance level of the content. Field range is 1 to 65535.

mfxU16 MaxPicAverageLightLevel

Maximum average per-frame luminance level of the content. Field range is 1 to 65535.

mfxExtSyncSubmission

struct mfxExtSyncSubmission

The structure is used to get a synchronization object which signalizes about submission of a task to GPU.

Public Members

mfxSyncPoint *SubmissionSyncPoint

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_SYNCSUBMISSION. SyncPoint object to get a moment of a submission task to GPU.

mfxU32 reserved1[8]

Reserved for future use.

mfxExtTuneEncodeQuality

struct mfxExtTuneEncodeQuality

The structure specifies type of quality optimization used by the encoder. The buffer can also be attached for VPP functions to make correspondent pre-filtering.

Public Members

mfxExtBuffer Header

Extension buffer header. Header.BufferId must be equal to MFX_EXTBUFF_TUNE_ENCODE_QUALITY.

mfxU32 TuneQuality

The control to specify type of encode quality metric(s) to optimize; See correspondent enum.

mfxExtBuffer **ExtParam

Points to an array of pointers to the extra configuration structures; see the ExtendedBufferID enumerator for a list of extended configurations.

mfxU16 NumExtParam

The number of extra configuration structures attached to the structure.

mfxConfigInterface

struct mfxConfigInterface

Public Members

mfxHDL Context

The context of the config interface. User should not touch (change, set, null) this pointer.

mfxStructVersion Version

The version of the structure.

mfxStatus (*SetParameter)(struct mfxConfigInterface *config_interface, const mfxU8 *key, const mfxU8 *value, mfxStructureType struct_type, mfxHDL structure, mfxExtBuffer *ext_buffer)

Sets a parameter to specified value in the current session. If a parameter already has a value, the new value will overwrite the existing value.

Since

This function is available since API version 2.10.

Param config_interface:

[in] The valid interface returned by calling MFXQueryInterface().

Param key:

[in] Null-terminated string containing parameter to set. The string length must be < MAX_PARAM_STRING_LENGTH bytes.

Param value:

[in] Null-terminated string containing value to which key should be set. The string length must be < MAX_PARAM_STRING_LENGTH bytes. value will be converted from a string to the expected data type for the given key, or return an error if conversion fails.

Param struct_type:

[in] Type of structure pointed to by structure.

Param structure:

[out] If and only if SetParameter returns MFX_ERR_NONE, the contents of structure (including any attached extension buffers) will be updated according to the provided key and value. If key modifies a field in an extension buffer which is not already attached, the function will return MFX_ERR_MORE_EXTBUFFER and fill ext_buffer with the header for the required mfxExtBuffer type.

Param ext_buffer:

[out] If and only if SetParameter returns MFX_ERR_MORE_EXTBUFFER, ext_buffer will contain the header for a buffer of type mfxExtBuffer. The caller should allocate a buffer of the size ext_buffer.BufferSz, copy the header in ext_buffer to the start of this new buffer, attach this buffer to videoParam, then call SetParameter again. Otherwise, the contents of ext_buffer will be cleared.

Return:

MFX_ERR_NONE The function completed successfully. MFX_ERR_NULL_PTR If key, value, videoParam, and/or ext_buffer is NULL. MFX_ERR_NOT_FOUND If key contains an unknown parameter name. MFX_ERR_UNSUPPORTED If value is of the wrong format for key (for example, a string is provided where an integer is required) or if value cannot be converted into any valid data type. MFX_ERR_INVALID_VIDEO_PARAM If length of key or value is >= MAX_PARAM_STRING_LENGTH or is zero (empty string). MFX_ERR_MORE_EXTBUFFER If key requires modifying a field in an mfxExtBuffer which is not attached. Caller must allocate and attach the buffer type provided in ext_buffer then call the function again.