# 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp 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 ```cpp DIL_ReturnCode DIL_InputMousePosition( DIL_Decoder decoder, float x, float y ); ```