Texas Instruments DM365 User Manual Download Page 47

Page: 47 / 131

4-1

Chapter 4

API Reference

This chapter provides a detailed description of the data structures and
interfaces functions used in the codec component.

Topic Page

4.1 Symbolic Constants and Enumerated Data Types

4-2

4.2 Data Structures

4-22

4.3 H.264 Encoder ROI specific Data Structures and Enumerations

4-50

4.4 H264 Encoder Two Pass Encoder data structure

4-53

4.5 H.264 Encoder Low latency specific Data Structures and
Enumerations

4-55

4.6 Interface Functions

4-59

Summary of Contents for DM365

Page 1: ...H 264 Base Main High Profile Encoder on DM365 DM368 User s Guide Literature Number SPRUEU9C August 2010 ...

Page 2: ...ch statements TI products are not authorized for use in safety critical applications such as life support where a failure of the TI product would reasonably be expected to cause severe personal injury or death unless officers of the parties have executed an agreement specifically governing such use Buyers represent that they have all necessary expertise in the safety and regulatory ramifications o...

Page 3: ... you are fluent in the C language have a good working knowledge of Digital Signal Processing DSP digital signal processors and DSP applications Good knowledge of eXpressDSP Algorithm Interface Standard XDAIS and eXpressDSP Digital Media XDM standard will be helpful How to Use This Manual This document includes the following chapters Chapter 1 Introduction provides a brief introduction to the XDAIS...

Page 4: ...orithm Standard Rules and Guidelines SPRU352 defines a set of requirements for DSP algorithms that if followed allow system integrators to quickly assemble production quality systems from one or more such algorithms TMS320 DSP Algorithm Standard API Reference SPRU360 describes all the APIs that are defined by the TMS320 DSP Algorithm Interoperability Standard also known as XDAIS specification Usin...

Page 5: ...1280x720 resolution in progressive scan HDTV High Definition Television HDVICP High Definition Video and Imaging Co processor sub system IDR Instantaneous Decoding Refresh ITU T International Telecommunication Union JM Joint Menu JVT Joint Video Team MB Macro Block MBAFF Macro Block Adaptive Field Frame MJCP MPEG JPEG Co Processor MPEG Motion Pictures Expert Group MV Motion Vector NAL Network Adap...

Page 6: ...xt Conventions The following conventions are used in this document Text inside back quotes represents pseudo code Program source code function and macro names parameters and command line commands are shown in a mono spaced font Product Support When contacting TI for support on this codec quote the product name H 264 Base Main High Profile Encoder on DM365 DM368 and version number The version numbe...

Page 7: ... 00 00 xx Platinum Encoder 1 11 Installation Overview 2 1 2 1 System Requirements for Linux 2 2 2 1 1 Hardware 2 2 2 1 2 Software 2 2 2 2 Installing the Component for Linux 2 2 2 3 Building and Running the Sample Test Application on Linux 2 4 2 4 Configuration Files 2 4 2 4 1 Generic Configuration File 2 5 2 4 2 Encoder Configuration File 2 6 2 4 3 Encoder Sample Base Param Setting 2 8 2 5 Standar...

Page 8: ...ructures 4 22 4 2 2 H 264 Encoder Data Structures 4 37 4 3 H 264 Encoder ROI specific Data Structures and Enumerations 4 50 4 4 H264 Encoder Two Pass Encoder data structure 4 53 4 5 H 264 Encoder Low latency specific Data Structures and Enumerations 4 55 4 5 1 Structures 4 55 4 5 2 Constant 4 56 4 5 3 Typdef 4 56 4 5 4 Enum 4 57 4 6 Interface Functions 4 59 4 6 1 Creation APIs 4 60 4 6 2 Initializ...

Page 9: ...4 Block Diagram of H 264 Encoder 1 9 Figure 2 5 Component Directory Structure for Linux 2 3 Figure 3 1 Test Application Sample Implementation 3 2 Figure 3 2 Process Call with Host Release 3 4 Figure 3 3 Resource Level Interaction 3 6 Figure 3 4 Interaction Between Application and Codec 3 7 Figure 3 5 Interrupt Between Codec and Application 3 8 Figure C 1 VICP Buffers Managed By FC C 2 ...

Page 10: ...x This page is intentionally left blank ...

Page 11: ...xi Tables Table 1 1 List of Abbreviations iv Table 2 2 Component Directories for Linux 2 3 Table 3 1 process Implementation 3 11 Table 4 1 List of Enumerated Data Types 4 2 ...

Page 12: ...xii This page is intentionally left blank ...

Page 13: ...4 Base Main High Profile Encoder on the DM365 DM368 platform and its supported features Topic Page 1 1 Software Architecture 1 2 1 2 Overview of XDAIS XDM and Framework Component Tools 1 2 1 3 Overview of H 264 Base Main High Profile Encoder 1 7 1 4 Supported Services and Features 1 10 1 5 Comparison between version 01 10 00 xx with new version 02 00 00 xx Platinum Encoder 1 11 ...

Page 14: ...ec implementations are based on the eXpressDSP Digital Media XDM standard XDM is an extension of the eXpressDSP Algorithm Interface Standard XDAIS IRES is a TMS320 DSP Algorithm Standard xDAIS interface for management and utilization of special resource types such as hardware accelerators certain types of memory and DMA RMAN is a generic Resource Manager that manages software component s logical r...

Page 15: ...algNumAlloc and algMoved For more details on these APIs see TMS320 DSP Algorithm Standard API Reference SPRU360 1 2 2 XDM Overview In the multimedia application space you have the choice of integrating any codec into your multimedia system For example if you are building a video decoder system you can use any of the available video decoders such as MPEG4 H 263 or H 264 in your system To enable eas...

Page 16: ...en the client application and the codec component XDM insulates the client application from component level changes Since TI s multimedia algorithms are XDM compliant it provides you with the flexibility to use any TI algorithm without changing the client application code For example if you have developed a client application using an XDM compliant MPEG4 video decoder then you can easily replace M...

Page 17: ...ce initialization activation and deactivation The IRES interface introduces support for a new standard protocol for cooperative preemption in addition to the IALG style non cooperative sharing of scratch resources Co operative preemption allows activated algorithms to yield to higher priority tasks sharing common scratch resources Framework components include the following modules and interfaces t...

Page 18: ...ed by FC are listed in this section 1 2 3 2 HDVICP The IRES HDVICP Resource Interface IRES_HDVICP allows algorithms to request and receive handles representing Hardware Accelerator resource HDVICP on supported hardware platforms Algorithms can request and acquire one of the co processors using a single IRES request descriptor IRES_HDVICP is an example of a very simple resource type definition whic...

Page 19: ...APIs to perform cache and memory related operations cacheInv Invalidates a range of cache cacheWb Writes back a range of cache cacheWbInv Writes back and invalidate cache getPhysicalAddr Obtains physical hardware specific address 1 2 3 7 TCM ARM TCM resource manager provides access to request ARM926 TCM memory ARM926 in DM365 DM368 has 32K TCM which can be allocated to codec algorithm on request T...

Page 20: ... and value 0x00000001 followed by one NAL unit syntax structure The encoded frame data is a group of slices each is encapsulated in NAL units The slice consists of the following Intra coded data Spatial prediction mode and prediction error data subjected to DCT and later quantized Inter coded data Motion information and residual error data differential data between two frames subjected to DCT and ...

Page 21: ...profile uses the Context Adaptive Variable Length Coding CAVLC CAVLC is the stage where transformed and quantized coefficients are entropy coded using context adaptive table switching across different symbols The syntax defined by the H 264 Encoder stores the information at 4x4 block level The following figure depicts the working of the encoder Figure 1 4 Block Diagram of H 264 Encoder From this p...

Page 22: ...nd VBR Supports Insertion of Buffering Period and Picture Timing Supplemental Enhancement Information SEI and Video Usability Information VUI Supports Unrestricted Motion Vectors UMV Supports Half Pel and Quarter Pel Interpolation for motion estimation Supports following Smart Codec features o Simple Two Pass STP Encoding o Region of Interest ROI Supports Low latency feature o Can be configured to...

Page 23: ...decs which includes Smart codec technology Low latency API support Version 02 00 00 xx also supports version 1 1 standard mode as a backward compatible option This can be enabled by setting encodingPreset XDM_USER_DEFINED and encQuality 0 It enables application that needs low resolution encoding lesser EDMA channels or some specific tools like perceptual rate control Feature Version 1 1 Gen 1 Vers...

Page 24: ...Introduction 1 12 This page is intentionally left blank ...

Page 25: ...t It also provides information on building and running the sample test application Topic Page 2 1 System Requirements for Linux 2 2 2 2 Installing the Component for Linux 2 2 2 3 Building and Running the Sample Test Application on Linux 2 4 2 4 Configuration Files 2 4 2 5 Standards Conformance and User Defined Inputs 2 8 2 6 Uninstalling the Component 2 9 ...

Page 26: ...of the codec Build Environment This project is built using Linux with MVL ARM tool chain ARM Tool Chain This project is compiled and linked using MVL ARM tool chain 2 2 Installing the Component for Linux The codec component is released as a compressed archive To install the codec extract the contents of the tar file onto your local hard disk The tar file extraction creates a directory called dm365...

Page 27: ...ecs h264enc docs Contains user guide datasheet and release notes packages ti sdo codecs h264enc apps clie nt build arm926 Contains the makefile to built sample test application packages ti sdo codecs h264enc apps clie nt build arm926 cmd Contains a template xdt file to used to generate linker command file packages ti sdo codecs h264enc apps clie nt build arm926 map Contains the memory map generate...

Page 28: ...3 Ensure that you have installed the LSP Montavista arm tool chain XDC Framework Components releases with version numbers that are mentioned in the release notes 4 In the folder packages ti sdo codecs h264enc client build arm926 change the paths in the file rules make according to your setup 5 Open the command prompt at the sub directory packages ti sdo codecs h264enc client build arm926 and type ...

Page 29: ...apps client test testvecs config sub directory The format of the testvecs cfg file is X config input output reference recon where X may be set as o 1 for compliance checking no output file is created o 0 for writing the output to the output file config is the Encoder configuration file For details see Section 2 4 2 input is the input file name use complete path output reference is the output file ...

Page 30: ... Comment Parameters ImageWidth 1280 Image width in Pels must be multiple of 16 ImageHeight 720 Image height in Pels must be multiple of 16 FrameRate 30000 Frame Rate per second 1000 1 120 BitRate 4000000 Bitrate bps if ZERO RC is OFF ChromaFormat 9 9 XDM_YUV_420P InterlacedVideo 0 0 Progressive 1 Interlaced TimerScale 60 Timer Resolution for Picture Timing NumUnitsInTicks 1 Number of Timer units p...

Page 31: ... CABAC Transform8x8FlagIntra 1 0 Disable 1 Enable Transform8x8FlagInter 1 0 Disable 1 Enable SequenceScalingFlag 0 0 Disable 1 Auto 2 Low 3 Moderate 4 Reserved PerceptualRC 1 1 Enable Perceptual QP modulation 0 Disable EncoderQuality 1 0 Ver 1 1 mode Backward compatible 2 Platinum mode mvSADout 0 0 disable mvsad out 1 enable mvsad out useARM926Tcm 1 0 do not use arm 926 tcm 1 use arm 926 tcm enabl...

Page 32: ...tType IVIDEO_PROGRESSIVE XDAS_Int32 reconChromaFormat XDM_YUV_420SP value 9 IVIDENC1_Params typedef struct IVIDENC1_DynamicParams XDAS_Int32 size sizeField XDAS_Int32 inputHeight Input frame height XDAS_Int32 inputWidth Input frame width XDAS_Int32 refFrameRate 30000 XDAS_Int32 targetFrameRate 30000 XDAS_Int32 targetBitRate 10000000 Target bit rate in bits per second XDAS_Int32 intraFrameInterval ...

Page 33: ...displays FAIL message if the bit stream does not match with reference bit stream After the encoding is complete the application displays a summary of total number of frames encoded In reference bit stream compliance check mode the application additionally displays PASS message if the bit stream matches with the reference bit stream If you have chosen the option to write to an output file X is 0 yo...

Page 34: ...Installation Overview 2 10 This page is intentionally left blank ...

Page 35: ... description of the sample test application that accompanies this codec component Topic Page 3 1 Overview of the Test Application 3 2 3 2 Handshaking Between Application and Algorithm 3 6 3 3 Cache Management by Application 3 9 3 4 Sample Test Application 3 11 ...

Page 36: ...64 Encoder library The main test application files are h264encoderapp c and h264encoderapp h These files are available in the client test src and client test inc sub directories respectively Figure 3 1 depicts the sequence of APIs exercised in the sample test application Figure 3 1 Test Application Sample Implementation ...

Page 37: ...he values it reads from the Testparams cfg file 4 Sets the extended parameters of the IH264VENC_Params structure based on the values it reads from the testparams cfg file After successful completion of the above steps the test application does the algorithm instance creation and initialization 3 1 2 Algorithm Instance Creation and Initialization In this logical block the test application accepts t...

Page 38: ...n are explained below The behavior of the algorithm can be controlled using various dynamic parameters see section 4 2 1 10 The inputs to the process functions are input and output buffer descriptors pointer to the IVIDENC1_InArgs and IVIDENC1_OutArgs structures 4 Call the process function to encode decode a single frame of data After triggering the start of the encode decode frame start the video...

Page 39: ...ppropriate input output buffer and arguments information 3 control optional To query the algorithm on status or setting of dynamic parameters and so on using the seven available control commands 4 algDeactivate To deactivate the algorithm instance The for loop encapsulates frame level process call and updates the input buffer and the output buffer pointer every time before the next call The for lo...

Page 40: ...rly it uses RMAN to grant resources to the codec Figure 3 3 Resource Level Interaction Creation Application Framework component CODEC IALG_create fns Register Resource RMAN_register Assign Resource RMAN_assign resource Control and Process Free Resource and Exit Codec Deletion RMAN_freeresou rce and RMAN_exit Encoding Decoding IALG_free fns Details of resource held by codec VICP buffers memories DM...

Page 41: ...unction also configures the Framework Component interrupt synchronization routine 2 HDVICPSYNC_wait IRES_HDVICP_Handle hdvicpHandle This function is a FC call back function use to pend on a semaphore Whenever the codec has completed the work on Host processor after transfer of frame level encode decode to HDVICP and needs to relive the CPU for other tasks it calls this function Framework Provided ...

Page 42: ...ation and codec Figure 3 5 Interrupt Between Codec and Application Framework calls Encoder Init HOST ARM926 HDVICP Start frame processing At the end send interrupt to Host that it has finished Inform Host through interrupt Codec task wakes up to finish end of frame processing and returns back to framework Framework Calls Encode frame process HDVICPSYNC_wait uses to make the codec task sleep Pendin...

Page 43: ...or better performance Since the codec also uses DMA there can be inherent cache coherency problems when application turns on the cache 3 3 2 Cache and Memory Related Call Back Functions for Linux To resolve the cache coherency and virtual to physical address issues FC provides memory until library These following functions can be used by codecs to resolve the cache coherency issues in Linux cacheI...

Page 44: ... 3 2 2 cacheWb This API writes back cache to the cache source when it is necessary Void MEMUTILS_cacheWb Ptr addr Int sizeInBytes 3 3 2 3 cacheWbInv This API writes back cache to the cache source when it is necessary and deletes the cache contents Void MEMUTILS_cacheWbInv Ptr addr Int sizeInBytes 3 3 2 4 getPhysicalAddr This API obtains the physical address Void MEMUTILS_getPhysicalAddr Ptr addr ...

Page 45: ...arams Pointer to Dynamicparam structure status Pointer to the status structure SET BASIC INPUT PARAMETERS iErrorFlag H264VENC_control handle Instance Handle XDM_GETSTATUS Command dynamicparams Pointer to Dynamicparam structure status Pointer to the status structure Based on the Num of buffers requested by the algorithm the application will allocate for the same here AllocateH264IOBuffers status st...

Page 46: ...t status Output end of Do While loop which Encodes frames Free Input and output buffers FreeH264IOBuffers inobj Pointer to Input Buffer Descriptor outobj Pointer to Output Buffer Descriptor Free assigned resources RMAN_freeResources IALG_Handle handle H264VENC_TI_IRES IRES_Fxns Delete the encoder Object handle H264VENC_delete handle Unregister protocal RMAN_unregister IRESMAN_EDMA3CHAN RMAN_exit N...

Page 47: ... codec component Topic Page 4 1 Symbolic Constants and Enumerated Data Types 4 2 4 2 Data Structures 4 22 4 3 H 264 Encoder ROI specific Data Structures and Enumerations 4 50 4 4 H264 Encoder Two Pass Encoder data structure 4 53 4 5 H 264 Encoder Low latency specific Data Structures and Enumerations 4 55 4 6 Interface Functions 4 59 ...

Page 48: ...ideo content IVIDEO_II_FRAME Interlaced frame both fields are I frames IVIDEO_IP_FRAME Interlaced frame first field is an I frame second field is a P frame IVIDEO_IB_FRAME Interlaced frame first field is an I frame second field is a B frame Not supported in this version of H 264 Encoder IVIDEO_PI_FRAME Interlaced frame first field is a P frame second field is an I frame Not supported in this versi...

Page 49: ... version of H 264 Encoder IVIDEO_FRAMETYPE_DEFAULT The default value is set to IVIDEO_I_FRAME IVIDEO_CONTENTTYPE_NA Content type is not applicable Encoder assumes IVIDEO_PROGRESSIVE IVIDEO_PROGRESSIVE Progressive video content This is the default value IVIDEO_ContentType IVIDEO_INTERLACED Interlaced video content IVIDEO_NONE No rate control is used IVIDEO_LOW_DELAY Constant Bit Rate CBR control fo...

Page 50: ...OMA_NA Chroma format not applicable Encoder assumes IH264VENC_YUV_420IUV XDM_YUV_420P YUV 4 2 0 planar Not supported in this version of H 264 Encoder XDM_YUV_422P YUV 4 2 2 planar Not supported in this version of H 264 Encoder XDM_YUV_422IBE YUV 4 2 2 interleaved big endian Not supported in this version of H 264 Encoder XDM_YUV_422ILE YUV 4 2 2 interleaved little endian Not supported in this versi...

Page 51: ...DM_SETPARAMS Set run time dynamic parameters through the DynamicParams structure XDM_RESET Reset the algorithm XDM_SETDEFAULT Initialize all fields in DynamicParams structure to default values specified in the library XDM_FLUSH Handle end of stream conditions This command forces algorithm instance to output data without additional input Not supported in this version of H 264 Encoder XDM_GETVERSION...

Page 52: ...ient data 0 Ignore XDM_CORRUPTEDDATA Bit 11 1 Data problem corruption 0 Ignore XDM_CORRUPTEDHEADER Bit 12 1 Header problem corruption 0 Ignore XDM_UNSUPPORTEDINPUT Bit 13 1 Unsupported feature parameter in input 0 Ignore XDM_UNSUPPORTEDPARAM Bit 14 1 Unsupported input parameter or configuration 0 Ignore XDM_ErrorBit XDM_FATALERROR Bit 15 1 Fatal error stop encoding 0 Recoverable error Note encodin...

Page 53: ...er for H 264 Encoder IH264VENC_LEVEL_20 Level 2 0 identifier for H 264 Encoder IH264VENC_LEVEL_21 Level 2 1 identifier for H 264 Encoder IH264VENC_LEVEL_22 Level 2 2 identifier for H 264 Encoder IH264VENC_LEVEL_30 Level 3 0 identifier for H 264 Encoder IH264VENC_Level IH264VENC_LEVEL_31 Level 3 1 identifier for H 264 Encoder IH264VENC_LEVEL_32 Level 3 2 identifier for H 264 Encoder IH264VENC_LEVEL...

Page 54: ...rams exceeds H264VENC_TI_MAX_HEIGHT 2048 or is less than H264VENC_TI_MIN_HEIGHT H264VENC_TI_MIN_HEIGHT takes value of 96 in case of encodingPreset XDM_USER_DEFINED and encQuality 0 OR 128 in case of encodingPreset XDM_HIGH_SPEED XDM_HIGH_QUAL ITY IH264VENC_ERR_ENCODING PRESET encodingPreset not supported fatal input error is returned during algInit if the encodingPreset parameter is out of support...

Page 55: ... if inputContentType is not set to IVIDEO_PROGRESSIVE or IVIDEO_INTERLACED This error is also returned during algInit if interlaced encoding is enabled inputContentType set to IVIDEO_INTERLACED for levels less than 2 1 or more than 4 1 IH264VENC_ERR_RECONCHR OMAFORMAT reconChromaFormat not supported fatal input error is returned during algInit if reconChromaFormat is not set to XDM_YUV_420SP or XD...

Page 56: ..._MBS_ IN_FRM_LIMIT_EXCEED This fatal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if the number of MBs in a frame exceeds the maximum limit for resolution of 2048x2048 Control call returns IVIDENC1_EFAIL IH264VENC_ERR_TARGETFR AMERATE This fatal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if targetFrameRate in dynamic param...

Page 57: ... or 1 for High Profile profileIdc 100 IH264VENC_ERR_TRANSFOR M8X8FLAGINTER_IN_BP_MP transform8x8FlagInterFrame not supported a fatal input error is returned during algInit if transform8x8FlagInterFrame is enabled for Baseline or Main Profile profileIdc 66 or 77 or if the value is out of the supported range 0 or 1 for High Profile profileIdc 100 IH264VENC_ERR_SEQSCALI NGFLAG_IN_BP_MP seqScalingFlag...

Page 58: ...VENC_ERR_MEALGO meAlgo not supported fatal input error is returned during algInit if meAlgo is not 0 or 1 IH264VENC_ERR_UNRESTRI CTEDMV unrestrictedMV not supported fatal input error is returned during algInit if unrestrictedMV is not 0 or 1 IH264VENC_ERR_ENCQUALI TY encQuality not supported fatal input error is returned during algInit if encQuality is not 0 1 or 2 IH264VENC_ERR_ENABLEAR M926TCM e...

Page 59: ...mismatch Control call returns IVIDENC1_EFAIL IH264VENC_ERR_INTRAFRA MEINTERVAL This fatal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if intraFrameInterval is less than 0 Control call returns IVIDENC1_EFAIL IH264VENC_ERR_GENERATE HEADER This fatal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if generateHeader is not 0 or 1 ...

Page 60: ...atal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if rcQMin is less than 0 or more than rcQMax Control call returns IVIDENC1_EFAIL IH264VENC_ERR_RCIQMAX This fatal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if rcQMaxI is less than 0 or more than 51 Control call returns IVIDENC1_EFAIL IH264VENC_ERR_RCIQMIN This fatal error ...

Page 61: ...AMS control call if sliceSize is not with in range The range depends on the value of sliceMode Control call returns IVIDENC1_EFAIL See the note at end of section 4 2 2 2 for more details on range and interpretation of sliceSize IH264VENC_ERR_INTRASLI CENUM This fatal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if intraSliceNum is less than 0 Control call retur...

Page 62: ... is not 0 or 1 Control call returns IVIDENC1_EFAIL IH264VENC_ERR_METADATA FLAG This fatal error is returned in videncStatus extendedError during XDM_SETPARAMS control call if metaDataGenerateConsume is not set between 0 and 3 Control call returns IVIDENC1_EFAIL IH264VENC_ERR_MAXINTER FRAMEINTERVAL This fatal unsupported param error is returned in algInit instance creation if maxInterFrameInterval ...

Page 63: ...ll returns IVIDENC1_EFAIL IH264VENC_ERR_IVIDENC1 _OUTARGS_SIZE This fatal error can be retrieved from a XDM_GETSTATUS control call if outArgs size in process call was not set to IVIDENC1_OutArgs or IH264VENC_OutArgs Process call returns IVIDENC1_EFAIL IH264VENC_ERR_IVIDENC1 _INARGS_INPUTID This fatal error is returned in outArgs extendedError if inputID in inArgs of process call is 0 Process call ...

Page 64: ...OutputDataUnits is not valid Valid values are 1 to IH264VENC_TI_MAXNUMBLOCKS Process call returns IVIDENC1_EFAIL IH264VENC_ERR_INTERLAC E_IN_BP This fatal error is returned during algInit instance creation stage if application tries to encode interlaced content in Baseline Profile mode IH264VENC_ERR_INSERTUS ERDATA This fatal error is returned in outArgs extendedError if insertUserData in extended...

Page 65: ...error is returned in sStatus videncStatus extendedError and control call returns IVIDENC1_EFAIL If the handle is incorrectly passed in a process call this error is returned in outArgs extendedError and process call returns IVIDENC1_EFAIL IH264VENC_ERR_MEMTAB_N ULL This fatal error is returned when memtabs passed to algInit or algFree are NULL or not aligned to 32bit word boundary IH264VENC_ERR_IVI...

Page 66: ...de without aprior algActivate this error is returned in sStatus videncStatus extendedError and control call returns IVIDENC1_EFAIL If a process call is made without aprior algActivate this error is returned in outArgs extendedError and process call returns IVIDENC1_EFAIL IH264VENC_WARN_LEVELID C This warning is returned in videncStatus extendedError in XDM_GETSTATUS control call after instance cre...

Page 67: ...r Evaluation IH264VENC_ERR_STATUS_B UF This warning is returned in videncStatus extendedError during XDM_GETVERSION control call if videncStatus data buf is NULL or if videncStatus data bufSize is insufficient to copy the library version string The control call returns IVIDENC1_EFAIL ...

Page 68: ... define any implementation specific parameters for a codec component 4 2 1 Common XDM Data Structures This section includes the following common XDM data structures XDM_BufDesc XDM1_BufDesc XDM_SingleBufDesc XDM1_SingleBufDesc XDM_AlgBufInfo IVIDEO_BufDesc IVIDEO1_BufDescIn IVIDENC1_Fxns IVIDENC1_Params IVIDENC1_DynamicParams IVIDENC1_InArgs IVIDENC1_Status IVIDENC1_OutArgs ...

Page 69: ...GETBUFINFO command Fields Field Data type Input Output Description minNumInBufs XDAS_Int32 Output Number of input buffers minNumOutBufs XDAS_Int32 Output Number of output buffers minInBufSize XDM_MAX _IO_BUFFERS XDAS_Int32 Output Size in bytes required for each input buffer minOutBufSize XDM_MA X_IO_BUFFERS XDAS_Int32 Output Size in bytes required for each output buffer Note For H 264 Base Main Hi...

Page 70: ...t buffer to pass metadata information from codec to application High resolution needs an extra input buffer to pass metadata information from application to codec The metadata is copied from output buffer of low resolution encoder to the input buffer of high resolution encoder These are the maximum buffer sizes but you can reconfigure depending on the format of the bit stream 4 2 1 3 XDM1_BufDesc ...

Page 71: ... hardware accelerator that does not write through the algorithm CPU then bits in this mask should not be set Note This feature is not supported in this version of H264 Encoder 4 2 1 6 IVIDEO_BufDesc Description This structure defines the buffer descriptor for input and output buffers Fields Field Data type Input Output Description numBufs XDAS_Int32 Input Number of buffers width XDAS_Int32 Input P...

Page 72: ... same as inputHeight for height multiple of 16 For inputHeight non multiple of 16 application will set this field to next multiple of 16 Interlaced It will be same as inputHeight for height multiple of 32 For inputHeight non multiple of 32 application will set this field to next multiple of 32 framePitch XDAS_Int32 Input Frame pitch used to store the frame This field is not used by the encoder buf...

Page 73: ...of the basic or extended if being used data structure in bytes Default size is size of IH264VENC_PARAMS structure encodingPreset XDAS_Int32 Input Encoding preset See XDM_EncodingPreset enumeration for details Default value XDM_USER_DEFINED rateControlPreset XDAS_Int32 Input Rate control preset See IVIDEO_RateControlPreset enumeration for details Default value IVIDEO_STORAGE maxHeight XDAS_Int32 In...

Page 74: ...eration for details Default value IVIDEO_PROGRESSIVE reconChromaFormat XDAS_Int32 Input Chroma formats for the reconstruction buffers Set value as XDM_YUV_420SP Other values are not supported Note encodingPreset There are no tools which can cause perfromance difference Hence XDM_HIGH_QUALITY and XDM_HIGH_SPEED will give the same bitstream perfromance The maximum video height and width supported ar...

Page 75: ...pported maxFrameRate values for each level maxFrameRate maxMbsPerSecond FrameSizeinMbs See Table A 1 Level Limits in ISO IEC 14496 10 for the supported values of maxMbsPerSecond Use the following expression to calculate FrameSizeinMbs FrameSizeinMbs inputWidth inputHeight 256 See Table A 1 Level Limits in ISO IEC 14496 10 for the supported values of Max Video bit rate During creation time these va...

Page 76: ...y height lesser than 128 and greater than 96 you can use version 1 1 backward compatible mode See section 1 5 for details Note Progressive When the input height is a non multiple of 16 the encoder expects the application to pad the input frame to the nearest multiple of 16 at the bottom of the frame In this case the application should set input height to actual height but should provide the padded...

Page 77: ...as crop information in the bit stream Default value 720 refFrameRate XDAS_Int32 Input Reference or input frame rate in fps 1000 For example if the frame rate is 30 set this field to 30000 This parameter is not supported should be set equal to targetFrameRate Default value 25000 targetFrameRate XDAS_Int32 Input Target frame rate in fps 1000 For example if the frame rate is 30 set this field to 3000...

Page 78: ...g of any specific frame type for the frame IVIDEO_I_FRAME Force the frame to be encoded as I frame IVIDEO_IDR_FRAME Force the frame to be encoded as an IDR frame Default value IVIDEO_NA_FRAME interFrameInter val XDAS_Int32 Input Number of B frames between two reference frames that is the number of B frames between two P frames or I P frames This parameter is not supported It should be set to 0 mbD...

Page 79: ...Width and targetFrameRate should adhere to the standard defined level limits For an incorrect level the encoder tries to match the best level for the parameters provided However if it exceeds level 5 0 an error is reported As per the requirement level limit can be violated for targetBitRate When inputHeight inputWidth are non multiples of 16 encoder expects the application to pad the input frame t...

Page 80: ...ul when frames require buffering for example B frames and to support buffer management When there is no re ordering IVIDENC1_OutArgs outputID will be the same as this inputID field Zero 0 is not a supported inputID This value is reserved for cases when there is no output buffer provided topFieldFirstFlag XDAS_Int32 Input Flag to indicate the field order in interlaced content Valid values are XDAS_...

Page 81: ...for details 4 2 1 13 IVIDENC1_OutArgs Description This structure defines the run time output arguments for an algorithm instance object Fields Field Data type Input Output Description size XDAS_Int32 Input Size of the basic or extended if being used data structure in bytes extendedError XDAS_Int32 Output Extended error code See XDM_ErrorBit enumeration for details bytesGenerated XDAS_Int32 Output ...

Page 82: ...1_SingleBuf Desc Output The encoder fills the buffer with the encoded bit stream In case of sequences with only I and P frames these values are identical to outBufs passed in IVIDENC1_Fxns process The encodedBuf bufSize field returned corresponds to the actual valid bytes available in the buffer The bit stream is in encoded order The outputId and encodedBuf together provide information related to ...

Page 83: ...VIDENC1_Params data structure for details The size parameter in videncParams is set to size of IH264VENC_Params structure by default while using extended parameters profileIdc XDAS_Int32 Input Profile identification for the encoder The current version supports High Profile The value must be set to 66 Base line profile 77 main profile 100 high profile Default value 100 levelIdc XDAS_Int32 Input Lev...

Page 84: ...ams insertion in SPS If 0 VUI is not inserted in SPS 1 VUI is inserted in SPS The VUI message is generated internally by the codec based on RC and some other API parameters Bit 1 Controls IDR frame insertion in case of RC parameter change If 0 IDR is inserted with change in RC parameters 1 IDR is not inserted with change in RC parameters Note If enableBufSEI 1 VUI param insertion condition is enab...

Page 85: ...ity XDAS_Int32 Input Flag for Encoder setting 0 version 1 1 backward compatible mode 2 High speed mode This is same as encodingPreset XDM_HIFG_SPEED Default value 2 unrestrictedMV XDAS_Int32 Input This field is reserved UMV is always ON in the encoder enableARM926Tcm XDAS_Int32 Input Flag for enabling disabling usage of ARM926 TCM 1 Uses ARM926 TCM 0 Does not use ARM926 TCM Default value 0 This co...

Page 86: ...rameters are changed dynamically i Framerate ii Bitrate iii MaxDelay iv RC Algorithm When enableVUIparams is set to 0 or 1 an IDR frame containing SPS and PPS parameter is inserted in the stream The behavior of aspectRatioX and aspectRatioY is similar to what is defined in the section E 1 3 of H 264 standard You need to specify X and Y values If it matches with the value as provided in table E 1 a...

Page 87: ...nded parameters intraFrameQP XDAS_Int32 Input Quantization Parameter QP of I frames in fixed QP mode Valid value is 0 to 51 It is useful only when rateControlPreset of IVIDENC1_Params is equal to IVIDEO_NONE RcAlgo 2 Fixed QP targetBitRate 0 Default value 28 interPFrameQP XDAS_Int32 Input Quantization Parameter QP of P frames in fixed QP mode Valid value is 0 to 51 It is useful only when rateContr...

Page 88: ...S_Int32 Input Minimum value of Quantization Parameter QP to be used while encoding Intra Frame Valid value is 0 to 51 The value for rcQMinI should not be greater than rcQMaxI The parameter is applicable only when rate control is enabled Default value 0 airRate XDAS_Int32 Input Parameter for forced Intra MB insertion in P frames 0 No forced Intra MBs n 0 number of forced Intra MB in each frame Defa...

Page 89: ...imSEI XDAS_Int32 Input Flag for enabling picture timing SEI message 0 Disable 1 Enable This parameter is disabled if EnableBufSEI is disabled Default value 0 Picture Timing SEI insertion is not supported for interlaced content intraThrQF XDAS_Int32 Input This field is reserved perceptualRC XDAS_Int32 Input Flag for enabling perceptual QP modulation of MBs 0 Disable 1 Enable Default value 1 This fe...

Page 90: ...es of HDVICP was overwritten by some other codec or by other instance of same codec with different quality settings between process call and hence reloads the code and data For example Application will set this flag to 1 if running another instance of different codec like H264 decoder or if running another H264 encoder instance with different quality setting in encQuality or encodingPreset However...

Page 91: ... to improve customise the encoding operation If the flag value is 3 the metaData is generated by the low resolution encoder but not yet consumed by high resolution encoder See Appendix D for detailed usage disableMVDCostFac tor XDAS_Int32 Input Reserved putDataGetSpaceFxn IH264VENC_T I_DataSyncP utGetFxn Input Pointer to callback module required to enable low latency feature dataSyncHandle IH264VE...

Page 92: ...at low resolution encoder is encoded as IDR I frame then no scene change information is passed to high resolution encoder Forcing intra MBs when airRate 0 is done as explained below Randomized AIR is used as intra refresh startegy In this case atlease airRate number of MBs in a frame will be set as intra except for the last module There could be more than airRate MBs as intra because there could b...

Page 93: ...gs data structure for details timeStamp XDAS_Int32 Input Time stamp value of the frame to be placed in bit stream This should be integral multiple of TimerResolution frame rate in fps Initial time stamp value for first frame should be 0 Default is calculated as Frame number TimerResolution Frame rate in fps See Appendix A for more details insertUserData XDAS_Int32 Input Flag to enable insertion of...

Page 94: ...time output arguments for the H 264 Encoder instance object Fields Field Data type Input Output Description videncOutArgs IVIDENC1_OutAr gs Output See IVIDENC1_OutArgs data structure for details numPackets XDAS_Int32 Output Total number of packets slices in the encoded frame The size of the packet is part of outBufs memory of the process call offsetUserDat a XDAS_Int32 Output This is the offset in...

Page 95: ...H264VENC_Fxns Description This structure defines all of the operations for the H 264 Encoder instance object Fields Field Data type Input Output Description ividenc IVIDENC1_Fxns Output See IVIDENC1_Fxns data structure for details ...

Page 96: ...X and Y co ordinates of given point Fields Field Data type Input Output Description x XDAS_Int32 Input This will specify the X co ordinate of a given point y XDAS_Int32 Input This will specify the Y co ordinate of a given point 4 3 1 2 XDM_Rect Description This structure defines all the fields required to specify a rectangle This will be used to specify top left and bottom right co ordinates of a ...

Page 97: ...OBJECT FOREGROUND_OBJECT Type of ROI is FOREGROUND OBJECT DEFAULT_OBJECT Type of ROI is DEFAULT OBJECT ROI_type PRIVACY_MASK Type of ROI is PRIVACY MASK 4 3 1 4 ROI_Interface Description This structure defines all the fields required to send ROI data to the algorithm Field Data type Input Output Description listROI MAX_ROI XDM_Rect Input For a given ROI this gives the X and Y co ordinates of the t...

Page 98: ...termines the number of bits given to ROI Note In current implementation MAX_ROI supported is 5 There is support for different priorities for different ROIs in this version of H264 Encoder But ROIs of same ROI_type should have same priority Overlapping of ROIs of same ROI_type is allowed in this release ROI of type PRIVACY_MASK is not supported in this version of H264 Encoder ROI can be of any type...

Page 99: ... to store MB information It contains following elements Fields Field Data type Input Output Description numBitsMB XDAS_UInt16 Output Number of bits to encode MB mbCodingMode XDAS_UInt8 Output MB coding mode Inter or Intra mbQP XDAS_UInt8 Output QP of MB 4 4 2 MBRowinfo Description This structure contains buffer description of MB row related parameters Fields Field Data type Input Output Descriptio...

Page 100: ...o encode frame by low resolution encoder frameRate XDAS_UInt32 Output Frame rate per second Bitrate XDAS_UInt32 Output Target bit rate in bps mvSADpointer XDAS_UInt32 Output Pointer to MVSAD of all the MBs in a frame mbComplexity MBinfo Output Pointer to MB information of all the MBs in a frame gmvPointerVert MBRowinfo Output Pointer to vertical GMV values per row Note When mvSADflag is disabled t...

Page 101: ...data being transferred via callback for producing the encoded data at NAL level Fields Field Data type Input Output Description Size XDAS_Int32 Input Size of this structure numBlocks XDAS_Int32 Input Number of blocks provided for writing the encoded NAL Valid values are between 1 to IH264VENC_TI_MAX_NUMBLOCKS varBlockSizesFla g XDAS_Int32 Input Flag indicating whether any of the data blocks vary i...

Page 102: ...oviding output data via callback 4 5 3 2 IH264VENC_TI_DataSyncPutGetFxn Typedef to pointer to callback module used by encoder to signal data ready to consumer and to get the space for next set of data Consumer need to define this API Returns the successor failure status Valid return value is XDM_EOK or XDM_EFAIL Name IH264VENC_TI_DataSyncPutGetFxn Synopsis typedef XDAS_Int32 IH264VENC_TI_DataSyncP...

Page 103: ...ICEMODE provide encoded data after one slice is encoded IH264VENC_TI_DataMod e IH264VENC_TI_ENTIREFRA ME provide encoded data after entire frame is encoded 4 5 4 2 H264VENC_TI_SliceFormat Description Describes the output slice format of encoder This enumeration type is used to specify codec encode stream format type Fields Enumeration Class Symbolic Constant Name Description IH264VENC_TI_NALSTREAM...

Page 104: ...duce slice of 2MB row and the Low latency call back API will get called after 1 slice encode for data exchange Syncronization and Data Exchange If the encoder is run in the above mode the application will see the call back function getting invoked after 1 slice encode Application can use this call back API for synchronization as well as data exchange If the next 2MB row of data is put into DDR by ...

Page 105: ...Activate process algDeactivate Termination algFree You must call these APIs in the following sequence 1 algNumAlloc 2 algAlloc 3 algInit 4 algActivate 5 process 6 algDeactivate 7 algFree control can be called any time after calling the algInit API algNumAlloc algAlloc algInit algActivate algDeactivate and algFree are standard XDAIS APIs This document includes only a brief description for the stand...

Page 106: ...ts Void Return Value XDAS_Int32 number of buffers required Description algNumAlloc returns the number of buffers that the algAlloc method requires This operation allows you to allocate sufficient space to call the algAlloc method algNumAlloc may be called at any time and can be called repeatedly without any side effects It always returns the same result The algNumAlloc API is optional For more det...

Page 107: ...initialized The first argument to algAlloc is a pointer to a structure that defines the creation parameters This pointer may be NULL however in this case algAlloc must assume default creation parameters and must not fail The second argument to algAlloc is an output parameter algAlloc may return a pointer to its parent IALG functions If an algorithm does not require a parent object to be created th...

Page 108: ...ion necessary to complete the run time creation of an algorithm instance object After a successful return from algInit the instance object is ready to be used to process data The first argument to algInit is a handle to an algorithm instance This value is initialized to the base field of memTab 0 The second argument is a table of memory records that describe the base address size alignment type an...

Page 109: ... handle IVIDENC1_Cmd id algorithm specific control commands IVIDENC1_DynamicParams params algorithm run time parameters IVIDENC1_Status status algorithm instance status parameters Return Value IALG_EOK status indicating success IALG_EFAIL status indicating failure Description This function changes the run time parameters of an algorithm instance and queries the algorithm s status control must only...

Page 110: ... calling this function otherwise its operation is undefined control can only be called after a successful return from algInit and algActivate handle must be a valid handle for the algorithm s instance object Post conditions The following conditions are true immediately after returning from this function If the control operation is successful the return value from this operation is equal to IALG_EO...

Page 111: ...Void Description algActivate initializes any of the instance scratch buffers using the persistent memory that is part of the algorithm s instance object The first and only argument to algActivate is an algorithm instance handle This handle is used by the algorithm to identify various buffers that must be initialized prior to calling any of the algorithm processing methods For more details see TMS3...

Page 112: ...t buffer descriptor data structures respectively see XDM_BufDesc data structure for details Input output buffers should be allocated in non cacheable non bufferable region if low latency is enabled The fourth argument is a pointer to the IVIDENC1_InArgs data structure that defines the run time input arguments for an algorithm instance object The last argument is a pointer to the IVIDENC1_OutArgs d...

Page 113: ...If the process operation is successful the return value from this operation is equal to IALG_EOK otherwise it is equal to either IALG_EFAIL or an algorithm specific return value Example See test application file h264encoderapp c available in the client test src sub directory See Also algInit algDeactivate control Note A video encoder or decoder cannot be pre empted by any other video encoder or de...

Page 114: ...ent memory that is part of the algorithm s instance object The first and only argument to algDeactivate is an algorithm instance handle This handle is used by the algorithm to identify various buffers that must be saved prior to next cycle of algActivate and processing For more details see TMS320 DSP Algorithm Standard API Reference literature number SPRU360 See Also algActivate 4 6 5 Termination ...

Page 115: ...y regions after closing an instance of the algorithm The first argument to algFree is a handle to the algorithm instance The second argument is a table of memory records that describe the base address size alignment type and memory space of all buffers previously allocated for the algorithm instance For more details see TMS320 DSP Algorithm Standard API Reference literature number SPRU360 See Also...

Page 116: ...API Reference 4 70 This page is intentionally left blank ...

Page 117: ...mp for each frame Ideally the time stamp can be set based on the frame rate This simplifies the process of generating time stamps However the application is free to use any method of time stamp generation Time stamp based on frame rate can be generated as follows Let f be the frame rate of the sequence Assuming a constant frame rate sequence set TimeScale k f NumUnitsinTicks n where k is an intege...

Page 118: ... NumUnitsInTicks 2 units_per_frame 1 TimeStamp 0 1 2 3 4 Example 3 f 15 k 1000 TimeScale 1000 15 15000 NumUnitsInTicks 1000 units_per_frame 1 TimeStamp 0 1 2 3 4 Example 4 f 0 5 k 200 TimeScale 200 0 5 100 NumUnitsinTicks 100 units_per_frame 2 TimeStamp 0 2 4 6 8 ...

Page 119: ...s listed in the following table ProfileIDC Profile Inputparam values that results in FATAL ERROR 66 Baseline inputContentType 1 transform8x8FlagIntraFrame 1 transform8x8FlagInterFrame 1 seqScalingFlag 1 entropyMode 1 77 Main transform8x8FlagIntraFrame 1 transform8x8FlagInterFrame 1 seqScalingFlag 1 100 High In addition to this if any other input parameter is beyond the range specified in the user ...

Page 120: ...Error Description B 2 This page is intentionally left blank ...

Page 121: ...used The Framework component FC manages the VCIP buffers using VCIP resource manager In context of DM365 DM368 VICP buffers can be used by following algorithms MPEG4 and JPEG running on MJCP H 264 codec running on HDVICP Preprocessing algorithms or noise filter running on IMX NSF Any of these algorithms can place its request to VICP buffers FC services the VICP buffer request in a sequential manne...

Page 122: ...anaged by FC The memories in red are reserved for MJCP only FC gives the VICP memory to the algorithm from the start of the pool Hence it is the application s responsibility to instantiate the various algorithms in a way that an efficient usage of VICP buffers is achieved The amount of VICP buffer usage by the codec is part of datasheet provided in the release ...

Page 123: ...64 codec uses part of VICP buffers for its execution However when this codec is run along with an application that requires more VICP buffers like MPEG4 and JPEG running on MJCP then algorithm cannot use the VICP buffers originally used by it Therefore some of the buffers used in VICP will be transferred to ARM926 TCM The ARM926 TCM buffers are managed by Framework component FC using ARM TCM resou...

Page 124: ...ARM926 TCM Buffer Usage By Codec D 2 This page is intentionally left blank ...

Page 125: ... no information is passed to high resolution encoder for the corresponding frame 3 Case 3 If there is a frame skip at high resolution encoder the frame level information is retained and is consumed at next frame For example if SceneChange occurs at Nth frame and it is frame skip then the IDR frame is inserted at high resolution at N 1 th frame This way information is preserved and utilized at high...

Page 126: ...Simple Two pass Encoding Sample Usage E 2 Case 1 Case 2 Case 3 Case 4 Frame Skip ...

Page 127: ...lution encoder 4 Update metadata values in frame_info structure at low resolution encoder Once encoding operation is completed copy the metadata into the output buffers of low resolution encoder requested in the step 2 5 If the frame skip occurs at low resolution no metadata information is passed to the high resolution encoder 6 Now set the value of metaDataGenerateConsume flag for low resolution ...

Page 128: ...tadata in low resolution encoder Output Buffer requirement by low resolution encoder Structure Name Buffer Size FrameInfo_Interface sizeof FrameInfo_Interface MBInfo uiSize 4 4 MBRowInfo uiExtHeight 4 Where uiSize is the maximum number of pixels in a frame and uiExtHeight is the height of the frame in pixels Addresses of these buffers are passed to the codec where variables of the structures See S...

Page 129: ...e to 1 At application Set metaDataGenerateConsume flag of low resolution encoder to 1 Note When setting dynamicparams metaDataGenerateConsume 2 for the high resolution encoder the low resolution encoder must be run with dynamic params metaDataGenerateConsume 1 else severe quality degradation will occur The usage of the generated metaData by the high resolution encoder is internal to the codec and ...

Page 130: ...Simple Two pass Encoding Sample Usage E 6 This page is intentionally left blank ...

Page 131: ...to the SPRUEU9A codec specific user guide to make it SPRUEU9B Table F 1 Revision History for H 264 Base Main High Profile Encoder on DM365 DM368 Section Changes Global There are no major changes in the user guide for this release of H 264 Base Main High Profile Encoder on DM365 DM368 ...

Search results

Summary of Contents for DM365

Reviews:

Brands by name

Popular brands

Texas Instruments DM365, User Manual

Search results

Summary of Contents for DM365

Reviews:

Brands by name

Popular brands