Intel® oneAPI Programming Guide

Programming Guide

Contents

oneVPL Code Sample

oneVPL provides rich code samples to show how to use the oneVPL API. The code samples are included in the release package and are also available from the oneAPI-samples repository on GitHub*.
For example, the hello-decode sample shows a simple decode operation of HEVC input streams and demonstrates the basic steps in the oneVPL programming model.
The sample can be broken down into the following key steps in the code:
The snippets below may not reflect the latest version of the sample. Refer to the release package or sample repository for the latest version of this example.
  1. Initialize oneVPL session with dispatcher: 
    mfxLoader loader = NULL;
mfxConfig cfg = NULL;

loader = MFXLoad();

cfg = MFXCreateConfig(loader);
ImplValue.Type = MFX_VARIANT_TYPE_U32;
ImplValue.Data.U32 = MFX_CODEC_HEVC;
sts = MFXSetConfigFilterProperty(cfg, (mfxU8*)"mfxImplDescription.mfxDecoderDescription.decoder.CodecID", ImplValue);

sts = MFXCreateSession(loader, 0, &session);
    Here,
    MFXCreateConfig()
     creates the dispatcher internal configuration. Once the dispatcher is configured, the application uses
    MFXSetConfigFilterProperty()
     to set its requirements including codec ID and accelerator preference. After the application sets the desired requirements, the session is created.
  2. Start the decoding loop: 
    while(is_stillgoing) {
    sts = MFXVideoDECODE_DecodeFrameAsync(session,
              (isdraining) ? NULL : &bitstream,
              NULL,
              &pmfxOutSurface,
              &syncp);
......
}
    After preparing the input stream, the stream has the required context and the decoding loop is started immediately.
    MFXVideoDECODE_DecodeFrameAsync()
     takes the bit stream as the second parameter. When the bit stream becomes NULL, oneVPL drains the remaining frames from the input and completes the operation. The third parameter is the working memory; the NULL input shown in the example means the application wants oneVPL to manage working memory.
  3. Evaluate results of a decoding call: 
    while(is_stillgoing) {
    sts = MFXVideoDECODE_DecodeFrameAsync(...);

    switch(sts) {
        case MFX_ERR_MORE_DATA:
            ......
                ReadEncodedStream(bitstream, codec_id, source);
                ......
            }
            break;

        case MFX_ERR_NONE:
            do {
                sts = pmfxOutSurface->FrameInterface->Synchronize(pmfxOutSurface, WAIT_100_MILLSECONDS);
                if( MFX_ERR_NONE == sts ) {
                    sts = pmfxOutSurface->FrameInterface->Map(pmfxOutSurface, MFX_MAP_READ);

                    WriteRawFrame(pmfxOutSurface, sink);

                    sts = pmfxOutSurface->FrameInterface->Unmap(pmfxOutSurface);

                    sts = pmfxOutSurface->FrameInterface->Release(pmfxOutSurface);

                    framenum++;
                }
            } while( sts == MFX_WRN_IN_EXECUTION );
            break;

        default:
            break;
    }
    For each
    MFXVideoDECODE_DecodeFrameAsync()
     call, the application continues to read the input bit stream until oneVPL completes a new frame with
    MFX_ERR_NONE
    , indicating the function successfully completed its operation. For each new frame, the application waits until the output memory
    (surface)
     is ready and then outputs and releases the output frame.
    The
    Map()
     call is used to map the memory from the discrete graphic memory space to the host memory space.
  4. Exit and do cleanup: 
    MFXUnload(loader);
free(bitstream.Data);
    fclose(sink);
    fclose(source);
    Finally,
    MFXUnload()
     is called to reclaim the resources from oneVPL. This is the only call that the application must execute to reclaim the oneVPL library resources.
This example explains the key steps in the oneVPL programming model. It does not explain utility functions for input and output.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.