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

DIL_ReturnCode DIL_Create( const char*                   json_settings,
                           const DIL_ContextSettings*    context_settings,
                           DIL_Decoder                   instance );

DIL_Destroy

Destroy an instance of a DIL Decoder

• decoder instance to be destroyed

void DIL_Destroy( DIL_Decoder decoder);

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

DIL_ReturnCode DIL_GetImage(DIL_Decoder decoder, DIL_ImageDesc* image_desc, DIL_Image* image);

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

DIL_ReturnCode DIL_ReleaseImage(DIL_Decoder decoder, DIL_Image image);

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

DIL_ReturnCode DIL_ImageGetDesc(DIL_Image image, DIL_ImageDesc* desc);

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

DIL_ReturnCode DIL_ImageSetActiveRegion( DIL_Image                  image,
                                         uint32_t                   offset_x,
                                         uint32_t                   offset_y,
                                         uint32_t                   width,
                                         uint32_t                   height);

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

DIL_ReturnCode DIL_ImageGetActiveRegion( DIL_Image                  image,
                                         uint32_t*                  offset_x,
                                         uint32_t*                  offset_y,
                                         uint32_t*                  width,
                                         uint32_t*                  height);

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

DIL_ReturnCode DIL_ImageGetPlanesCount(DIL_Image image, uint32_t* plane_count);

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

DIL_ReturnCode DIL_ImageSetPlaneBuffer( DIL_Image	                  image,
                                        uint32_t                    plane_index,
                                        DIL_ImagePlaneBufferDesc*   buffer_desc);

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

DIL_ReturnCode DIL_ImageGetPlaneBuffer( DIL_Image                   image,
                                        uint32_t                    plane_index,
                                        DIL_ImagePlaneBufferDesc*   buffer_desc);

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

DIL_ReturnCode DIL_ImageSetPlaneTexture( DIL_Image                  image,
                                         uint32_t                   plane_index,
                                         DIL_ImagePlaneTextureDesc* texture_desc);

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

DIL_ReturnCode DIL_ImageGetPlaneTexture( DIL_Image                  image,
                                         uint32_t                   plane_index,
                                         DIL_ImagePlaneTextureDesc* texture_desc);

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

DIL_ReturnCode DIL_ImageSetPlaneHardwareBuffer( DIL_Image                         image,
                                                uint32_t                          plane_index,
                                                DIL_ImagePlaneHardwareBufferDesc* desc);

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

DIL_ReturnCode DIL_ImageGetPlaneHardwareBuffer( DIL_Image                         image,
                                                uint32_t                          plane_index,
                                                DIL_ImagePlaneHardwareBufferDesc* desc);

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

DIL_ReturnCode DIL_ImageSetUserData(DIL_Image image, void* userdata);

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

DIL_ReturnCode DIL_ImageGetUserData(DIL_Image image, void** userdata);

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

DIL_ReturnCode DIL_ImagePlaneHardwareBufferLock( DIL_Decoder                 decoder,
                                                 DIL_Image                   image,
                                                 uint32_t                    plane_index,
                                                 bool                        read_access,
                                                 bool                        write_access,
                                                 DIL_ImagePlaneBufferDesc*   buffer_desc);

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

DIL_ReturnCode DIL_ImagePlaneHardwareBufferUnlock( DIL_Decoder                 decoder,
                                                   DIL_Image                   image,
                                                   uint32_t                    plane_index);

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

DIL_ReturnCode DIL_AddTSData( DIL_Decoder           decoder,
                              uint16_t              input_cc,
                              uint8_t*              data,
                              uint32_t              size );

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

DIL_ReturnCode DIL_AddWebmData( DIL_Decoder         decoder,
                                uint16_t            input_cc,
                                uint8_t*            data,
                                uint32_t            size );

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

DIL_ReturnCode DIL_AddNALData( DIL_Decoder          decoder,
                               uint16_t             input_cc,
                               int64_t              timestamp,
                               uint8_t*             data,
                               uint32_t             size,
                               DIL_NALFormat        nalu_format );

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

uint32_t DIL_AddNALDataEx( DIL_Decoder              decoder,
                           uint16_t                 input_cc,
                           int64_t                  timestamp,
                           uint8_t*                 data,
                           uint32_t                 size,
                           DIL_NALFormat            nalu_format );

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

DIL_ReturnCode DIL_AddRawData( DIL_Decoder          decoder,
                               uint16_t             input_cc,
                               int64_t              timestamp,
                               uint8_t*             data,
                               uint32_t             size );

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

DIL_ReturnCode DIL_GetDecodeInformation( DIL_Decoder                    decoder,
                                         uint16_t                       input_cc,
                                         int64_t                        timestamp,
                                         uint32_t                       base_width,
                                         uint32_t                       base_height,
                                         DIL_DecodeInformation*         information );

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

DIL_ReturnCode DIL_Decode( DIL_Decoder                      decoder,
                           uint16_t                         input_cc,
                           int64_t                          timestamp,
                           uint32_t                         max_decode_time_us,
                           DIL_Image*                       input,
                           DIL_Image*                       output,
                           DIL_DecodeInformation*           decode_information );

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

DIL_ReturnCode DIL_Render( DIL_Decoder                      decoder,
                           uint16_t                         input_cc,
                           int64_t                          timestamp,
                           DIL_Image                        image,
                           const DIL_RenderInformation*     render_information,
                           int64_t                          delay_us );

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

DIL_ReturnCode DIL_DecodeAndRender( DIL_Decoder                         decoder,
                                    uint16_t                            input_cc,
                                    int64_t                             timestamp,
                                    uint32_t                            max_decode_time_us,
                                    DIL_Image                           input,
                                    const DIL_RenderInformation*        render_information,
                                    DIL_DecodeInformation*              decode_information );

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

DIL_ReturnCode DIL_DecodeSkip( DIL_Decoder              decoder,
                               uint16_t                 input_cc,
                               int64_t                  timestamp );

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

DIL_ReturnCode DIL_Flush( DIL_Decoder              decoder );

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

DIL_ReturnCode DIL_Drain( DIL_Decoder              decoder );

DIL_GetGLContext

Get the DIL's GL Context

• decoder DIL instance

• context pointer to pointer of GL Context

• return DIL API return code

DIL_ReturnCode DIL_GetGLContext( DIL_Decoder            decoder,
                                 void**                 context );

DIL_GetGLDisplay

Get the DIL's GL Display

• decoder DIL instance

• display pointer to pointer of GL Display

• return DIL API return code

DIL_ReturnCode DIL_GetGLDisplay( DIL_Decoder            decoder,
                                 void**                 display);

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

DIL_ReturnCode DIL_SetGLWindow( DIL_Decoder             decoder,
                                void*                   gl_external_window,
                                bool                    is_secure );

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

typedef void (*DILOnExitRequestedCallBack)( void* user_data );

DIL_ReturnCode DIL_SetExitRequestedCallback( DIL_Decoder                    decoder,
                                             DILOnExitRequestedCallBack     callback,
                                             void*                          user_data);

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

typedef void (*DILOnDecodedAsyncCallBack)( DIL_ReturnCode                   result,
                                           uint16_t                         input_cc,
                                           int64_t                          timestamp,
                                           DIL_Image                        input,
                                           DIL_Image                        output,
                                           const DIL_DecodeInformation*     information,
                                           void*                            user_data );

DIL_ReturnCode DIL_SetDecodedAsyncCallback( DIL_Decoder                     decoder,
                                            DILOnDecodedAsyncCallBack       callback,
                                            void*                           user_data );

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

typedef void (*DILOnRenderAsyncCallBack)( DIL_ReturnCode          result,
                                          int64_t                 completion_time_us,
                                          uint16_t                input_cc,
                                          int64_t                 timestamp,
                                          DIL_Image               output,
                                          void*                   user_data );
                                          
DIL_ReturnCode DIL_SetRenderAsyncCallback( DIL_Decoder                      decoder,
                                           DILOnRenderAsyncCallBack         callback,
                                           void*                            user_data );

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

typedef void (*DILOnRenderAsyncCallBack)( DIL_ReturnCode          result,
                                          int64_t                 completion_time_us,
                                          uint16_t                input_cc,
                                          int64_t                 timestamp,
                                          DIL_Image               output,
                                          void*                   user_data );

DIL_ReturnCode DIL_SetRenderResizeAsyncCallback( DIL_Decoder                      decoder,
                                                 DILOnRenderAsyncCallBack         callback,
                                                 void*                            user_data );

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

typedef void (*DILOnSynchronizeCallBack)( void* user_data );

DIL_ReturnCode DIL_SetFlushAsyncCallback( DIL_Decoder                      decoder,
                                          DILOnSynchronizeCallBack         callback,
                                          void*                            user_data );

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

typedef void (*DILOnSynchronizeCallBack)( void* user_data );

DIL_ReturnCode DIL_SetDrainAsyncCallback( DIL_Decoder                      decoder,
                                          DILOnSynchronizeCallBack         callback,
                                          void*                            user_data );

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

DIL_ReturnCode DIL_InputMouseButtonState( DIL_Decoder             decoder,
                                          bool                    pressed );

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

DIL_ReturnCode DIL_InputMousePosition( DIL_Decoder                decoder,
                                       float                      x,
                                       float                      y );