V-NOVA
Search…
V-Nova Documentation
V-NOVA LCEVC
Overview
SDK
Encoder Integration Layer (EIL)
Decoder Integration Layer (DIL)
Player Integrations
LCEVC in FFmpeg
LCEVC in Android Open-Source Project
LCEVC Best Practices
V-Nova Platform
Introduction
Encoding
Decoding
Powered By GitBook
Decoder Integration Layer (DIL)

Introduction

The DIL (Decoder Integration Layer) is the V-Nova library used to integrate LCEVC decoding and rendering to an existing legacy decoder implementation.
The DIL can be used in both:
    Application integration - the DIL renders directly onto an on-screen surface, provided by the client, of arbitrary size (generally different from the content resolution). Examples: ExoPlayer (Android).
    OS Integration - the DIL decodes onto a buffer or draws onto an off screen texture of the same size of the content final resolution, it doesn’t handle the final render to display, including YUV to RGB conversion, and resizing to the destination surface. Examples: MFT (Windows), OMX (Android).
The following block diagram illustrates the role of the DIL more clearly. In conjunction with a base decoder, typically provided by the OS, it offers a complete solution from buffer to output.
Figure 1 Unmodified and LCEVC Pipeline using the DIL

Functionality

Input & output

As shown in the diagram above, the DIL needs two inputs:
    input buffers - the same buffers that are fed to the base decoder in encoding order;
    base decoded frames - produced by the base decoder in presentation order;
and produces an output onto either a
    buffer or
    offscreen texture or
    onscreen surface.

Colour formats

The DIL can operate on a base decoded picture in the following colour formats:
    YUV420 I420 - planar Y, U and V with 4:2:0 subsampled chroma;
    YUV420 NV12 - semi-planar Y (planar), and UV (interleaved) with 4:2:0 subsampled chroma;
    RGB/RGBA - raster Red Green Blue, i.e. on one plane with interleaved colour components;

Modes

The DIL can be configured to work with two types of internal pipeline:
    CPU - all the LCEVC stages are performed in CPU, only using SIMD acceleration, by means of the DPI only, the GPU is used only for the possible YUV/RGB conversion;
    GPU - most of the LCEVC stages are performed in GPU suing GL shaders, including YUV/RGB conversions, while the CPU is only used to produce the LCEVC residual planes at both LOQs

Output type

The DIL offers decoding to either
    on screen
    off screen
On screen refers to a window from the OS window system, currently EGL and GLFW windowing systems are supported.
Off screen refers to an array of buffers or GL textures in memory. The latter case has been designed to allow the client to manage decode and presentation separately, for example to allow buffering/queuing already decoded pictures before display.

Other configurable features

On creating a DIL instance, the client can configure additional features, such as:
    OpenGL major and minor versions (to force a specific version over the system’s selected one);
    Use of OpenGL ES;
    Use of 8 bit LCEVC residual planes - instead of 16 bit
    Use of Hardware Buffers - (Apple and Android only)
    Enable an on screen UI for stats and live config;
    Enable dumping stats to local storage;
    Enable dumping raw output frames to local storage;
The clients configures the DIL at creation time by passing a JSON string and a pair of window system related parameters for context and destination surface.

API Overview

Using the DIL is fairly easy, especially if compared to the more basic DPI, since it operates at a relatively high abstraction level. Apart from obvious creation and destruction of a DIL instance (respectively DIL_Create() and DIL_Destroy()), the main API calls are effectively two:
    Feed input - DIL_AddNALData()
    Decode - DIL_DecodeandRender() (for decoding on screen, alternatively DIL_Decode() for decoding off screen followed by DIL_Render())
    Feed input - DIL_AddNALData()
    Decode - DIL_DecodeandRender() (for decoding on screen, alternatively DIL_Decode() for decoding off screen followed by DIL_Render())
The DIL also offers an API for the client to retrieve the size of the output picture, which can be useful to pre-allocate buffers or textures of the right size before decoding:
    Get size information - DIL_GetDecodeInformation()
Note: input buffers must have NAL byte stream format with either Annex B or Length Prefix format.

Drop/Skip frames

LCEVC content may be encoded with a temporal feature that requires each and every frame to be actioned on in order to keep the DPI internal temporal reference data correct. As a result when the client skips frames, for ex. because of a seek in the timeline, or drops frames because they are “late”, it shall let the DIL know by calling the following function:
    DIL_DecodeSkip()
The DIL does know whether the temporal feature is on and therefore can fall back to a no operation case if that is the case. It is not advised that the client tries to implement this behaviour on its side.

Synchronous and Asynchronous modes

The DIL can be used in both synchronous or asynchronous mode. This is applicable to the decode and render functions:
    DIL_Decode()
    DIL_DecodeAndRender()
    DIL_DecodeSkip()
    DIL_Render()
If the client has previously set the callback function by means of the DIL_SetDecodedAsyncCallback() or DIL_SetRenderAsyncCallback() API calls, the above decode functions will work asynchronously, therefore returning immediately and triggering the client’s callback function when the decode (or render) has completed. If the callback has not been set the functions will work synchronously.

Base pass-through mode

The DIL also supports a pass-through mode, in which the base is simply copied on to the output without applying the LCEVC enhancement. This mode is triggered when no LCEVC data is found for the frame and can be set as forced behaviour, for every frame, from the JSON configuration.

Example Integration Code

In basic terms, a sample integration code using the DIL can be briefly described, among the various phases, as follows:
1
// Include DIL header
2
#include <lcevc_dil.h>
3
// Initialisation phase ///////////////////////////////////////////////////////
4
// Create an instance of the DIL
5
DIL_ContextSettings context_settings = { 0 };
6
char * json_settings = "{\
7
\"gl_decode\": true,\
8
\"gl_es\": true,\
9
\"gl_major\": 3,\
10
\"gl_minor\": 1,\
11
\"swap_interval\": 0,\
12
\"fullscreen\": false,\
13
\"hardware_buffers\": false,\
14
\"use_u8_surface\": false,\
15
\"force_passthrough\": false\
16
}";
17
// Create a DIL instance
18
DIL_Decoder decoder = nullptr;
19
if (DIL_Create(json_settings, &context_settings , &decoder) != DIL_RC_Success)
20
{
21
fprintf(stderr, "Unable to create DIL instance\n");
22
exit(-1);
23
}
24
// Destruction phase //////////////////////////////////////////////////////////
25
DIL_Destroy(decoder);
26
decoder = nullptr;
27
// Handling input buffers /////////////////////////////////////////////////////
28
//...
29
DIL_NALFormat nalFormat;
30
// Set NAL format, from metadata, properties or parsing the input buffers
31
// ...
32
if (DIL_AddNALData(decoder, inputCc, presentationTimeStamp, buffer, length, nalFormat) != DIL_RC_Success)
33
{
34
fprintf(stderr, "Unable to pass input buffer for inputCc=%u pts=%PRId64\n", inputCc, presentationTimeStamp);
35
exit(-2);
36
}
37
// Handling decoded frame from base decoder ///////////////////////////////////
38
// ...
39
// Get size of ouput picture if needed
40
DIL_DecodeInformation decodeInfo;
41
if (DIL_GetDecodeInformation(decoder, inputCc, presentationTimeStamp, baseWidth, baseHeight, &decodeInfo) != DIL_RC_Success)
42
{
43
fprintf(stderr, "DIL get decode info failed for inputCc=%u pts=%PRId64\n", inputCc, baseImage.pts;
44
exit(-3);
45
}
46
// Using decode info
47
// ...
48
DIL_Image baseImage;
49
// Fill the base "Image" struct with the data properties of the base frame
50
// ...
51
DIL_RenderInformation renderInfo;
52
// Fill rotation and pixel aspect ratio
53
// ...
54
if (DIL_DecodeAndRender(decoder, inputCc, presentationTimeStamp, baseImage, &renderInfo, &decodeInfo) != DIL_RC_Success)
55
{
56
fprintf(stderr, "DIL decode failed for pts=%PRId64\n", baseImage.pts;
57
exit(-4);
58
}
59
// Decode info reports if LCEVC is available and has been applied
60
// ...
Copied!

DIL API

DIL_Create

Create an instance of a DIL Decoder
    json_settings JSON string with initialisation parameters
    context_settings settings from the windowing system
    instance decoder instance created
    return DIL API return code
1
DIL_ReturnCode DIL_Create( const char* json_settings,
2
const DIL_ContextSettings* context_settings,
3
DIL_Decoder instance );
Copied!

DIL_Destroy

Destroy an instance of a DIL Decoder
    decoder instance to be destroyed
1
void DIL_Destroy( DIL_Decoder decoder);
Copied!

DIL_GetImage

Returns a fresh usable instance of DIL_Image
    decoder DIL instance
    image_desc Describing Image configurations
    image Result DIL_Image if creation is successful, NULL otherwise
    return DIL_RC_Error if image_desc contains incompatible values
1
DIL_ReturnCode DIL_GetImage(DIL_Decoder decoder, DIL_ImageDesc* image_desc, DIL_Image* image);
Copied!

DIL_ReleaseImage

Releases instance of DIL_Image
NOTE: No reference calls to image address should be made after this method
    decoder DIL instance
    image DIL_Image instance to be released
    return DIL API return code
1
DIL_ReturnCode DIL_ReleaseImage(DIL_Decoder decoder, DIL_Image image);
Copied!

DIL_ImageGetDesc

Will return DIL_ImageDesc of the image
    image DIL_Image to query
    desc Contents of the pointer will be rewritten with image descriptions
    return DIL API return code
1
DIL_ReturnCode DIL_ImageGetDesc(DIL_Image image, DIL_ImageDesc* desc);
Copied!

DIL_ImageSetActiveRegion

Will set the active region for an image
    image DIL_Image instance to modify
    offset_x X offset for the region
    offset_y Y offset for the region
    width width for the region
    height height for the region
    return DIL_RC_Error if crop region is out of bounds, image_type doesn't support cropping
1
DIL_ReturnCode DIL_ImageSetActiveRegion( DIL_Image image,
2
uint32_t offset_x,
3
uint32_t offset_y,
4
uint32_t width,
5
uint32_t height);
Copied!

DIL_ImageGetActiveRegion

Will get the active region for an image
    image DIL_Image instance to modify
    offset_x X offset for the region
    offset_y Y offset for the region
    width width for the region
    height height for the region
    return DIL_RC_Error if crop region is out of bounds, image_type doesn't support cropping
1
DIL_ReturnCode DIL_ImageGetActiveRegion( DIL_Image image,
2
uint32_t* offset_x,
3
uint32_t* offset_y,
4
uint32_t* width,
5
uint32_t* height);
Copied!

DIL_ImageGetPlanesCount

Will return number image's number of planes
    image DIL_Image to query
    plane_count Will be filled with number of planes
    return DIL API return code
1
DIL_ReturnCode DIL_ImageGetPlanesCount(DIL_Image image, uint32_t* plane_count);
Copied!

DIL_ImageSetPlaneBuffer

Will set content and configurations of a plane by data buffer
    image DIL_Image instance to modify
    plane_index Index of the plane to modify
    buffer_desc DIL_ImagePlaneBufferDesc instance to read from
    return DIL_RC_Error if plane_index is out of bounds, image_type is not DIL_Buffer or image is managed
1
DIL_ReturnCode DIL_ImageSetPlaneBuffer( DIL_Image image,
2
uint32_t plane_index,
3
DIL_ImagePlaneBufferDesc* buffer_desc);
Copied!

DIL_ImageGetPlaneBuffer

Will return content and configurations of a plane
    image DIL_Image to query
    plane_index Index of the plane to query
    buffer_desc DIL_ImagePlaneBufferDesc instance to write to
    return DIL_RC_Error if plane_index is out of bounds or image_type is not DIL_Buffer
1
DIL_ReturnCode DIL_ImageGetPlaneBuffer( DIL_Image image,
2
uint32_t plane_index,
3
DIL_ImagePlaneBufferDesc* buffer_desc);
Copied!

DIL_ImageSetPlaneTexture

Will set content and configurations of a plane by OpenGL/GLES texture
    image DIL_Image instance to modify
    plane_index Index of the plane to modify
    texture_desc DIL_ImagePlaneTextureDesc instance to read from
    return DIL_RC_Error if plane_index is out of bounds, image_type is not DIL_Texture or image is managed
1
DIL_ReturnCode DIL_ImageSetPlaneTexture( DIL_Image image,
2
uint32_t plane_index,
3
DIL_ImagePlaneTextureDesc* texture_desc);
Copied!

DIL_ImageGetPlaneTexture

Will return content and configurations of a plane by OpenGL/GLES texture
    image DIL_Image instance to modify
    plane_index Index of the plane to modify
    texture_desc DIL_ImagePlaneTextureDesc instance to read from
    return DIL_RC_Error if plane_index is out of bounds, image_type is not DIL_Texture or image is managed
1
DIL_ReturnCode DIL_ImageGetPlaneTexture( DIL_Image image,
2
uint32_t plane_index,
3
DIL_ImagePlaneTextureDesc* texture_desc);
Copied!

DIL_ImageSetPlaneHardwareBuffer

Will set content and configurations of a plane by OS specific Hardware buffer.
    image DIL_Image instance to modify
    plane_index Index of the plane to modify
    desc DIL_ImagePlaneHardwareBufferDesc instance to read from
    return DIL_RC_Error if plane_index is out of bounds, image_type is not DIL_Texture or image is managed
1
DIL_ReturnCode DIL_ImageSetPlaneHardwareBuffer( DIL_Image image,
2
uint32_t plane_index,
3
DIL_ImagePlaneHardwareBufferDesc* desc);
Copied!

DIL_ImageGetPlaneHardwareBuffer

Will return content and configurations of a plane by OS specific Hardware buffer.
    image DIL_Image instance to query
    plane_index Index of the plane to query
    desc DIL_ImagePlaneHardwareBufferDesc instance to write to
    return Will return DIL_RC_Error if plane_index is out of bounds or image_type is not DIL_HardwareBuffer
1
DIL_ReturnCode DIL_ImageGetPlaneHardwareBuffer( DIL_Image image,
2
uint32_t plane_index,
3
DIL_ImagePlaneHardwareBufferDesc* desc);
Copied!

DIL_ImageSetUserData

Will set the user data associated with the image
    image DIL_Image to set the userdata for
    userdata The userdata to associate with the image
    return DIL_RC_InvalidParam if the image, DIL_RC_Success otherwise
1
DIL_ReturnCode DIL_ImageSetUserData(DIL_Image image, void* userdata);
Copied!

DIL_ImageGetUserData

Will get the user data associated with the image through DIL_ImageSetUserData
    image DIL_Image to get the userdata for
    userdata The userdata to associate with the image
    return DIL_RC_InvalidParam if the image is invalid or userdata is invalid, DIL_RC_Success otherwise
1
DIL_ReturnCode DIL_ImageGetUserData(DIL_Image image, void** userdata);
Copied!

DIL_ImagePlaneHardwareBufferLock

Will return content and configurations of a plane buffer obtained by locking the hardware buffer for CPU access
    image DIL_Image to access
    plane_index Index of the plane to query
    read_access Whether we want read access
    write_access Whether we want write access
    buffer_desc DIL_ImagePlaneBufferDesc instance to write to
    return Will return DIL_RC_Error if plane_index is out of bounds or image_type is not DIL_HardwareBuffer
1
DIL_ReturnCode DIL_ImagePlaneHardwareBufferLock( DIL_Decoder decoder,
2
DIL_Image image,
3
uint32_t plane_index,
4
bool read_access,
5
bool write_access,
6
DIL_ImagePlaneBufferDesc* buffer_desc);
Copied!

DIL_ImagePlaneHardwareBufferUnlock

Will unlock the hardware buffer plane once CPU access is completed.
    image DIL_Image to unlock
    plane_index Index of the plane to query
    return Returns DIL_RC_Error if plane_index is out of bounds or image_type is not DIL_HardwareBuffer
1
DIL_ReturnCode DIL_ImagePlaneHardwareBufferUnlock( DIL_Decoder decoder,
2
DIL_Image image,
3
uint32_t plane_index);
Copied!

DIL_AddTSData

Feed Transport Stream packet(s) for the DIL to extract and store LCEVC data, feed a buffer of TS packets associated with the Access Unit identified by input cc and timestamp
NOTE: input_cc is a feed counter identifying which feed the passed data belongs to, the client shall increment its value every time the input changes, typically because of a playback position change or a rendition change in an ABR playback
NOTE: input_cc shall have monotonically increasing value over calls
    decoder DIL instance
    input_cc input continuity counter
    data pointer to the TS buffer
    size size of the TS buffer
    returns DIL API return code
1
DIL_ReturnCode DIL_AddTSData( DIL_Decoder decoder,
2
uint16_t input_cc,
3
uint8_t* data,
4
uint32_t size );
Copied!

DIL_AddWebmData

Feed Webm payload for the DIL to extract and store LCEVC data
    decoder DIL instance
    input_cc input continuity counter
    data pointer to the TS buffer
    size size of the TS buffer
    returns DIL API return code
1
DIL_ReturnCode DIL_AddWebmData( DIL_Decoder decoder,
2
uint16_t input_cc,
3
uint8_t* data,
4
uint32_t size );
Copied!

DIL_AddNALData

Feed NAL unit(s) for the DIL to extract and store LCEVC data, feed a buffer of NAL units associated with the Access Unit identified by input cc and timestamp
NOTE: input_cc is a feed counter identifying which feed the passed data belongs to, the client shall increment its value every time the input changes, typically because of a playback position change or a rendition change in an ABR playback
NOTE: input_cc shall have monotonically increasing value over calls
NOTE: timestamp shall have monotonically increasing value over calls within the same input_cc
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference for the passed NAL units
    data pointer to the NAL units buffer
    size size of the NAL units buffer
    nalu_format format of the NAL units
    return DIL API return code
1
DIL_ReturnCode DIL_AddNALData( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp,
4
uint8_t* data,
5
uint32_t size,
6
DIL_NALFormat nalu_format );
Copied!

DIL_AddNALDataEx

Feed NAL unit(s) for the DIL to extract and store LCEVC data (Extended), feed a buffer of NAL units associated with the Access Unit identified by input cc and timestamp and additionally let the DIL strip the LCEVC payloads and zero pad the trailing bytes, returning the new size before padding
NOTE: input_cc is a feed counter identifying which feed the passed data belongs to, the client shall increment its value every time the input changes, typically because of a playback position change or a rendition change in an ABR playback
NOTE: input_cc shall have monotonically increasing value over calls
NOTE: timestamp shall have monotonically increasing value over calls within the same input_cc
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference for the passed NAL units
    data pointer to the NAL units buffer
    size size of the NAL units buffer
    nalu_format format of the NAL units
    return size of the stripped NAL units buffer
1
uint32_t DIL_AddNALDataEx( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp,
4
uint8_t* data,
5
uint32_t size,
6
DIL_NALFormat nalu_format );
Copied!

DIL_AddRawData

Feed LCEVC data to the DIL, feed a buffer of pre parsed LCEVC payload data for the Access Unit identified by input cc and timestamp
NOTE: input_cc is a feed counter identifying which feed the passed data belongs to, the client shall increment its value every time the input changes, typically because of a playback position change or a rendition change in an ABR playback
NOTE: input_cc shall have monotonically increasing value over calls
NOTE: timestamp shall have monotonically increasing value over calls within the same input_cc
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference for the passed LCEVC data
    data pointer to the NAL units buffer
    size size of the NAL units buffer
    return DIL API return code
1
DIL_ReturnCode DIL_AddRawData( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp,
4
uint8_t* data,
5
uint32_t size );
Copied!

DIL_GetDecodeInformation

Get details about the decoding process for the Access Unit identified by input cc and timestamp
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference of the picture
    base_width width of the base decoded picture
    base_height height of the base decoded picture
    information pointer to decoder information structure that the DIL will fill
    return DIL API return code
1
DIL_ReturnCode DIL_GetDecodeInformation( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp,
4
uint32_t base_width,
5
uint32_t base_height,
6
DIL_DecodeInformation* information );
Copied!

DIL_Decode

Decode on to an off screen DIL_Image, get an off screen LCEVC enhanced (or base pass-through) picture from the input base picture relative to input cc and timestamp
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference of the picture to be decoded
    max_decode_time_us maximum amount of time the decode has to complete, use 0 to disable decode timeout
    input pointer to decoded base picture for input cc and timestamp (it may be modified if DIL operates in CPU mode)
    output pointer to LCEVC enhanced (or base pass-through) output picture
    decode_information pointer to decoder information structure that the DIL will fill (if DIL_SetDecodedAsyncCallback has not been called)
    return DIL API return code
1
DIL_ReturnCode DIL_Decode( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp,
4
uint32_t max_decode_time_us,
5
DIL_Image* input,
6
DIL_Image* output,
7
DIL_DecodeInformation* decode_information );
Copied!

DIL_Render

Render to back buffer a previously decoded DIL_Image
NOTE: for the scheduled render to be set DIL_SetRenderAsyncCallback must have been previously called
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference of the picture to be rendered
    image pointer to a picture to be rendered to back buffer
    render_information pointer to a render information structure
    delay_us delay in microseconds for the render to eb executed (0 for no delay)
    return DIL API return code
1
DIL_ReturnCode DIL_Render( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp,
4
DIL_Image image,
5
const DIL_RenderInformation* render_information,
6
int64_t delay_us );
Copied!

DIL_DecodeAndRender

Decode and render immediately to back buffer
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference of the picture to be decoded and rendered
    max_decode_time_us maximum amount of time the decode has to complete, use 0 to disable decode timeout
    input pointer to decoded base picture for input cc and timestamp (it may be modified if DIL operates in CPU mode)
    render_information pointer to a render information structure
    decode_information pointer to decoder information structure that the DIL will fill (if DIL_SetDecodedAsyncCallback has not been called)
    return DIL API return code
1
DIL_ReturnCode DIL_DecodeAndRender( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp,
4
uint32_t max_decode_time_us,
5
DIL_Image input,
6
const DIL_RenderInformation* render_information,
7
DIL_DecodeInformation* decode_information );
Copied!

DIL_DecodeSkip

Let the DIL know that an Access Unit is not being presented (dropped or skipped), DIL will do the minimum processing to keep internal state consistent for the next picture
NOTE: this call will generate a DecodeAsyncCallback if previously set
NOTE: calling this on an IDR Access Unit is undefined behaviour
    decoder DIL instance
    input_cc input continuity counter
    timestamp time reference for the Access Unit to be skipped
    return DIL API return code
1
DIL_ReturnCode DIL_DecodeSkip( DIL_Decoder decoder,
2
uint16_t input_cc,
3
int64_t timestamp );
Copied!

DIL_Flush

Synchronize client and DIL by throwing away any pending decodes and renders and waiting for all callbacks to complete
NOTE: all callbacks set by DecodeAsyncCallback and RenderAsyncCallback will be called with a the result filed in the callback will indicate the error DIL_RC_Flushed making DIL calls in this callback could result in a deadlock use the DIL_SetFlushAsyncCallback to break this loop
    decoder DIL instance
    return DIL API return code
1
DIL_ReturnCode DIL_Flush( DIL_Decoder decoder );
Copied!

DIL_Drain

synchronize client and DIL by allowing any pending decodes and renders to complete and waiting for all callbacks to complete
NOTE: all callbacks set by DecodeAsyncCallback and RenderAsyncCallback will be called making DIL calls in this callback could result in a deadlock use the DIL_SetDrainAsyncCallback to break this loop
    decoder DIL instance
    return DIL API return code
1
DIL_ReturnCode DIL_Drain( DIL_Decoder decoder );
Copied!

DIL_GetGLContext

Get the DIL's GL Context
    decoder DIL instance
    context pointer to pointer of GL Context
    return DIL API return code
1
DIL_ReturnCode DIL_GetGLContext( DIL_Decoder decoder,
2
void** context );
Copied!

DIL_GetGLDisplay

Get the DIL's GL Display
    decoder DIL instance
    display pointer to pointer of GL Display
    return DIL API return code
1
DIL_ReturnCode DIL_GetGLDisplay( DIL_Decoder decoder,
2
void** display);
Copied!

DIL_SetGLWindow

Set the DIL's GL output window
    decoder DIL instance
    gl_external_window pointer to destination window
    is_secure true if the destination window is secure
    return DIL API return code
1
DIL_ReturnCode DIL_SetGLWindow( DIL_Decoder decoder,
2
void* gl_external_window,
3
bool is_secure );
Copied!

DIL_SetExitRequestedCallback

Set ExitRequest call back function
    decoder DIL instance
    callback pointer to DILOnExitRequestedCallBack function
    user_data pointer to client's user data
    return DIL API return code
1
typedef void (*DILOnExitRequestedCallBack)( void* user_data );
2
​
3
DIL_ReturnCode DIL_SetExitRequestedCallback( DIL_Decoder decoder,
4
DILOnExitRequestedCallBack callback,
5
void* user_data);
6
​
Copied!

DIL_SetDecodedAsyncCallback

Set asynchronous on decoded call back function
    result result of the decode request, see DIL_ReturnCode
    input_cc input continuity counter
    timestamp time reference of the picture that was decoded
    input pointer to base input picture, the same passed in the previous DIL_Decode
    output pointer to LCEVC enhanced (or base pass-through) output picture, the same passed in the previous DIL_Decode
    information pointer to decoder information structure (not the same passed in from the previous DIL_Decode)
    user_data pointer to the same client's user data that was passed into the DIL_SetDecodedAsyncCallback
​
    decoder DIL instance
    callback pointer to DILOnDecodedAsyncCallBack function
    user_data pointer to client's user data
    return DIL API return code
​
1
typedef void (*DILOnDecodedAsyncCallBack)( DIL_ReturnCode result,
2
uint16_t input_cc,
3
int64_t timestamp,
4
DIL_Image input,
5
DIL_Image output,
6
const DIL_DecodeInformation* information,
7
void* user_data );
8
​
9
DIL_ReturnCode DIL_SetDecodedAsyncCallback( DIL_Decoder decoder,
10
DILOnDecodedAsyncCallBack callback,
11
void* user_data );
Copied!

DIL_SetRenderAsyncCallback

Set asynchronous on render callback function
    result result of render request, see DIL_ReturnCode
    completion_time_us actual time in microseconds the render completed
    input_cc input continuity counter
    timestamp time reference of the picture that was rendered
    output pointer to the same picture passed in with the DIL_Render method
    user_data pointer to the same client's user data that was passed into the DIL_SetRenderAsyncCallback
​
    decoder DIL instance
    callback pointer to DILOnRenderAsyncCallBack function
    user_data pointer to client's user data
    return DIL API return code
1
typedef void (*DILOnRenderAsyncCallBack)( DIL_ReturnCode result,
2
int64_t completion_time_us,
3
uint16_t input_cc,
4
int64_t timestamp,
5
DIL_Image output,
6
void* user_data );
7
8
DIL_ReturnCode DIL_SetRenderAsyncCallback( DIL_Decoder decoder,
9
DILOnRenderAsyncCallBack callback,
10
void* user_data );
Copied!

DIL_SetRenderResizeAsyncCallback

Called at the start of the render process when the image to be displayed has a different size to the last image rendered. This is a blocking call and there should be no DIL calls in the callback function.
    result result of render request, see DIL_ReturnCode
    completion_time_us actual time in microseconds the render completed
    input_cc input continuity counter
    timestamp time reference of the picture that was rendered
    output pointer to the same picture passed in with the DIL_Render method
    user_data pointer to the same client's user data that was passed into the DIL_SetRenderAsyncCallback
​
    decoder DIL instance
    callback pointer to DILOnRenderAsyncCallBack function
    user_data pointer to client's user data
    return DIL API return code
1
typedef void (*DILOnRenderAsyncCallBack)( DIL_ReturnCode result,
2
int64_t completion_time_us,
3
uint16_t input_cc,
4
int64_t timestamp,
5
DIL_Image output,
6
void* user_data );
7
​
8
DIL_ReturnCode DIL_SetRenderResizeAsyncCallback( DIL_Decoder decoder,
9
DILOnRenderAsyncCallBack callback,
10
void* user_data );
11
​
Copied!

DIL_SetFlushAsyncCallback

Callback function for the DIL_Flush() function
    user_data pointer to client's user data
​
    decoder DIL instance
    callback pointer to DILOnSynchronizeCallBack function
    user_data pointer to client's user data
    return DIL API return code
1
typedef void (*DILOnSynchronizeCallBack)( void* user_data );
2
​
3
DIL_ReturnCode DIL_SetFlushAsyncCallback( DIL_Decoder decoder,
4
DILOnSynchronizeCallBack callback,
5
void* user_data );
Copied!

DIL_SetDrainAsyncCallback

Callback function for the DIL_Drain() function
    user_data pointer to client's user data
​
    decoder DIL instance
    callback pointer to DILOnSynchronizeCallBack function
    user_data pointer to client's user data
    return DIL API return code
1
typedef void (*DILOnSynchronizeCallBack)( void* user_data );
2
​
3
DIL_ReturnCode DIL_SetDrainAsyncCallback( DIL_Decoder decoder,
4
DILOnSynchronizeCallBack callback,
5
void* user_data );
Copied!

DIL_InputMouseButtonState

Pass the DIL the position of the input mouse button
    decoder DIL instance
    pressed true if button is pressed
    return DIL API return code
1
DIL_ReturnCode DIL_InputMouseButtonState( DIL_Decoder decoder,
2
bool pressed );
Copied!

DIL_InputMousePosition

Pass the DIL the position of the input mouse
    decoder DIL instance
    x horizontal coordinate of the mouse cursor
    y vertical coordinate of the mouse cursor
    return DIL API return code
1
DIL_ReturnCode DIL_InputMousePosition( DIL_Decoder decoder,
2
float x,
3
float y );
Copied!

DIL Types and Enumerations

DIL_NALFormat enum

DIL_NALFormat represents the two possible NAL Unit formats, for each of the MPEG base codecs the DIL currently supports: H264 (ISO/IEC 14496-10, aka AVC) and H265 (ISO/IEC 23008-2, aka HEVC) NAL, where Annex B indicates 3 byte 0x000001 or 4 byte 0x00000001 start code prefix as described in Annex B of (H264 or HEVC), LP (Length Prefix) indicates a 4 byte prefix with the length of the NAL unit as MSBF 32 bit unsigned int.
1
typedef enum DIL_NALFormat
2
{
3
DIL_UnknownNALFormat = 0,
4
DIL_H264_AnnexB,
5
DIL_H265_AnnexB,
6
DIL_H264_LP,
7
DIL_H265_LP
8
} DIL_NALFormat;
Copied!

DIL_ReturnCode enum

DIL_ReturnCode represents the possible API return codes. Most of the API calls will return one of these values.
1
typedef enum DIL_ReturnCode
2
{
3
DIL_RC_Success = 0, /* The API call completed successfully */
4
DIL_RC_Error = -1, /* A generic catch all error */
5
DIL_RC_InvalidParam = -2, /* The user supplied an invalid parameter to the function call */
6
DIL_RC_NotFound = -3, /* The query call failed to find the item by name, but didn't not generate an error. */
7
DIL_RC_NotSupported = -4, /* The functionality requested is not supported on the running system. */
8
DIL_RC_Flushed = -5, /* The requested operation failed because it was flushed via DIL_Flush. */
9
DIL_RC_Timeout = -6 /* The requested operation failed because it timedout. */
10
} DIL_ReturnCode;
Copied!

DIL_ColorFormat enum

This enum represents the supported colour formats, currently only 8 bit per sample formats are supported For a detailed description of the formats see: https://gstreamer.freedesktop.org/documentation/additional/design/mediatype-video-raw.html​
1
typedef enum DIL_ColorFormat
2
{
3
DIL_UnknownColorFormat = 0, /* Unspecified colour format */
4
DIL_I420_8, /* 8 bit 4:2:0 YUV Planar colour format: Y, U and V on separate planes */
5
DIL_NV12_8, /* 8 bit 4:2:0 YUV SemiPlanar colour format: Y plane and UV interleaved plane */
6
DIL_RGB_8, /* 8 bit Interleaved R, G, B planes 24 bit per sample */
7
DIL_RGBA_8, /* 8 bit Interleaved R, G, B and A planes 32 bit per sample */
8
DIL_I420_10LE, /* 10 bit Little Endian 4:2:0 YUV Planar colour format: Y, U and V on separate planes */
9
​
10
} DIL_ColorFormat;
11
​
Copied!

DIL_ImageType enum

This enum identifies the type of planes the DIL_Image consists of; planes are non-overlapping sets of samples belonging to one or more colour channels with a constant sample stride, so RGB is a single plane, because R G and B pointed at separately would overlap UV from NV12 is a single plane, because U and V pointed at separately would overlap Y U and V from I420 are three planes because they do not overlap
1
typedef enum DIL_ImageType
2
{
3
DIL_UnknownImageType = 0, /* Unspecified image type */
4
DIL_Buffer_Array, /* One buffer per plane, even if image is on a single memory allocation, an array of planes shall be set by assigning the right pointers to plane buffers. DIL allocated buffers have contiguous memory allocation */
5
DIL_Texture_Array, /* One texture per plane, typically in YUV colour formats, it consists of a single plane, even for YUV, if GL YUV extension is used */
6
DIL_HardwareBuffer_Array /* One HardwareBuffer per plane, typically in YUV colour formats, it consists of a single plane, even for YUV, if GL YUV extension is used */
7
} DIL_ImageType;
8
​
Copied!

DIL_ImageDesc struct

Holds configurations of a single DIL_Image instance
1
typedef struct DIL_ImageDesc
2
{
3
bool is_managed; /* True means that Image (and its memory) is managed by DIL */
4
DIL_ImageType image_type; /* Whether it is a buffer array or a texture array */
5
DIL_ColorFormat color_format; /* Colour format */
6
uint32_t width; /* Nominal net width of the image in luma samples, i.e. no alignment to macroblocks or striding */
7
uint32_t height; /* Nominal net height of the image in luma samples, i.e. no sliceheight or padding */
8
bool can_modify; /* Specifying wether content of image is readOnly or changable */
9
bool can_resize; /* Specifying wether allocated memory is resizable or not. (Does not apply to DIL_Buffer_External) */
10
uint32_t options; /* options used in creating the Image, in the case of HardwareBuffers this is a combination of DIL_HardwareBufferUsageOption */
11
} DIL_ImageDesc;
Copied!

DIL_ContextSettings struct

This structure holds parameters related to the window surface the DIL would render into, in case of on screen rendering those parameters are normally provided by the windowing system, e.g. EGL, GLFW.
1
typedef struct DIL_ContextSettings
2
{
3
void* gl_external_window; /* Surface window, from the windowing system */
4
void* gl_external_context; /* Context, from the windowing system */
5