Contents

Dispatcher API Function Reference

API

MFXCreateConfig

mfxConfig MFXCreateConfig(mfxLoader loader)

Creates dispatcher configuration.

Creates the dispatcher internal configuration, which is used to filter out available implementations. 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

Config handle or NULL pointer is failed.

Since

This function is available since API version 2.0.

Parameters

  • [in] loader: Loader handle.

MFXCreateSession

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

Loads and initializes 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 a pointer to the 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.

Since

This function is available since API version 2.0.

Parameters

  • [in] loader: Loader handle.

  • [in] i: Index of the implementation.

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

MFXDispReleaseImplDescription

mfxStatus MFXDispReleaseImplDescription(mfxLoader loader, mfxHDL hdl)

Destroys handle allocated by the MFXEnumImplementations function.

Return

MFX_ERR_NONE The function completed successfully.

MFX_ERR_NULL_PTR If loader is NULL.

MFX_ERR_INVALID_HANDLE Provided hdl handle is not associated with this loader.

Since

This function is available since API version 2.0.

Parameters

  • [in] loader: Loader handle.

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

MFXEnumImplementations

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

Iterates 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 is not supported.

Since

This function is available since API version 2.0.

Parameters

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

MFXLoad

mfxLoader MFXLoad()

Creates the loader.

Return

Loader Loader handle or NULL if failed.

Since

This function is available since API version 2.0.

MFXSetConfigFilterProperty

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

Adds additional filter properties (any fields of the mfxImplDescription structure) to the configuration of the 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 does not equal the parameter with provided name.

Since

This function is available since API version 2.0.

Parameters

  • [in] config: Config handle.

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

  • [in] value: Value of the parameter.

MFXUnload

void MFXUnload(mfxLoader loader)

Destroys the dispatcher.

Since

This function is available since API version 2.0.

Parameters

  • [in] loader: Loader handle.

Dispatcher API Dispatcher API Structure Reference