Parameter Configuration

Intel^® VPL API 2.10 introduces a new interface for configuring Intel^® VPL for encode, decode, or video processing. Applications may optionally use the new function mfxConfigInterface::SetParameter to fill in data structures used for initialization, including mfxVideoParam and extension buffers of type mfxExtBuffer.

mfxConfigInterface::SetParameter accepts as input key-value pairs of char * strings, converts these strings to appropriate C data types, and writes the results into the application-provided initialization structures. This can provide a simpler and more flexible initialization method for applications which accept user input in the form of strings, or which store configuration information in formats such as XML, YAML, or JSON.

Applications may freely mix use of mfxConfigInterface::SetParameter with standard C-style initialization of the same structures. Additionally, the use of mfxConfigInterface::SetParameter facilitates support of new parameters which may be added to Intel^® VPL API in the future. When new extension buffers are added to Intel^® VPL API, mfxConfigInterface::SetParameter will enable the application to allocate buffers of the appropriate size, and initialize them with the required values, without recompiling the application.

Setting a parameter in mfxVideoParam

The following code snippet shows an example of setting a parameter in the structure mfxVideoParam.

// call MFXVideoCORE_GetHandle to obtain mfxConfigInterface
mfxConfigInterface *iface = nullptr;
sts = MFXVideoCORE_GetHandle(session, MFX_HANDLE_CONFIG_INTERFACE, (mfxHDL *)(&iface));

// Alternately, we could use the following alias:
// sts = MFXGetConfigInterface(session, &iface);

// pass string parameter which maps to mfxVideoParam
mfxVideoParam par   = {};
mfxExtBuffer extBuf = {};
sts = iface->SetParameter(iface, (mfxU8 *)"TargetKbps", (mfxU8 *)"1650", MFX_STRUCTURE_TYPE_VIDEO_PARAM, &par, &extBuf);

Setting a parameter in an extension buffer

The following code snippet shows an example of setting a parameter in the extension buffer mfxExtHEVCParam and attaching it to the structure mfxVideoParam.

When setting a parameter which maps to an extension buffer, the function first checks whether the required extension buffer has been attached to the provided mfxVideoParam. If so, Intel^® VPL will update the corresponding field in the extension buffer and return MFX_ERR_NONE.

If the required extension buffer is not attached, Intel^® VPL will instead return MFX_ERR_MORE_EXTBUFFER. If this happens, the application is required to allocate an extension buffer whose size and buffer ID are indicated by the ext_buffer parameter returned from the call to mfxConfigInterface::SetParameter. This extension buffer must then be attached to mfxVideoParam, then mfxConfigInterface::SetParameter should be called again with the same arguments. If the key and value strings represent a valid parameter in the newly-attached extension buffer, the function will now return MFX_ERR_NONE.

// call MFXGetConfigInterface() to obtain mfxConfigInterface
mfxConfigInterface *iface = nullptr;
sts = MFXGetConfigInterface(session, &iface);

// pass string parameter which maps to an Intel® VPL extension buffer
mfxVideoParam par   = {};
mfxExtBuffer extBuf = {};
sts = iface->SetParameter(iface, (mfxU8 *)"mfxExtHEVCParam.PicWidthInLumaSamples", (mfxU8 *)"640", MFX_STRUCTURE_TYPE_VIDEO_PARAM, &par, &extBuf);

// if extension buffer has not already been attached, allocate it and call again
if (sts == MFX_ERR_MORE_EXTBUFFER) {
    // the first call to SetParameter filled in extBuf with the buffer ID and size to allocate
    mfxExtBuffer *extBufNew = (mfxExtBuffer *)calloc(extBuf.BufferSz, 1);
    if (!extBufNew)
        return MFX_ERR_MEMORY_ALLOC;

    extBufNew->BufferId = extBuf.BufferId;
    extBufNew->BufferSz = extBuf.BufferSz;

    extBufVector.push_back(extBufNew);
    par.NumExtParam = static_cast<mfxU16>(extBufVector.size());
    par.ExtParam    = extBufVector.data();

    // the correct extension buffer is now attached, so the call should succeed this time
    sts = iface->SetParameter(iface, (mfxU8 *)"mfxExtHEVCParam.PicWidthInLumaSamples", (mfxU8 *)"640", MFX_STRUCTURE_TYPE_VIDEO_PARAM, &par, &extBuf);

    if (sts != MFX_ERR_NONE)
        return sts;
    }

return MFX_ERR_NONE;