This chapter describes the Application Program Interfaces (APIs) of the lib264 video decoder. Application uses these APIs to interact with the codec library and to exchange the data with it. There is a single entry point to the decoder library via following API:
| Decoder API | ||
|---|---|---|
| Name | <DecoderName>_api_function() | |
| Purpose | This is an API function of the decoder for the application, and is the only entry point to the decoder library. | |
| Prototype | void <DecoderName>_api_function()(iv_obj_t *dec_hdl, void *pv_api_ip, void *pv_api_op); | |
| Argument details | Arguement | Description |
| iv_obj_t *dec_hdl | Pointer to the codec instance called as decoder handle. | |
| void *pv_api_ip | Pointer to the APIs input structure type-casted as void pointer. | |
| void *pv_api_op | Pointer to the APIs output structure type-casted as void pointer. | |
Table: Decoder API Details
The input structure passed depends on the purpose of the call. That is, for a control call to get the version information, the input structure will be ivd_ctl_getversioninfo_ip_t.
All the input structures have the e_cmd Enumeration data type as the second field. Application calls the API with a suitable value of e_cmd Enum. Decoder reads this command and performs the desired functionality. For example, if the application wants to initialize the lib264 decoder, it shall call the lib264_library with e_cmd set as IVD_CMD_INIT and the input structure will be ivd_init_ip_t . Apart from e_cmd, the input structure contains the parameters necessary for codec configuration and other input parameters needed by the library interface to process the input bit stream. The output structure contains the status code and other parameters returned by the library based on the command passed to the decoder. Handle contains the pointer to memory records location and the data structure containing all the persistent state variables of the decoder.
The following sub-sections describe the various functionalities exported by the above API. Application should set the appropriate values of e_cmd parameter and the other fields in the appropriate input structure. Status of the API call and the other outputs are returned in the output structure. An application typecasts the input and the output structure pointers as void pointers before it makes a call to the API. On receiving the command via e_cmd parameter, the Decoder calls the suitable function to perform the functionality, corresponding to the current command. Decoder also type casts the input/output structures suitably according to the e_cmd.
NOTE: void pointer variable in the input and output structure for each API has been kept for extension purpose of the API and is an optional parameter.
| Get Number of Memory Records API | ||
|---|---|---|
| Purpose | Application uses this API functionality to find the number of memory records needed by the decoder library. The application then allocates sufficient memory to store all the memory records. | |
| Input Structure | typedef struct { UWORD32 u4_size; IV_API_COMMAND_TYPE_T e_cmd; } iv_num_mem_rec_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the function to be performed by decoder library. For memory query, command should be IV_CMD_GET_NUM_MEM_REC; | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; UWORD32 u4_num_mem_rec; } iv_num_mem_rec_op_t; |
|
| Output Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For the error and status codes refer Error/Status Codes | |
| u4_num_mem_rec | Number of memory records neededby decoder. | |
Table: Number of memory records API
| Fill Memory Records API | ||
|---|---|---|
| Purpose | Application asks the decoder to fill the details of all the memory records through this API call. Decoder fills the size, type of memory (scratch/persistent), alignment requirements of each memory record. The application uses these memory attributes to allocate memory in appropriate region of memory. | |
| Input Structure | typedef struct { UWORD32 u4_size; IV_API_COMMAND_TYPE_T e_cmd; iv_mem_rec_t *pv_mem_rec_location; UWORD32 u4_max_frm_wd; UWORD32 u4_max_frm_ht; } iv_fill_mem_rec_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the function to be performed by decoder library. For fill memory records query, command should be IV_CMD_FILL_NUM_MEM_REC | |
| pv_mem_rec_location | Pointer pointing to the data structure containing the mem tabs. | |
| u4_max_frm_wd | The parameter tells the width of current video sequence, this is either known through file container information, or application can also pass maximum width it supports. This information shall be used by the decoder to calculate the memory requirements. | |
| u4_max_frm_ht | The parameter tells the height of current video sequence,this is either known through file container information, or application can also pass maximum height it supports. This information shall be used by the decoder to calculate the memory requirements. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; UWORD32 u4_num_mem_rec_filled; } iv_fill_mem_rec_op_t; |
|
| Output Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For error and status codes refer Error/Status Codes | |
| u2_num_mem_rec_filled | This parameter specifies the number of memory records actually filled by decoder library. | |
Table: Fill memory records API
| Retrieve Memory Records API | ||
|---|---|---|
| Purpose | This is the API call to retrieve the memory records that were allocated to the decoder during initialization. This will be used in the deletion of the instance of the codec. | |
| Input Structure | typedef struct { UWORD32 u4_size; IV_API_COMMAND_TYPE_T e_cmd; iv_mem_rec_t *pv_mem_rec_location; } iv_retrieve_mem_rec_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the function to be performed by decoder library. For memory query, command should be IV_CMD_RETRIEVE_MEMREC | |
| pv_mem_rec_location | This is the pointer in which the decoder fills the memory record attributes along with the memory pointer allocated by the application. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; UWORD32 u4_num_mem_rec_filled; } iv_retrieve_mem_rec_op_t; |
|
| Output Structure Details | Parameter | Description |
| u4_size | ||
| u4_error_code | For error and status codes refer Error/Status Codes | |
| u4_num_mem_rec_filled | This parameter specifies the number of memory records actually filled by decoder library. | |
Table: Retrieve Memory Records API
| Initialize decoder API | ||
|---|---|---|
| Purpose | All the persistent state variables and the memory records are initialized internally in the decoder and a decoder object is returned as a codec Handle. Refer section 3.3 for the handle definition. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; UWORD32 u4_num_mem_rec; UWORD32 u4_frm_max_wd; UWORD32 u4_frm_max_ht; IV_COLOR_FORMAT_T e_output_format; iv_mem_rec_t *pv_mem_rec_location; } ivd_init_ip_t; |
|
| Input Structure Details | API Parameter |
Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the function to be performed by decoder library. To initialize decoder, command should be IVD_CMD_INIT | |
| u4_num_mem_rec | This parameter specifies the number of memory records for which memory is allocated. This shall be same as that returned during IV_CMD_GET_NUM_MEM_REC call | |
| u4_frm_max_wd | The parameter tells the width of current video sequence, this is either known through file container information, or application can also pass maximum width it supports | |
| u4_frm_max_ht | The parameter tells the height of current video sequence, this is either known through file container information, or application can also pass maximum height it supports | |
| e_output_format | The parameter gives the output color format expected. | |
| pv_mem_rec_location | This pointer holds the memory records that have been allocated by the application. The allocation has to be as per the decoder request (or at least compatible to the request) after the fill memory records API call. If any of the memory records is incompatible, the init call will fail. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; } ivd_init_op_t; |
|
| Output Structure Details | API Parameter |
Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For error and status codes refer Error/Status Codes | |
Table: initialize decoder API
| Video Control API | ||||
|---|---|---|---|---|
| Purpose | This API is used to make control calls to change run time parameters, query the status, flush decoder and to set the decoder in the required state before the frame decode call. For more details refer the Video Control API command type data structure. This varies depending upon the e_sub_cmd. For details refer the individual data structures corresponding to each control API command type. However common parameters are explained. | |||
| Input Structure |
typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; . . }<structure_name> The <structure_name> depends on the type of control call. The various structures available are: |
|||
| Structure Name | e_sub_cmd | Description | ||
| ivd_ctl_flush_ip_t | IVD_CMD_CTL_FLUSH | Input structure for control call to flush. | ||
| ivd_ctl_reset_ip_t | IVD_CMD_CTL_RESET | Input structure for control call to reset. | ||
| ivd_ctl_set_config_ip_t | IVD_CMD_CTL_SETPARAMS | Input structure for control call to set the config parameters. | ||
| IVD_CMD_CTL_SETDEFAULT | Input structure for control call to set the config parameters to default. | |||
| ivd_ctl_getbufinfo_ip_t | IVD_CMD_CTL_GETBUFINFO | Input structure for control call to get the buffer information. | ||
| ivd_ctl_getstatus_ip_t | IVD_CMD_CTL_GETPARAMS | Input structure for control call to get the parameter values of decoder. | ||
| ivd_ctl_getversioninfo_ip_t | IVD_CMD_CTL_GETVERSION | Input structure for control call to get the decoder version number. | ||
| Input Structure Details | Parameter | Description | ||
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |||
| e_cmd | This parameter defines the function to be performed by decoder library. To call control API, the command should be IVD_CMD_VIDEO_CTL | |||
| e_sub_cmd | This is Video Control API command type and tells the functionality to be performed by the Video control API. For details referSection 3.8 - Video Control API Command Type | |||
| Output Structure | This varies depending upon the e_sub_cmd. For details refer the individual data structures corresponding to each control API command type. | |||
| StructureName | e_sub_cmd | Description | ||
| ivd_ctl_flush_op_t | IVD_CMD_CTL_FLUSH | Output structure for control call to flush. | ||
| ivd_ctl_reset_op_t | IVD_CMD_CTL_RESET | Output structure for control call to reset. | ||
| ivd_ctl_set_config_op_t | IVD_CMD_CTL_SETPARAMS | Output structure for control call to set the config parameters. | ||
| IVD_CMD_CTL_SETDEFAULT | Output structure for control call to set the config parameters to default. | |||
| ivd_ctl_getbufinfo_op_t | IVD_CMD_CTL_GETBUFINFO | Output structure for control call to get the buffer information. | ||
| ivd_ctl_getstatus_op_t | IVD_CMD_CTL_GETPARAMS | Output structure for control call to get the parameter values of decoder. | ||
| ivd_ctl_getversioninfo_op_t | IVD_CMD_CTL_GETVERSION | Output structure for control call to get the decoder version number. | ||
| Output Structure Details | Parameter | Description | ||
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |||
| u4_error_code | For the error and status codes refer Error/Status Codes. | |||
Table: Video Control API
| Video Decode API | ||
|---|---|---|
| Purpose | This API is used to decode Video content, If the bitstream given to decoder is not starting with start code, decoder will also search for start code as per the num_Bytes. In shared mode decoder will return IVD_DEC_REF_BUF_NULL error code when there are no free buffers that can be used as reference buffers. In this case application needs to wait till a new buffer is released from display. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; UWORD32 u4_ts; UWORD32 u4_num_Bytes; void *pv_stream_buffer; ivd_out_bufdesc_t s_out_buffer; } ivd_video_decode_ip_t; |
|
| Input Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the function to be performed by decoder library. For video frame decode, this should be IVD_CMD_VIDEO_DECODE | |
| u4_ts | This parameter indicates the decode time-stamp as decodedby system (through parser). This time stamp will be returned in ivd_video_decode_op_t when its corresponding output frame is given for display. | |
| u4_num_Bytes | Size of input data in bytes, provided to the algorithm for decoding | |
| pv_stream_buffer | This parameter points to the bit-stream | |
| s_out_buffer | This is the pointer to the output YUV buffer given by the application whose size shall be at-least as requested by the codec in the IVD_CMD_CTL_GETBUFINFO call. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; UWORD32 u4_num_bytes_consumed; UWORD32 u4_pic_wd; UWORD32 u4_pic_ht; IV_PICTURE_CODING_TYPE_T e_pic_type; UWORD32 u4_frame_decoded_flag; UWORD32 u4_new_seq; UWORD32 u4_output_present; UWORD32 u4_progressive_frame_flag; UWORD32 u4_is_ref_flag; IV_COLOR_FORMAT_T e_output_format; iv_yuv_buf_t s_disp_frm_buf; ivd_sei_decode_op_t s_sei_decode_op; IV_FLD_TYPE_T e4_fld_type; UWORD32 u4_ts; UWORD32 u4_disp_buf_id; } ivd_video_decode_op_t; |
|
| Output Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For the error and status codes refer Error/Status Codes | |
| u4_num_bytes_consumed | This gives the number of bytes the decoder consumed. | |
| u4_pic_wt | Picture width (without any padding) | |
| u4_pic_ht | Picture Height | |
| e_pic_type | This parameter indicates the current frame/picture decoded type e.g. IDR-Frame, P-Frame, B-Frame etc. refer the enum for details. | |
| u4_frame_decoded_flag | This is set to 1 if the current decode call has decoded a complete Frame/field. It is zero in case of Header decode, Flush mode or Partial picture decode. | |
| u4_new_seq | New sequence detected | |
| u4_output_present | This parameter is set to 1, if the current process call has returned output frame for display, else it is 0. | |
| u4_progressive_frame_flag | This parameter is set to 1 if, the frame given for display is Progressive content, else it is 0. This parameter is valid only when u4_output_present is set to 1. | |
| u4_is_ref_flag | This parameter is set to 1, if the frame decoded in the current decode call will used as reference, else it is 0. Invalid in flush mode. | |
| e_output_format | The parameter gives the output color format given for display. This parameter is valid only when u4_output_present is set to 1. | |
| s_disp_frm_buf | Contains YUV Buffer pointer and related details. This parameter is valid only when u4_output_present is set to 1. | |
| s_sei_decode_op | This parameter is used to set SEI parameter values. | |
| e4_fld_type | This parameter is not relevant in current configuration. The output given for display is always a complete frame. | |
| u4_ts | Timestamp corresponds to the value of u4_ts given by application corresponding to its Input bitstream buffer in ivd_video_decode_ip_t. This value can be used to co-relate the Input and output buffers. In the case of Interlace pictures, this value corresponds to the time stamp of second field given by the application. This parameter is valid only when u4_output_present is set to 1. | |
| u4_disp_buf_id | This element returns an ID that is associated with the buffer given out for display. This ID is used in shared display mode and has to be passed to codec during release display control call when the display buffer given out is ready for reuse in the codec. | |
Table: Video Decode API
| Set display frame API | ||
|---|---|---|
| Purpose | This API should be used to give the pointers to all the display buffers to the decoder library. This command should be called before the first IVD_CMD_VIDEO_DECODEAPI command. This API command should be used only when u4_share_disp_buf in ih264d_init_ip_t is set to 1. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; UWORD32 num_disp_bufs; ivd_out_bufdesc_t s_disp_buffer[IVD_VIDDEC_MAX_IO_BUFFERS]; } ivd_set_display_frame_ip_t; |
|
| Input Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the function to be performed by decoder library. For set display frame this needs to be set to IVD_CMD_SET_DISPLAY_FRAME. | |
| num_disp_bufs | This parameter indicates the number of display buffers being given to the library. This can be maximum of 32. | |
| s_disp_buffer[IVD_VIDDEC_MAX_IO_BUFFERS]; | This is an array of display buffer structures. Each element of this array corresponds to one display buffer. The index of the element in this array is its Buffer ID. This buffer ID will be used in the release display frame API call. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; } ivd_set_display_frame_op_t; |
|
| Output Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For the error and status codes refer Error/Status Codes | |
Table: Set display frame API
| Release display frame API | ||
|---|---|---|
| Purpose | This API is used to release a display frame from the application to the decoder library. When a release display frame API is called for a frame, the ownership of the buffer is transferred to the decoder library. The decoder library can now write into the buffer. This API command should be used only when u4_share_disp_buf in ih264d_init_ip_t is set to 1. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; UWORD32 u4_disp_buf_id; } ivd_rel_display_frame_ip_t; |
|
| Input Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the function to be performed by decoder library. For Release display frame API, this should be IVD_CMD_REL_DISPLAY_FRAME | |
| u4_disp_buf_id | This parameter indicates the ID of the buffer being released from display. This signals to the decoder that the buffer with this ID has been displayed and can be reused by codec. The details of the buffer must have been given to the decoder library using an IVD_CMD_SET_DISPLAY_FRAME API call earlier. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; } ivd_rel_display_frame_op_t; |
|
| Output Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For the error and status codes refer Error/Status Codes | |
Table: Release display frame API
This chapter defines some of the common data structures and enumerations used by codec APIs, to interact and exchange data with the application.
| Memory Records (iv_mem_rec_t) | ||
|---|---|---|
| Purpose | This structure is used to pass the memory requirement of decoder to application. | |
| Structure definition | typedef struct { UWORD32 u4_size; void *pv_base; UWORD32 u4_mem_size; UWORD32 u4_mem_alignment; IV_MEM_TYPE_T e_mem_type; } iv_mem_rec_t; |
|
| Enumeration definition |
typedef enum { IV_NA_MEM_TYPE = 0x7FFFFFFF, IV_INTERNAL_CACHEABLE_PERSISTENT_MEM = 0x1, IV_INTERNAL_CACHEABLE_SCRATCH_MEM = 0x2, IV_EXTERNAL_CACHEABLE_PERSISTENT_MEM = 0x3, IV_EXTERNAL_CACHEABLE_SCRATCH_MEM = 0x4, IV_INTERNAL_NONCACHEABLE_PERSISTENT_MEM = 0x5, IV_INTERNAL_NONCACHEABLE_SCRATCH_MEM = 0x6, IV_EXTERNAL_NONCACHEABLE_PERSISTENT_MEM = 0x7, IV_EXTERNAL_NONCACHEABLE_SCRATCH_MEM = 0x8 } IV_MEM_TYPE_T; |
|
| Members of structure | Member | Description |
| u4_size | Contains the size of the current memory record. | |
| pv_base | Contains the base address of the current memory record. | |
| u4_mem_size | Contains the size of the memory to be allocated. | |
| u4_mem_alignment | Defines the alignment requirement of the base address for memory record. | |
| e_mem_type | Contains the type of memory e.g. internal, scratch, persistent, etc. | |
Table: memory records (IV_MEM_REC_T)
| YUV Frame buffer (iv_yuv_buf_t) | ||
|---|---|---|
| Purpose | This structure is used to pass the frame buffer from application to decoder and decoder uses these buffer to store decoded frame, also on get_display_frame API, decoder returns pointer to yuv_frm_buf_t | |
| Structure definition | typedef struct { UWORD32 u4_size; void *pv_y_buf; void *pv_u_buf; void *pv_v_buf; UWORD32 u4_y_wd; UWORD32 u4_y_ht; UWORD32 u4_y_strd; UWORD32 u4_u_wd; UWORD32 u4_u_ht; UWORD32 u4_u_strd; UWORD32 u4_v_wd; UWORD32 u4_v_ht; UWORD32 u4_v_strd; } iv_yuv_buf_t; |
|
| Members of structure | Member | Description |
| u4_size | u4_size of the structure | |
| pv_y_buf | Contains the base address of the Y component of the decoder frame. | |
| pv_u_buf | Contains the base address of the U component of the decoder frame | |
| pv_v_buf | Contains the base address of the V component of the decoder frame | |
| u4_y_wd | Defines the width of the Y frame buffer. | |
| u4_y_ht | Defines the height of the Y frame buffer. | |
| u4_y_strd | Stride/Pitch of the Luma (Y) Buffer | |
| u4_u_wd | Defines the width of the U component in frame buffer. | |
| u4_u_ht | Defines the height of the U component in frame buffer. | |
| u4_u_strd | Stride/Pitch of the U Buffer. | |
| u4_v_wd | Defines the width of the V component in frame buffer. | |
| u4_v_ht | Defines the height of the V component in frame buffer. | |
| u4_v_strd | Stride/Pitch of the V Buffer. | |
Table: YUV frame buffer (yuv_frm_buf_t)
| iv_obj_t | ||
|---|---|---|
| Purpose | This structure defines the handle for the codec instance | |
| Structure definition | typedef struct { UWORD32 u4_size; void *pv_fxns; void *pv_codec_handle; } iv_obj_t; |
|
| Members of structure | Member | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| pv_fxns | Pointer to the API function pointer table of the codec | |
| pv_codec_handle | Pointer to the handle of the codec | |
Table: Video decoder Object
| VOP/Frame coding type | ||
|---|---|---|
| Purpose | This Enumeration defines the frame/VOP type. | |
| Enumeration definition | typedef enum { IV_NA_FRAME = 0x7FFFFFFF, IV_I_FRAME = 0x0, IV_P_FRAME = 0x1, IV_B_FRAME = 0x2, IV_IDR_FRAME = 0x3, IV_II_FRAME = 0x4, IV_IP_FRAME = 0x5, IV_IB_FRAME = 0x6, IV_PI_FRAME = 0x7, IV_PP_FRAME = 0x8, IV_PB_FRAME = 0x9, IV_BI_FRAME = 0xa, IV_BP_FRAME = 0xb, IV_BB_FRAME = 0xc, IV_MBAFF_I_FRAME = 0xd, IV_MBAFF_P_FRAME = 0xe, IV_MBAFF_B_FRAME = 0xf, IV_MBAFF_IDR_FRAME = 0x10, IV_NOT_CODED_FRAME = 0x11, IV_FRAMETYPE_DEFAULT = IV_I_FRAME } IV_PICTURE_CODING_TYPE_T; |
|
| Enumeration Details | Member | Description |
| IV_NA_FRAME | Frame type not available. | |
| IV_I_FRAME | Intra coded frame. | |
| IV_P_FRAME | Forward inter coded frame. | |
| IV_B_FRAME | Bi-directional inter coded frame. | |
| IV_IDR_FRAME | Intra coded frame that can be used for refreshing video content. | |
| IV_II_FRAME | Interlaced Frame, both fields are I frames | |
| IV_IP_FRAME | Interlaced Frame, first field is an I field picture, second field is a P field picture. | |
| IV_IB_FRAME | Interlaced Frame, first field is an I field picture, second field is a B field picture. | |
| IV_PI_FRAME | Interlaced Frame, first field is a P field picture, second field is an I field picture. | |
| IV_PP_FRAME | Interlaced Frame, first field is a P field picture, second field is a P field picture. | |
| IV_PB_FRAME | Interlaced Frame, first field is a P field picture, second field is a B field picture. | |
| IV_BI_FRAME | Interlaced Frame, first field is a B field picture, second field is an I field picture. | |
| IV_BP_FRAME | Interlaced Frame, first field is a B field picture, second field is a P field picture. | |
| IV_BB_FRAME | Interlaced Frame, both fields are B field pictures. | |
| IV_MBAFF_I_FRAME | Intra coded MBAFF frame. | |
| IV_MBAFF_P_FRAME | Forward inter coded MBAFF frame. | |
| IV_MBAFF_B_FRAME | Bi-directional inter coded MBAFF frame. | |
| IV_MBAFF_IDR_FRAME | Intra coded MBAFF frame that can be used for refreshing video content. | |
| IV_NOT_CODED_FRAME | The frame is not coded. | |
| IV_FRAMETYPE_DEFAULT | Default setting. | |
Table: VOP/Frame coding type
| Skip mode Enumeration | ||
|---|---|---|
| Purpose | This Enumeration defines the skip modes available. | |
| Enumeration definition | typedef enum { IVD_SKIP_NONE = 0x7FFFFFFF, IVD_SKIP_P = 0x1, IVD_SKIP_B = 0x2, IVD_SKIP_I = 0x3, IVD_SKIP_IP = 0x4, IVD_SKIP_IB = 0x5, IVD_SKIP_PB = 0x6, IVD_SKIP_IPB = 0x7, IVD_SKIP_IDR = 0x8, IVD_SKIP_DEFAULT = IVD_SKIP_NONE } IVD_FRAME_SKIP_MODE_T; |
|
| Enumeration Details | Member | Description |
| IVD_SKIP_NONE | Do not skip any frame types. | |
| IVD_SKIP_P | Decode the P frame/skip frames internally, but do not copy the decoded output to the output buffers. This should be indicated by setting theout put buffers to NULL. Remarks: For example, if a B frame is dependent on the previously decoded P frame, the B frame shall be decoded and displayed successfully. For this, the P frame needs to be decoded, but not copied to the output buffer. |
|
| IVD_SKIP_B | Skip B, BI frames. For B frames, the decoder will decode the frame bit stream, and return as soon as the frame type is decisively decoded. Internally, the algorithm will modify its state, so that subsequent decoding of other frames is possible. | |
| IVD_SKIP_I | Skip intra coded frame. | |
| IVD_SKIP_IP | Skip I and P frame/field(s). | |
| IVD_SKIP_IB | Skip I and B frame/field(s). | |
| IVD_SKIP_PB | Skip P and B frame/field(s). | |
| IVD_SKIP_IPB | Skip I/P/B/BI frames. | |
| IVD_SKIP_IDR | Skip IDR Frame. | |
| IVD_SKIP_DEFAULT | Default settings. Currently set to IVD_SKIP_NONE. | |
Table: Skip mode Enumeration
| Video content type | ||
|---|---|---|
| Purpose | This Enumeration defines the video content type. | |
| Enumeration definition | typedef enum { IV_CONTENTTYPE_NA = 0x7FFFFFFF, IV_PROGRESSIVE = 0x0, IV_INTERLACED = 0x1, IV_PROGRESSIVE_FRAME = 0x2, IV_INTERLACED_FRAME = 0x3, IV_INTERLACED_TOPFIELD = 0x4, IV_INTERLACED_BOTTOMFIELD = 0x5, IV_CONTENTTYPE_DEFAULT = IV_PROGRESSIVE, } IV_CONTENT_TYPE_T; |
|
| Enumeration Details | Member | Description |
| IV_CONTENTTYPE_NA | Frame type is not available. | |
| IV_PROGRESSIVE | Progressive frame. | |
| IV_PROGRESSIVE_FRAME | Progressive Frame. | |
| IV_INTERLACED | Interlaced frame. | |
| IV_INTERLACED_FRAME | Interlaced frame. | |
| IV_INTERLACED_TOPFIELD | Interlaced picture, top field. | |
| IV_INTERLACED_BOTTOMFIELD | Interlaced picture, bottom field. | |
| IV_CONTENTTYPE_DEFAULT | Default setting. | |
Table: Video content type
| API command type | ||
|---|---|---|
| Purpose | This Enumeration defines the API command type. | |
| Enumeration definition | typedef enum { IV_CMD_NA = 0x7FFFFFFF, IV_CMD_GET_NUM_MEM_REC = 0x0, IV_CMD_FILL_NUM_MEM_REC = 0x1, IV_CMD_RETRIEVE_MEMREC = 0x2, IV_CMD_INIT = 0x3, IV_CMD_DUMMY_ELEMENT = 0x4, } IV_API_COMMAND_TYPE_T; |
|
| Enumeration Details | Member | Description |
| IV_CMD_NA | Unknown command. Should not be used. | |
| IV_CMD_GET_NUM_MEM_REC | Get Number of Memory Records API functionality is called |
|
| IV_CMD_FILL_NUM_MEM_REC | Fill Memory Records API functionality is called | |
| IV_CMD_INIT | Initialize decoder API functionality is called |
|
| IV_CMD_RETRIEVE_MEMREC | Retrieve memory records API functionality is called. | |
| IV_CMD_DUMMY_ELEMENT | Dummy element, not used. | |
Table: API command type
| API command type | ||
|---|---|---|
| Purpose | This Enumeration defines the API command type. | |
| Enumeration definition | typedef enum { IVD_CMD_VIDEO_NA = 0x7FFFFFFF, IVD_CMD_VIDEO_CTL = IV_CMD_DUMMY_ELEMENT + 1, IVD_CMD_VIDEO_DECODE, IVD_CMD_GET_DISPLAY_FRAME, IVD_CMD_REL_DISPLAY_FRAME, IVD_CMD_SET_DISPLAY_FRAME } IVD_API_COMMAND_TYPE_T; |
|
| Enumeration Details | Member | Description |
| IV_CMD_VIDEO_NA | Unknown command. Should not be used. | |
| IVD_CMD_VIDEO_CTL | This enumeration indicates control command. Refer to section 2.5 for more details. |
|
| IVD_CMD_VIDEO_DECODE | This enumeration indicates Video decode command. Refer to section 2.6 for more details. | |
| IVD_CMD_GET_DISPLAY_FRAME | The enumeration is not being used currently. | |
| IVD_CMD_REL_DISPLAY_FRAME | This enumeration indicates Release display frame command. Refer to section 2.8 for more details. | |
| IVD_CMD_SET_DISPLAY_FRAME | This Enumeration indicates Set display frame command. Refer to section 2.7 for more details. | |
Table: API command type
| Video control API command type | ||
|---|---|---|
| Purpose | This Enumeration defines the Video Control API command type. | |
| Enumeration definition | typedef enum { IVD_CMD_NA = 0x7FFFFFFF, IVD_CMD_CTL_GETPARAMS = 0x0, IVD_CMD_CTL_SETPARAMS = 0x1, IVD_CMD_CTL_RESET = 0x2, IVD_CMD_CTL_SETDEFAULT = 0x3, IVD_CMD_CTL_FLUSH = 0x4, IVD_CMD_CTL_GETBUFINFO = 0x5, IVD_CMD_CTL_GETVERSION = 0x6, IVD_CMD_CTL_CODEC_SUBCMD_START = 0x7 } IVD_CONTROL_API_COMMAND_TYPE_T; |
|
| Enumeration Details | Member | Description |
| IVD_CMD_NA | Unknown command. Should not be used. | |
| IVD_CMD_CTL_GETPARAMS | Get run-time dynamic parameters via the ivd_ctl_getstatus_ip_t and ivd_ctl_getstatus_op_t structures | |
| IVD_CMD_CTL_SETPARAMS | Set run-time dynamic parameters via the ivd_ctl_set_config_ip_t and ivd_ctl_set_config_op_t structures | |
| IVD_CMD_CTL_RESET | Reset the algorithm via the ivd_ctl_reset_ip_t and ivd_ctl_reset_op_t structures | |
| IVD_CMD_CTL_SETDEFAULT | Set run-time dynamic parameters to default values via the ivd_set_config_ip_t and ivd_set_config_op_t structures | |
| IVD_CMD_CTL_FLUSH | Handle end of stream conditions. This command forces algorithm instance to flush out allthe decoded buffers via the ivd_ctl_flush_ip_t and ivd_ctl_flush_ip_t structures | |
| IVD_CMD_CTL_GETBUFINFO | Query algorithm instance regarding the properties of input and output buffers via the ivd_ctl_getbufinfo_ip_t and ivd_ctl_getbufinfo_op_t structures | |
| IVD_CMD_CTL_GETVERSION | Get the version information of the decoder library via the ivd_ctl_getversioninfo_ip_t and ivd_ctl_getversioninfo_op_t structures. | |
| IVD_CMD_CTL_CODEC_SUBCMD_START | Codec specific control commands will start with this value. | |
Table: Video control API command type
| Color Format Enumeration | ||
|---|---|---|
| Purpose | This Enumeration defines the various possible color format | |
| Enumeration definition | typedef enum { IV_CHROMA_NA = 0x7FFFFFFF, IV_YUV_420P = 0x1, IV_YUV_422P = 0x2, IV_420_UV_INTL = 0x3, IV_YUV_422IBE = 0x4, IV_YUV_422ILE = 0x5, IV_YUV_444P = 0x6, IV_YUV_411P = 0x7, IV_GRAY = 0x8, IV_RGB_565 = 0x9, IV_RGB_24 = 0xa, IV_YUV_420SP_UV = 0xb, IV_YUV_420SP_VU = 0xc, IV_RGBA_8888 = 0xd } IV_COLOR_FORMAT_T; |
|
| Enumeration Details | Member | Description |
| IV_CHROMA_NA | Chroma format not applicable | |
| IV_YUV_420P | YUV 4:2:0 planer | |
| IV_YUV_422P | YUV 4:2:2 planer | |
| IV_420_UV_INTL | YUV 4:2:0 Semi-planar [Only Uand V color components are interleaved] | |
| IV_YUV_422IBE | YUV 4:2:2 interleaved (bigendian). | |
| IV_YUV_422ILE | YUV 4:2:2 interleaved (littleendian). | |
| IV_YUV_444P | YUV 4:4:4 planar | |
| IV_YUV_411P | YUV 4:1:1 planar | |
| IV_GRAY | Gray format. | |
| IV_RGB_565 | RGB 565 color format. | |
| IV_RGB_24 | RGB 24 color format. | |
| IV_YUV_420SP_UV | YUV 4:2:0 Semi-planar [Only Uand V color components are interleaved, with U first and V second] | |
| IV_YUV_420SP_VU | YUV 4:2:0 Semi-planar [Only Uand V color components are interleaved, with V first and U second] | |
| IV_RGBA_8888 | RGB 8888 color format. | |
Table: Color Format
| Video Decode Mode Enumeration | ||
|---|---|---|
| Purpose | This Enumeration indicates whether the frame decode API call shall decode only header on header and frame worth of data | |
| Enumeration definition | typedef enum { IVD_DECODE_MODE_NA = 0x7FFFFFFF, IVD_DECODE_FRAME = 0x0, IVD_DECODE_HEADER = 0x1, } IVD_VIDEO_DECODE_MODE_T; |
|
| Enumeration Details | Member | Description |
| IVD_DECODE_MODE_NA | Unknown command. Should not be used. | |
| IVD_DECODE_FRAME | Decode both header and frame worth of data | |
| IVD_DECODE_HEADER | Decode only header data | |
Table: Video Decode Mode Enumeration
| Video Frame Output Mode Enumeration | ||
|---|---|---|
| Purpose | This Enumeration indicates whether Get Display Buffer API call shall output frames in display ordering or in decode ordering | |
| Enumeration definition | typedef enum { IVD_DISPLAY_ORDER_NA = 0x7FFFFFFF, IVD_DISPLAY_FRAME_OUT = 0x0, IVD_DECODE_FRAME_OUT = 0x1, } IVD_DISPLAY_FRAME_OUT_MODE_T; |
|
| Enumeration Details | Member | Description |
| IVD_DISPLAY_ORDER_NA | Unknown command. Should not be used. | |
| IVD_DISPLAY_FRAME_OUT | To set codec to fill output buffers in display order | |
| IVD_DECODE_FRAME_OUT | To set codec to fill output buffers in decode order | |
Table: Enumeration definition for IVD_DISPLAY_FRAME_OUT_MODE_T
| Skip mode Enumeration | ||
|---|---|---|
| Purpose | This Enumeration defines the skip modes available. | |
| Enumeration definition | typedef enum { IVD_SKIP_NONE = 0x7FFFFFFF, IVD_SKIP_P = 0x1, IVD_SKIP_B = 0x2, IVD_SKIP_I = 0x3, IVD_SKIP_IP = 0x4, IVD_SKIP_IB = 0x5, IVD_SKIP_PB = 0x6, IVD_SKIP_IPB = 0x7, IVD_SKIP_IDR = 0x8, IVD_SKIP_DEFAULT = IVD_SKIP_NONE } IVD_FRAME_SKIP_MODE_T; |
|
| Enumeration Details | Member | Description |
| IVD_SKIP_NONE | Do not skip any frame types. | |
| IVD_SKIP_P | Decode the P frame/skip frames internally, but do not copy the decoded output to the output buffers. This should be indicated by setting the output buffers to NULL. Remarks: For example, if a B frame is dependent on the previously decoded P frame, the B frame shall be decoded and displayed successfully. For this, the P frame needs to be decoded, but not copied to the output buffer. |
|
| IVD_SKIP_B | Skip B, BI frames. For B frames, the decoder will decode the frame bit stream, and return as soon as the frame type is decisively decoded. Internally, the algorithm will modify its state, so that subsequent decoding of other frames is possible. | |
| IVD_SKIP_I | Skip intra coded frame. | |
| IVD_SKIP_IP | Skip I and P frame/field(s). | |
| IVD_SKIP_IB | Skip I and B frame/field(s). | |
| IVD_SKIP_PB | Skip P and B frame/field(s). | |
| IVD_SKIP_IPB | Skip I/P/B/BI frames. | |
| IVD_SKIP_IDR | Skip IDR Frame. | |
| IVD_SKIP_DEFAULT | Default settings. Currently set to IVD_SKIP_NONE. | |
Table: Enumeration definition for IVD_FRAME_SKIP_MODE_T
When e_sub_cmd in the input structure of Video Control API is IVD_CMD_CTL_GETBUFINFO, this API is used to get the Input/output Buffer size information from the decoder.Following table details the input/output structures for the functionality
| Get Buffer Information API | ||
|---|---|---|
| Purpose | This returns the details the Input/output Buffer details. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; } ivd_ctl_getbufinfo_ip_t; |
|
| Input Structure Details | API Parameter | Description |
| u4_size | Stores the size of this structure. | |
| e_cmd | This indicates the functionality to be performed by the decoder API. To perform this control functionality this has to be equal to IVD_CMD_VIDEO_CTL | |
| e_sub_cmd | This tells the functionality to be performed by the Video control API. To get the buffer information of the decoder, this value of this parameter should be equal to IVD_CMD_ctl_GETBUFINFO | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; UWORD32 u4_num_disp_bufs; UWORD32 u4_min_num_in_bufs; UWORD32 u4_min_num_out_bufs; UWORD32 u4_min_in_buf_size[IVD_VIDDEC_MAX_IO_BUFFERS]; UWORD32 u4_min_out_buf_size[IVD_VIDDEC_MAX_IO_BUFFERS]; } ivd_ctl_getbufinfo_op_t; |
|
| Output Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | The error code returned. | |
| u4_num_disp_bufs | Number of display buffer sets required by codec. Application can allocate 16 more than this number at max. These 16 buffers allow handling of display depth. | |
| |
u4_min_num_in_bufs | Minimum no of Input Buffers needed bythe decoder |
| u4_min_num_out_bufs | Minimum no of Output Buffers needed by the decoder | |
| u4_min_in_buf_size[] | Array containing the size (in bytes) required for each input buffer | |
| u4_min_out_buf_size [] | Array containing the size(in bytes) required for each output buffer | |
Table: Get Buffer Information API
| Set Params API | ||
|---|---|---|
| Purpose | This API is used to set the run time parameters of the decoder. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; IVD_VIDEO_DECODE_MODE_T e_vid_dec_mode; UWORD32 u4_disp_wd; IVD_FRAME_SKIP_MODE_T e_frm_skip_mode; IVD_DISPLAY_FRAME_OUT_MODE_T e_frm_out_mode; } ivd_ctl_set_config_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the functionality to be performed by decoder API. For control calls, it should be IVD_CMD_VIDEO_CTL | |
| e_sub_cmd | This tells the functionality to be performed by the Video control API. To set the dynamic parameters of the decoder, this value of this parameter should be equal to IVD_CMD_CTL_SETPARAMS or IVD_CMD_CTL_SETDEFAULT | |
| e_vid_dec_mode | This parameter is set equal to IVD_DECODE_HEADER if the application wants decoder to decode only the header in the next Video decode API call, otherwise it is set equal to IVD_DECODE_FRAME. See IVD_VIDEO_DECODE_MODE_T. | |
| u4_disp_wd | This parameter is used to set the stride of the output buffer s_out_buffer, given to decoder in Video Decode API call. . | |
| e_frm_skip_mode | Stores the skip mode settings. Refer IVD_FRAME_SKIP_MODE_T for the skip modes available. | |
| e_frm_out_mode | Stores the display modes. Refer IVD_DISPLAY_FRAME_OUT_MODE_T for the modes available. | |
| Note | This API may be called after Initialization. If not called then the decoder initializes the parameters to their default state. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; } ivd_ctl_set_config_op_t; |
|
| Output Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | Status of the control call | |
Table: Video Control API - Set Params
| Get Params API | ||
|---|---|---|
| Purpose | This API is used to get the status of runtime parameters from the decoder. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; } ivd_ctl_getstatus_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the functionality to be performed by decoder API. To call this API the command should be IVD_CMD_VIDEO_CTL | |
| e_sub_cmd | This tells the functionality to be performed by the Video control API. To get the status of the decoder, the value of this parameter should be equal to IVD_CMD_ctl_GETPARAMS | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; UWORD32 u4_num_disp_bufs; UWORD32 u4_pic_ht; UWORD32 u4_pic_wd; UWORD32 u4_frame_rate; UWORD32 u4_bit_rate; IV_CONTENT_TYPE_T e_content_type; IV_COLOR_FORMAT_T e_output_chroma_format; UWORD32 u4_min_num_in_bufs; UWORD32 u4_min_num_out_bufs; UWORD32 u4_min_in_buf_size[IVD_VIDDEC_MAX_IO_BUFFERS]; UWORD32u4_min_out_buf_size[IVD_VIDDEC_MAX_IO_BUFFERS]; } ivd_ctl_getstatus_op_t; |
|
| Output Structure Details |
API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | Error code. Refer the enum Codec Error Code for Error bit details | |
| u4_num_disp_bufs | No of display buffers needed by the decoder. Application can allocate 16 more than this if required. | |
| u4_pic_ht | Height of the video content | |
| u4_pic_wd | Width of the video content | |
| u4_frame_rate | Frame rate the video content | |
| u4_bit_rate | Bit rate of the video content | |
| e_content_type | Content type. Refer enum IV_CONTENT_TYPE_T in Section 3.6 | |
| e_output_chroma_format | Refer enum IV_COLOR_FORMAT_T | |
| u4_min_num_in_bufs | No of input buffers for storing frame | |
| u4_min_num_out_bufs | No of output buffers for storing frame | |
| u4_min_in_buf_size [] | Array containing the size of each input buffer | |
| u4_min_out_buf_size [] | Array containing the size of each output buffer | |
Table: Video Control API - Get Status
| Flush API | ||
|---|---|---|
| Purpose | This API is used to flush the display buffers. In this call the decoder will prepare the decoded frames for display for the subsequent get display API calls.. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; } ivd_ctl_flush_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the functionality to be performed by decoder API. To call this API the command should be IVD_CMD_VIDEO_CTL | |
| e_sub_cmd | This tells the functionality to be performed by the Video control API. To set the dynamic parameters of the decoder, the value of this parameter should be equal to IVD_CMD_CTL_FLUSH | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; } ivd_ctl_flush_op_t; |
|
| Output Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For the error and status codes refer Error/Status Codes. | |
Table: Video Control API - Flush
| Reset API | ||
|---|---|---|
| Purpose | This API is used to reset the decoder. After this call is made, the decoder acquires a state similar to after initialization of the instance. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; } ivd_ctl_reset_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the functionality to be performed by decoder API. To call this API the command should be IVD_CMD_VIDEO_CTL | |
| e_sub_cmd | This tells the functionality to be performed by the Video control API. To reset the decoder, the value of this parameter should be equal to IVD_CMD_CTL_RESET | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; } ivd_ctl_reset_op_t; |
|
| Output Structure Details | API Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | For the error and status codes refer Error/Status Codes. | |
Table: Video Control API - Reset
| API Error/status codes | ||
|---|---|---|
| Purpose | This Enumeration defines the Error/Status codes. | |
| Enumeration definition | typedef enum{ IV_STATUS_NA = 0x7FFFFFFF, IV_SUCCESS = 0x0, IV_FAIL = 0x1 } IV_API_CALL_STATUS_T; |
|
| Enumeration Details | Member | Description |
| IV_STATUS_NA | Unknown command. Should not be used. | |
| IV_SUCCESS | The API executed successfully | |
| IV_FAIL | The API could not execute successfully | |
Table: API Error Status codes
| Codec Error Code | ||
|---|---|---|
| Purpose | Decoder updates e_Error_code bits as per the enumeration values corresponding to the error. Lower 8 bits of error code will be used for the below enum. | |
| Enumeration definition | typedef enum { IVD_ERROR_NONE = 0x0, IVD_NUM_MEM_REC_FAILED = 0x1, IVD_NUM_REC_NOT_SUFFICIENT = 0x2, IVD_FILL_MEM_REC_FAILED = 0x3, IVD_REQUESTED_WIDTH_NOT_SUPPPORTED = 0x4, IVD_REQUESTED_HEIGHT_NOT_SUPPPORTED = 0x5, IVD_INIT_DEC_FAILED = 0x6, IVD_INIT_DEC_NOT_SUFFICIENT = 0x7, IVD_INIT_DEC_WIDTH_NOT_SUPPPORTED = 0x8, IVD_INIT_DEC_HEIGHT_NOT_SUPPPORTED = 0x9, IVD_INIT_DEC_MEM_NOT_ALIGNED = 0xa, IVD_INIT_DEC_COL_FMT_NOT_SUPPORTED = 0xb, IVD_INIT_DEC_MEM_REC_NOT_SUFFICIENT = 0xc, IVD_GET_VERSION_DATABUFFER_SZ_INSUFFICIENT = 0xd, IVD_BUFFER_SIZE_SET_TO_ZERO = 0xe, IVD_UNEXPECTED_END_OF_STREAM = 0xf, IVD_SEQUENCE_HEADER_NOT_DECODED = 0x10, IVD_STREAM_WIDTH_HEIGHT_NOT_SUPPORTED = 0x11, IVD_MAX_FRAME_LIMIT_REACHED = 0x12, IVD_IP_API_STRUCT_SIZE_INCORRECT = 0x13, IVD_OP_API_STRUCT_SIZE_INCORRECT = 0x14, IVD_HANDLE_NULL = 0x15, IVD_HANDLE_STRUCT_SIZE_INCORRECT = 0x16, IVD_INVALID_HANDLE_NULL = 0x17, IVD_INVALID_API_CMD = 0x18, IVD_UNSUPPORTED_API_CMD = 0x19, IVD_MEM_REC_STRUCT_SIZE_INCORRECT = 0x1a, IVD_DISP_FRM_ZERO_OP_BUFS = 0x1b, IVD_DISP_FRM_OP_BUF_NULL = 0x1c, IVD_DISP_FRM_ZERO_OP_BUF_SIZE = 0x1d, IVD_DEC_FRM_BS_BUF_NULL = 0x1e, IVD_SET_CONFG_INVALID_DEC_MODE = 0x1f, IVD_SET_CONFG_UNSUPPORTED_DISP_WIDTH = 0x20, IVD_RESET_FAILED = 0x21, IVD_INIT_DEC_MEM_REC_OVERLAP_ERR = 0x22, IVD_INIT_DEC_MEM_REC_BASE_NULL = 0x23, IVD_INIT_DEC_MEM_REC_ALIGNMENT_ERR = 0x24, IVD_INIT_DEC_MEM_REC_INSUFFICIENT_SIZE = 0x25, IVD_INIT_DEC_MEM_REC_INCORRECT_TYPE = 0x26, IVD_DEC_NUMBYTES_INV = 0x27, IVD_DEC_REF_BUF_NULL = 0x28, IVD_DEC_FRM_SKIPPED = 0x29, IVD_RES_CHANGED = 0x2a, IVD_DUMMY_ELEMENT_FOR_CODEC_EXTENSIONS = 0x30, } IVD_ERROR_CODES_T; |
|
| Enumeration Details | Member | Description |
| IVD_ERROR_NONE | No error. | |
| IVD_NUM_MEM_REC_FAILED | API call to get num_mem_rec failed | |
| IVD_NUM_REC_NOT_SUFFICIENT | Insufficient number of memory records | |
| IVD_FILL_MEM_REC_FAILED | API call to get fill_mem_rec failed | |
| IVD_REQUESTED_WIDTH_NOT_SUPPPORTED | Requested Width not supported | |
| IVD_REQUESTED_HEIGHT_NOT_SUPPPORTED | Requested Height not supported | |
| IVD_INIT_DEC_FAILED | Decoder init failed | |
| IVD_INIT_DEC_NOT_SUFFICIENT | Decoder init memory not sufficient | |
| IVD_INIT_DEC_WIDTH_NOT_SUPPPORTED | Width requested at init not supported | |
| IVD_INIT_DEC_HEIGHT_NOT_SUPPPORTED | Height requested at init not supported | |
| IVD_INIT_DEC_MEM_NOT_ALIGNED | Memory not aligned | |
| IVD_INIT_DEC_COL_FMT_NOT_SUPPORTED | Color format not supported | |
| IVD_INIT_DEC_MEM_REC_NOT_SUFFICIENT | Numberof memory record not sufficient | |
| IVD_GET_VERSION_DATABUFFER_SZ_INSUFFICIENT | Numberof bytes in buffer not sufficient for version info | |
| IVD_BUFFER_SIZE_SET_TO_ZERO | Buffersize is set to 0 | |
| IVD_UNEXPECTED_END_OF_STREAM | Unexpected end of stream | |
| IVD_SEQUENCE_HEADER_NOT_DECODED | Header not Decoded | |
| IVD_STREAM_WIDTH_HEIGHT_NOT_SUPPORTED | Stream Width and height not supported | |
| IVD_MAX_FRAME_LIMIT_REACHED | Maximum Frame limit reached | |
| IVD_IP_API_STRUCT_SIZE_INCORRECT | Input API structure size is incorrect | |
| IVD_OP_API_STRUCT_SIZE_INCORRECT | Output API structure size is incorrect | |
| IVD_HANDLE_NULL | Null Codec Handle passed to codec | |
| IVD_HANDLE_STRUCT_SIZE_INCORRECT | Handle structure size is incorrect | |
| IVD_INVALID_HANDLE_NULL | Invalid Handle | |
| IVD_INVALID_API_CMD | Invalid API command | |
| IVD_UNSUPPORTED_API_CMD | Unsupported API command | |
| IVD_MEM_REC_STRUCT_SIZE_INCORRECT | memory record structure size incorrect | |
| IVD_DISP_FRM_ZERO_OP_BUFS | Display frame zero output buffers | |
| IVD_DISP_FRM_OP_BUF_NULL | Display frame output buffer is Null | |
| IVD_DISP_FRM_ZERO_OP_BUF_SIZE | Display frame output buffer size is zero | |
| IVD_DEC_FRM_BS_BUF_NULL | Bitstream Buffer is Null | |
| IVD_SET_CONFG_INVALID_DEC_MODE | Invalid decoder mode in set config | |
| IVD_SET_CONFG_UNSUPPORTED_DISP_WIDTH | Unsupported width in set config | |
| IVD_RESET_FAILED | Reset failed | |
| IVD_INIT_DEC_MEM_REC_OVERLAP_ERR | Memory records overlap | |
| IVD_INIT_DEC_MEM_REC_BASE_NULL | Memory records base is Null | |
| IVD_INIT_DEC_MEM_REC_ALIGNMENT_ERR | Memory records alignment error | |
| IVD_INIT_DEC_MEM_REC_INSUFFICIENT_SIZE | Insufficient Memory records size | |
| IVD_INIT_DEC_MEM_REC_INCORRECT_TYPE | Incorrect Memory records type | |
| IVD_DEC_NUMBYTES_INV | Invalid numbytes provided to decoder | |
| IVD_DEC_REF_BUF_NULL | Decoder reference buffer null | |
| IVD_DEC_FRM_SKIPPED | Frame skipped by decoder | |
| IVD_DUMMY_ELEMENT_FOR_CODEC_EXTENSIONS | Dummy element for codec extension | |
Table: Codec Error Code
| Codec Error Code | ||
|---|---|---|
| Purpose | Decoder updates e_Error_code bits as per the enumeration values corresponding to the error. Bits 0 to 7 from LSB side are kept free for codec specific error codes. | |
| Enumeration definition | typedef enum { IVD_APPLIEDCONCEALMENT = 0x8, IVD_INSUFFICIENTDATA = 0x9, IVD_CORRUPTEDDATA = 0xa, IVD_CORRUPTEDHEADER = 0xb, IVD_UNSUPPORTEDINPUT = 0xc, IVD_UNSUPPORTEDPARAM = 0xd, IVD_FATALERROR = 0xe, IVD_INVALID_BITSTREAM = 0xf, IVD_INCOMPLETE_BITSTREAM = 0x10, IVD_ERROR_BITS_T_DUMMY_ELEMENT = 0x7FFFFFFF } IVD_ERROR_BITS_T; |
|
| Enumeration Details | Member | Description |
| IVD_APPLIEDCONCEALMENT | This bit is set if errorconcealment is applied | |
| IVD_INSUFFICIENTDATA | This bit is set if decoder finds insufficient data in input buffer | |
| IVD_CORRUPTEDDATA | This bit is set if decoder encounters corrupt data in bitstream | |
| IVD_CORRUPTEDHEADER | This bit is set if the decoder encounters an error in the header. | |
| IVD_UNSUPPORTEDINPUT | This bit is set if decoder finds any unsupported toolset in bitstream | |
| IVD_UNSUPPORTEDPARAM | This bit is set if applicationtries to set any parameter and decoder does not support it. | |
| IVD_FATALERROR | This bit is set if decoder encounters a fatal error. | |
| IVD_INCOMPLETE_BITSTREAM | This bit is set if the bitstream given to the decoder is incomplete. | |
Table: Codec error code
| H264 Decoder API Entry Point Function | ||
|---|---|---|
| Name | ih264d_api_function() | |
| Purpose | This is an API function of the H264 decoder for the application, and is the only entry point to the h264 decoder library. | |
| Prototype | IV_API_CALL_STATUS_T ih264d_api_function(iv_obj_t *dec_hdl, void *pv_api_ip, void *pv_api_op) | |
| Argument details | Argument | Description |
| iv_obj_t *dec_hdl | Pointer to the codec instance called as decoder handle. | |
| void *pv_api_ip | Pointer to the APIs input structure type-casted as void pointer. | |
| void *pv_api_op | Pointer to the APIs output structure type-casted as void pointer. | |
Table: H264 Decoder API Entry Point Function
| Fill Memory Records API | ||
|---|---|---|
| Purpose | This extension gives the user flexibility of memory allocation if the nature of the video to be decoded is known by varying the number of reorder and reference frames. | |
| Input Structure | typedef struct { iv_fill_mem_rec_ip_t s_ivd_fill_mem_rec_ip_t; WORD32 i4_level; UWORD32 u4_num_reorder_frames; UWORD32 u4_num_ref_frames; UWORD32 u4_share_disp_buf; IV_COLOR_FORMAT_T e_output_format; UWORD32 u4_num_extra_disp_buf; } ih264d_fill_mem_rec_ip_t; |
|
| Input Structure Details | Parameter | Description |
| s_ivd_fill_mem_rec_ip_t | Refer iv_fill_mem_rec_ip_t | |
| i4_level | This parameter defines the level of the video to be decoded. | |
| u4_num_reorder_frames | This parameter should contain the maximum number of frames that are required to accomplish the reordering of the video, if any | |
| u4_num_ref_frames | This parameter should contain the maximum number of frames that need to be stored in the reference frame buffers | |
| u4_share_disp_buf | This should be set to 1 to enable shared display buffer mode. | |
| e_output_format | The parameter gives the output color format required by the application. It is same as e_output_format in ivd_init_ip_t. | |
| u4_num_extra_disp_buf | Number of extra display buffers that will be allocated to handle display pipeline depth | |
Table: Extended Fill Memory Records API
| Initialize decoder API | ||
|---|---|---|
| Purpose | This serves the same purpose as the extension of the Fill Memory Records extension. It has to been sured that the values level, reorder frames and reference frames values have to be the same for both Fill Memory Records and Initialize Decoder API. | |
| Input Structure | typedef struct { ivd_init_ip_t s_ivd_init_ip_t; WORD32 i4_level; UWORD32 u4_num_reorder_frames; UWORD32 u4_num_ref_frames; UWORD32 u4_share_disp_buf; UWORD32 u4_num_extra_disp_buf; } ih264d_init_ip_t; |
|
| Input Structure Details | API Parameter | Description |
| s_ivd_init_ip_t | Refer ivd_init_ip_t | |
| i4_level | This parameter defines the level of the video to be decoded. | |
| u4_num_reorder_frames | This parameter should contain the maximum number of frames that are required to accomplish the reordering of the video, if any | |
| u4_num_ref_frames | This parameter should contain the maximum number of frames that need to be stored in the reference frame buffers | |
| u4_share_disp_buf | This should be set to 1 to enable shared display buffer mode. This is should be equal to u4_share_disp_buf in ih264d_fill_mem_rec_ip_t. | |
| u4_num_extra_disp_buf | Number of extra display buffers that will be allocated to handle display pipeline depth | |
Table: Extended Initialize decoder API
| IH264D_CMD_CTL_SUB_CMDS | ||
|---|---|---|
| Purpose | Codec specific Control calls. | |
| Enumeration definition | typedef enum { IH264D_CMD_CTL_SET_NUM_CORES = IVD_CMD_CTL_CODEC_SUBCMD_START, IH264D_CMD_CTL_SET_PROCESSOR = IVD_CMD_CTL_CODEC_SUBCMD_START + 0x001, IH264D_CMD_CTL_GET_BUFFER_DIMENSIONS = IVD_CMD_CTL_CODEC_SUBCMD_START + 0x100, IH264D_CMD_CTL_GET_VUI_PARAMS = IVD_CMD_CTL_CODEC_SUBCMD_START + 0x101, IH264D_CMD_CTL_GPU_ENABLE_DISABLE = IVD_CMD_CTL_CODEC_SUBCMD_START + 0x200, IH264D_CMD_CTL_DEGRADE = IVD_CMD_CTL_CODEC_SUBCMD_START + 0x300, IH264D_CMD_CTL_GET_SEI_MDCV_PARAMS = IVD_CMD_CTL_CODEC_SUBCMD_START + 0x301, IH264D_CMD_CTL_GET_SEI_CLLI_PARAMS = IVD_CMD_CTL_CODEC_SUBCMD_START + 0x302} IH264D_CMD_CTL_SUB_CMDS; |
|
| Enumeration Details | Member | Description |
| IH264D_CMD_CTL_SET_NUM_CORES |
This sub command is used to set number of processor cores to be used by the decoder. | |
| IH264D_CMD_CTL_SET_PROCESSOR |
This sub command is used to set the target processor architecture to be used by the decoder. | |
| IH264D_CMD_CTL_GET_BUFFER_DIMENSIONS | This sub command is used to get output frame dimensions. | |
| IH264D_CMD_CTL_GET_VUI_PARAMS | This sub command is used to get the VUI parameters. | |
| IH264D_CMD_CTL_GET_SEI_MDCV_PARAMS | This sub command is used to get the SEI MDCV parameters. | |
| IH264D_CMD_CTL_GET_SEI_CLLI_PARAMS | This sub command is used to get the SEI CLLI parameters. | |
Table: IH264D_CMD_CTL_SUB_CMDS
| Set num cores API | ||
|---|---|---|
| Purpose | This API is used to set the number of Processor cores that the decoder can use. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; UWORD32 u4_num_cores; } ih264d_ctl_set_num_cores_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the functionality to be performed by decoder API. For control calls, it should be IVD_CMD_VIDEO_CTL | |
| e_sub_cmd | This tells the functionality to be performed by the Video control API. To set the number of processor cores that the decoder should use, this should be set to value of IH264D_CMD_CTL_SET_NUM_CORES | |
| u4_num_cores | This parameter is used to inform the decoder about number of cores to be used. | |
Table: Set num cores API
| Set num cores API | ||
|---|---|---|
| Purpose | This API is used to set the number of Processor cores that the decoder can use. | |
| Output Structure | typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; } ih264d_ctl_set_num_cores_op_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | Error code returned by decoder library if any | |
| Get frame dimensions API | ||
|---|---|---|
| Purpose | This API is used to get output frame dimensions such as x and y offsets, display width and height, buffer width and height. This is useful when the decoder is used in shared mode where decode buffer and display dimensions are different because of padding and cropping. In non-shared mode offsets will be zero and display dimensions will be same as buffer dimensions. | |
| Input Structure | typedef struct { UWORD32 u4_size; IVD_API_COMMAND_TYPE_T e_cmd; IVD_CONTROL_API_COMMAND_TYPE_T e_sub_cmd; } ih264d_ctl_get_frame_dimensions_ip_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| e_cmd | This parameter defines the functionality to be performed by decoder API. For control calls, it should be IVD_CMD_VIDEO_CTL | |
| e_sub_cmd | This tells the functionality to be performed by the Video control API. To set the number of processor cores that the decoder should use, this should be set to value of IH264D_CMD_CTL_GET_BUFFER_DIMENSIONS | |
| Output Structure |
typedef struct { UWORD32 u4_size; UWORD32 u4_error_code; UWORD32 u4_x_offset[3]; UWORD32 u4_y_offset[3]; UWORD32 u4_disp_wd[3]; UWORD32 u4_disp_ht[3]; UWORD32 u4_buffer_wd[3]; UWORD32 u4_buffer_ht[3]; } ih264d_ctl_get_frame_dimensions_op_t; |
|
| Input Structure Details | Parameter | Description |
| u4_size | Size of the structure. Useful in extending the structure with new fields. | |
| u4_error_code | Error code returned by decoder library if any | |
| u4_x_offset[3] | X offset for each of the components. This includes padding required by the codec and as well as frame cropping as per the standard. | |
| u4_y_offset[3] | Y offset for each of the components. This includes padding required by the codec and as well as frame cropping as per the standard. | |
| u4_disp_wd[3] | Display width for each of the components | |
| u4_disp_ht[3] | Display height for each of the components | |
| u4_disp_wd[3] | Buffer width for each of the components. | |
| u4_disp_ht[3] | Buffer height for each of the components | |
Table: Get frame dimensions API
| H264 Decoder Error/status codes | ||
|---|---|---|
| Purpose | This Enumeration defines the Error/Status codes specific to H264 Decoder. Bits 0 to 7 from LSB side are used here to report the codec specific error codes | |
| Error Code | Error Name | Description |
| 0 |
IH264_SUCCESS | No error |
| 0x89 |
ERROR_ACTUAL_RESOLUTION_GREATER_THAN_INIT | Resolution greater than init time resolution |
| 0x8A |
ERROR_PROFILE_NOT_SUPPORTED | Unsupported profile |
| 0x7FFFFFFF |
IH264_FAIL | Generic failure |
Table: H264 Decoder Error/status codes