Dispatcher API

Defines

MFX_IMPL_NAME_LEN

Maximum allowed length of the implementation name.

MFX_STRFIELD_LEN

Maximum allowed length of the implementation name.

Enums

mfxImplType

enum mfxImplType

This enum itemizes implementation type.

Values:

enumerator MFX_IMPL_TYPE_SOFTWARE = 0x0001

Pure Software Implementation.

enumerator MFX_IMPL_TYPE_HARDWARE = 0x0002

Hardware Accelerated Implementation.

mfxAccelerationMode

enum mfxAccelerationMode

This enum itemizes hardware acceleration stack to use.

Values:

enumerator MFX_ACCEL_MODE_NA = 0

Hardware acceleration is not applicable.

enumerator MFX_ACCEL_MODE_VIA_D3D9 = 0x0200

Hardware acceleration goes through the Microsoft* Direct3D9* infrastructure.

enumerator MFX_ACCEL_MODE_VIA_D3D11 = 0x0300

Hardware acceleration goes through the Microsoft* Direct3D11* infrastructure.

enumerator MFX_ACCEL_MODE_VIA_VAAPI = 0x0400

Hardware acceleration goes through the Linux* VA-API infrastructure.

Structures

mfxVariant

enum mfxVariantType

The mfxVariantType enumerator data types for mfxVarianf type.

Values:

enumerator MFX_VARIANT_TYPE_UNSET = 0

Undefined type.

enumerator MFX_VARIANT_TYPE_U8 = 1

8-bit unsigned integer.

enumerator MFX_VARIANT_TYPE_I8

8-bit signed integer.

enumerator MFX_VARIANT_TYPE_U16

16-bit unsigned integer.

enumerator MFX_VARIANT_TYPE_I16

16-bit signed integer.

enumerator MFX_VARIANT_TYPE_U32

32-bit unsigned integer.

enumerator MFX_VARIANT_TYPE_I32

32-bit signed integer.

enumerator MFX_VARIANT_TYPE_U64

64-bit unsigned integer.

enumerator MFX_VARIANT_TYPE_I64

64-bit signed integer.

enumerator MFX_VARIANT_TYPE_F32

32-bit single precision floating point.

enumerator MFX_VARIANT_TYPE_F64

64-bit double precision floating point.

enumerator MFX_VARIANT_TYPE_PTR

Generic type pointer.

struct mfxVariant

The mfxVariantType enumerator data types for mfxVarianf type.

Public Members

mfxStructVersion Version

Version of the structure.

mfxVariantType Type

Value type.

union mfxVariant::data Data

Value data member.

union data

Value data holder.

Public Members

mfxU8 U8

mfxU8 data.

mfxI8 I8

mfxI8 data.

mfxU16 U16

mfxU16 data.

mfxI16 I16

mfxI16 data.

mfxU32 U32

mfxU32 data.

mfxI32 I32

mfxI32 data.

mfxU64 U64

mfxU64 data.

mfxI64 I64

mfxI64 data.

mfxF32 F32

mfxF32 data.

mfxF64 F64

mfxF64 data.

mfxHDL Ptr

Pointer.

mfxDecoderDescription

struct mfxDecoderDescription

The mfxDecoderDescription structure represents the description of a decoder.

Public Members

mfxStructVersion Version

Version of the structure.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumCodecs

Number of supported decoders.

struct mfxDecoderDescription::decoder *Codecs

Pointer to the array of decoders.

struct decoder

This structure represents the decoder description.

Public Members

mfxU32 CodecID

Decoder ID in FourCC format.

mfxU16 reserved[8]

Reserved for future use.

mfxU16 MaxcodecLevel

Maximum supported codec level. See the CodecProfile enumerator for possible values.

mfxU16 NumProfiles

Number of supported profiles.

struct mfxDecoderDescription::decoder::decprofile *Profiles

Pointer to the array of profiles supported by the codec.

struct decprofile

This structure represents the codec profile description.

Public Members

mfxU32 Profile

Profile ID. See the CodecProfile enumerator for possible values.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumMemTypes

Number of supported memory types.

struct mfxDecoderDescription::decoder::decprofile::decmemdesc *MemDesc

Pointer to the array of memory types.

struct decmemdesc

This structure represents the underlying details of the memory type.

Public Members

mfxResourceType MemHandleType

Memory handle type.

mfxRange32U Width

Range of supported image widths.

mfxRange32U Height

Range of supported image heights.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumColorFormats

Number of supported output color formats.

mfxU32 *ColorFormats

Pointer to the array of supported output color formats (in FOURCC).

mfxEncoderDescription

struct mfxEncoderDescription

This structure represents an encoder description.

Public Members

mfxStructVersion Version

Version of the structure.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumCodecs

Number of supported encoders.

struct mfxEncoderDescription::encoder *Codecs

Pointer to the array of encoders.

struct encoder

This structure represents encoder description.

Public Members

mfxU32 CodecID

Encoder ID in FourCC format.

mfxU16 MaxcodecLevel

Maximum supported codec level. See the CodecProfile enumerator for possible values.

mfxU16 BiDirectionalPrediction

Indicates B-frames support.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumProfiles

Number of supported profiles.

struct mfxEncoderDescription::encoder::encprofile *Profiles

Pointer to the array of profiles supported by the codec.

struct encprofile

This structure represents the codec profile description.

Public Members

mfxU32 Profile

Profile ID. See the CodecProfile enumerator for possible values.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumMemTypes

Number of supported memory types.

struct mfxEncoderDescription::encoder::encprofile::encmemdesc *MemDesc

Pointer to the array of memory types.

struct encmemdesc

This structure represents the underlying details of the memory type.

Public Members

mfxResourceType MemHandleType

Memory handle type.

mfxRange32U Width

Range of supported image widths.

mfxRange32U Height

Range of supported image heights.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumColorFormats

Number of supported input color formats.

mfxU32 *ColorFormats

Pointer to the array of supported input color formats (in FOURCC).

mfxVPPDescription

struct mfxVPPDescription

This structure represents VPP description.

Public Members

mfxStructVersion Version

Version of the structure.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumFilters

Number of supported VPP filters.

struct mfxVPPDescription::filter *Filters

Pointer to the array of supported filters.

struct filter

This structure represents the VPP filters description.

Public Members

mfxU32 FilterFourCC

Filter ID in FourCC format.

mfxU16 MaxDelayInFrames

Introduced output delay in frames.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumMemTypes

Number of supported memory types.

struct mfxVPPDescription::filter::memdesc *MemDesc

Pointer to the array of memory types.

struct memdesc

This structure represents the underlying details of the memory type.

Public Members

mfxResourceType MemHandleType

Memory handle type.

mfxRange32U Width

Range of supported image widths.

mfxRange32U Height

Range of supported image heights.

mfxU16 reserved[7]

Reserved for future use.

mfxU16 NumInFormats

Number of supported input color formats.

struct mfxVPPDescription::filter::memdesc::format *Formats

Pointer to the array of supported formats.

struct format

This structure represents the input color format description.

Public Members

mfxU32 InFormat

Input color in FourCC format.

mfxU16 reserved[5]

Reserved for future use.

mfxU16 NumOutFormat

Number of supported output color formats.

mfxU32 *OutFormats

Pointer to the array of supported output color formats (in FOURCC).

mfxDeviceDescription

struct mfxDeviceDescription

This structure represents device description.

Public Members

mfxStructVersion Version

Version of the structure.

mfxU16 reserved[7]

reserved for future use.

mfxChar DeviceID[MFX_STRFIELD_LEN]

Null terminated string with device ID.

mfxU16 NumSubDevices

Number of available uniform sub-devices. Pure software implementation can report 0.

struct mfxDeviceDescription::subdevices *SubDevices

Pointer to the array of available sub-devices.

struct subdevices

This structure represents sub-device description.

Public Members

mfxU32 Index

Index of the sub-device, started from 0 and increased by 1.

mfxChar SubDeviceID[MFX_STRFIELD_LEN]

Null terminated string with unique sub-device ID, mapped to the system ID.

mfxU32 reserved[7]

reserved for future use.

mfxImplDescription

struct mfxImplDescription

This structure represents the implementation description.

Public Members

mfxStructVersion Version

Version of the structure.

mfxImplType Impl

Impl type: software/hardware.

mfxAccelerationMode AccelerationMode

Hardware acceleration stack to use. OS dependent parameter. Use VA for Linux* and DX* for Windows*.

mfxVersion ApiVersion

Supported API version.

mfxChar ImplName[MFX_IMPL_NAME_LEN]

Null-terminated string with implementation name given by vendor.

mfxChar License[MFX_STRFIELD_LEN]

Null-terminated string with license name of the implementation.

mfxChar Keywords[MFX_STRFIELD_LEN]

Null-terminated string with comma-separated list of keywords specific to this implementation that dispatcher can search for.

mfxU32 VendorID

Standard vendor ID 0x8086 - Intel.

mfxU32 VendorImplID

Vendor specific number with given implementation ID.

mfxDeviceDescription Dev

Supported device.

mfxDecoderDescription Dec

Decoders configuration.

mfxEncoderDescription Enc

Encoders configuration.

mfxVPPDescription VPP

VPP configuration.

mfxU32 reserved[16]

Reserved for future use.

mfxU32 NumExtParam

Number of extension buffers. Reserved for future use. Must be 0.

mfxExtBuffer **ExtParam

Array of extension buffers.

mfxU64 Reserved2

Reserved for future use.

union mfxImplDescription::[anonymous] ExtParams

Extension buffers. Reserved for future.

Functions

mfxLoader MFXLoad()

This function creates the SDK loader.

Return

Loader SDK loader handle or NULL if failed.

void MFXUnload(mfxLoader loader)

This function destroys the SDK dispatcher.

Parameters
  • [in] loader: SDK loader handle.

mfxConfig MFXCreateConfig(mfxLoader loader)

This function creates dispatcher configuration.

This function creates the dispatcher internal configuration, which is used to filter out available implementations. Then this configuration is used to walk through selected implementations to gather more details and select the appropriate implementation to load. The loader object remembers all created mfxConfig objects and destroys them during the mfxUnload function call.

Multiple configurations per single mfxLoader object are possible.

Usage example:

mfxLoader loader = MFXLoad();
mfxConfig cfg = MFXCreateConfig(loader);
MFXCreateSession(loader,0,&session);
Return

SDK config handle or NULL pointer is failed.

Parameters
  • [in] loader: SDK loader handle.

mfxStatus MFXSetConfigFilterProperty(mfxConfig config, const mfxU8 *name, mfxVariant value)

This function is used to add additional filter properties (any fields of the mfxImplDescription structure) to the configuration of the SDK loader object. One mfxConfig properties can hold only single filter property.

Simple usage example:

mfxLoader loader = MFXLoad();
mfxConfig cfg = MFXCreateConfig(loader);
mfxVariant ImplValue;
ImplValue.Type = MFX_VARIANT_TYPE_U32;
ImplValue.Data.U32 = MFX_IMPL_TYPE_HARDWARE;
MFXSetConfigFilterProperty(cfg,"mfxImplDescription.Impl",ImplValue);
MFXCreateSession(loader,0,&session);
Note

Each new call with the same parameter name will overwrite the previously set value. This may invalidate other properties.

Note

Each new call with another parameter name will delete the previous property and create a new property based on new name’s value.

Usage example with two sessions (multiple loaders):

// Create session with software based implementation
mfxLoader loader1 = MFXLoad();
mfxConfig cfg1 = MFXCreateConfig(loader1);
mfxVariant ImplValueSW;
ImplValueSW.Type = MFX_VARIANT_TYPE_U32;
ImplValueSW.Data.U32 = MFX_IMPL_TYPE_SOFTWARE;
MFXSetConfigFilterProperty(cfg1,"mfxImplDescription.Impl",ImplValueSW);
MFXCreateSession(loader1,0,&sessionSW);

// Create session with hardware based implementation
mfxLoader loader2 = MFXLoad();
mfxConfig cfg2 = MFXCreateConfig(loader2);
mfxVariant ImplValueHW;
ImplValueHW.Type = MFX_VARIANT_TYPE_U32;
ImplValueHW.Data.U32 = MFX_IMPL_TYPE_HARDWARE;
MFXSetConfigFilterProperty(cfg2,"mfxImplDescription.Impl",ImplValueHW);
MFXCreateSession(loader2,0,&sessionHW);

// use both sessionSW and sessionHW
// ...
// Close everything
MFXClose(sessionSW);
MFXClose(sessionHW);
MFXUnload(loader1); // cfg1 will be destroyed here.
MFXUnload(loader2); // cfg2 will be destroyed here.

Usage example with two decoders (multiple config objects):

mfxLoader loader = MFXLoad();

mfxConfig cfg1 = MFXCreateConfig(loader);
mfxVariant ImplValue;
val.Type = MFX_VARIANT_TYPE_U32;
val.Data.U32 = MFX_CODEC_AVC;
MFXSetConfigFilterProperty(cfg1,"mfxImplDescription.mfxDecoderDescription.decoder.CodecID",ImplValue);

mfxConfig cfg2 = MFXCreateConfig(loader);
mfxVariant ImplValue;
val.Type = MFX_VARIANT_TYPE_U32;
val.Data.U32 = MFX_CODEC_HEVC;
MFXSetConfigFilterProperty(cfg2,"mfxImplDescription.mfxDecoderDescription.decoder.CodecID",ImplValue);

MFXCreateSession(loader,0,&sessionAVC);
MFXCreateSession(loader,0,&sessionHEVC);

Return

MFX_ERR_NONE The function completed successfully. MFX_ERR_NULL_PTR If config is NULL.

MFX_ERR_NULL_PTR If name is NULL.

MFX_ERR_NOT_FOUND If name contains unknown parameter name. MFX_ERR_UNSUPPORTED If value data type doesn’t equal to the parameter with provided name.

Parameters
  • [in] config: SDK config handle.

  • [in] name: Name of the parameter (see mfxImplDescription structure and example).

  • [in] value: Value of the parameter.

mfxStatus MFXEnumImplementations(mfxLoader loader, mfxU32 i, mfxImplCapsDeliveryFormat format, mfxHDL *idesc)

This function is used to iterate over filtered out implementations to gather their details. This function allocates memory to store mfxImplDescription structure instance. Use the MFXDispReleaseImplDescription function to free memory allocated to the mfxImplDescription structure.

Return

MFX_ERR_NONE The function completed successfully. The idesc contains valid information.

MFX_ERR_NULL_PTR If loader is NULL.

MFX_ERR_NULL_PTR If idesc is NULL.

MFX_ERR_NOT_FOUND Provided index is out of possible range.

MFX_ERR_UNSUPPORTED If requested format isn’t supported.

Parameters
  • [in] loader: SDK loader handle.

  • [in] i: Index of the implementation.

  • [in] format: Format in which capabilities need to be delivered. See the mfxImplCapsDeliveryFormat enumerator for more details.

  • [out] idesc: Pointer to the mfxImplDescription structure.

mfxStatus MFXCreateSession(mfxLoader loader, mfxU32 i, mfxSession *session)

This function is used to load and initialize the implementation.

mfxLoader loader = MFXLoad();
int i=0;
while(1) {
   mfxImplDescription *idesc;
   MFXEnumImplementations(loader, i, MFX_IMPLCAPS_IMPLDESCSTRUCTURE, (mfxHDL*)&idesc);
   if(is_good(idesc)) {
       MFXCreateSession(loader, i,&session);
       // ...
       MFXDispReleaseImplDescription(loader, idesc);
   }
   else
   {
       MFXDispReleaseImplDescription(loader, idesc);
       break;
   }
}
Return

MFX_ERR_NONE The function completed successfully. The session contains pointer to the SDK session handle.

MFX_ERR_NULL_PTR If loader is NULL.

MFX_ERR_NULL_PTR If session is NULL.

MFX_ERR_NOT_FOUND Provided index is out of possible range.

Parameters
  • [in] loader: SDK loader handle.

  • [in] i: Index of the implementation.

  • [out] session: Pointer to the SDK session handle.

mfxStatus MFXDispReleaseImplDescription(mfxLoader loader, mfxHDL hdl)

This function destroys handle allocated by MFXQueryImplsCapabilities function.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR If loader is NULL.

MFX_ERR_INVALID_HANDLE Provided hdl handle isn’t associated with this loader.

Parameters
  • [in] loader: SDK loader handle.

  • [in] hdl: Handle to destroy. Can be equal to NULL.