jpuapi.h 57 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426
  1. /*
  2. * Copyright (c) 2018, Chips&Media
  3. * All rights reserved.
  4. *
  5. * Redistribution and use in source and binary forms, with or without
  6. * modification, are permitted provided that the following conditions are met:
  7. *
  8. * 1. Redistributions of source code must retain the above copyright notice, this
  9. * list of conditions and the following disclaimer.
  10. * 2. Redistributions in binary form must reproduce the above copyright notice,
  11. * this list of conditions and the following disclaimer in the documentation
  12. * and/or other materials provided with the distribution.
  13. *
  14. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  15. * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  16. * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  17. * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
  18. * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  19. * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  20. * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  21. * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22. * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  23. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24. */
  25. #ifndef JPUAPI_H_INCLUDED
  26. #define JPUAPI_H_INCLUDED
  27. #include "jpuconfig.h"
  28. #include "../jdi/jdi.h"
  29. #include "jputypes.h"
  30. /* _n: number, _s: significance */
  31. #define JPU_CEIL(_s, _n) (((_n)+(_s-1))&~(_s-1))
  32. #define JPU_FLOOR(_s, _n) (_n&~(_s-1))
  33. //------------------------------------------------------------------------------
  34. // common struct and definition
  35. //------------------------------------------------------------------------------
  36. /**
  37. * @brief
  38. This is a special enumeration type for representing the JPEG profiles.
  39. */
  40. typedef enum {
  41. /* Non-differential, Huffman coding */
  42. JPEG_BASELINE_DCT, /**< JPEG baseline profile */
  43. JPEG_EXTENDED_SEQUENTIAL_DCT, /**< JPEG extended sequential profile */
  44. /* The others are not supported on CODAJ12 */
  45. } JpgProfile;
  46. /**
  47. * @brief
  48. This is a special enumeration type for some configuration commands from host
  49. processor to the JPU. Most of these commands can be called occasionally, not
  50. periodically for changing the configuration of decoder operations running on the
  51. JPU. Details of these commands will be presented in the next chapter.
  52. */
  53. typedef enum {
  54. SET_JPG_SCALE_HOR, /**< This command sets the scale down ratio for picture width. The scale ratio value can be either 1(1/2 scale), 2(1/4 scale) or 3(1/8 scale). */
  55. SET_JPG_SCALE_VER, /**< This command sets the scale down ratio for picture height. The scale ratio value can be either 1(1/2 scale), 2(1/4 scale) or 3(1/8 scale). */
  56. SET_JPG_USE_STUFFING_BYTE_FF, /**< This command sets use of stuffing byte, 0xFF. */
  57. SET_JPG_QUALITY_FACTOR, /**< This command sets use of quality factor. */
  58. ENC_JPG_GET_HEADER, /**< This command generates JPEG high-level header syntaxes. */
  59. ENABLE_LOGGING, /**< This command activates message logging once JPU_DecOpen() or JPU_EncOpen() is called. */
  60. DISABLE_LOGGING, /**< This command deactivates message logging. (default) */
  61. JPG_CMD_END
  62. } JpgCommand;
  63. /**
  64. * @brief
  65. This is a type for representing physical addresses which is recognizable by the
  66. JPU. In general, the JPU hardware does not know about virtual address space
  67. which is set and handled by host processor. All these virtual addresses are
  68. translated into physical addresses by Memory Management Unit. All data buffer
  69. addresses such as stream buffer, frame buffer, should be given to the JPU as an
  70. address on physical address space.
  71. */
  72. typedef enum {
  73. JPG_RET_SUCCESS, /**< This means that operation was done successfully. */
  74. JPG_RET_FAILURE, /**< This means that operation was not done successfully. */
  75. JPG_RET_BIT_EMPTY, /**< This means that bitstream buffer is found to be empty during decode operation. */
  76. JPG_RET_EOS, /**< This means the end of stream. */
  77. JPG_RET_INVALID_HANDLE, /**< This means that the given handle for the current API function call was invalid(for example, not initialized yet, improper function call for the given handle, etc.). */
  78. JPG_RET_INVALID_PARAM, /**< This means that the given argument parameters (for example, input data structure) was invalid (not initialized yet or not valid anymore). */
  79. JPG_RET_INVALID_COMMAND, /**< This means that the given command was invalid (for example, undefined, or not allowed in the given instances). */
  80. JPG_RET_ROTATOR_OUTPUT_NOT_SET, /**< This means that rotator output buffer was not allocated even though postprocessor (rotation, mirroring, or deringing) is enabled. */
  81. JPG_RET_ROTATOR_STRIDE_NOT_SET, /**< This means that rotator stride was not provided even though postprocessor (rotation, mirroring, or deringing) is enabled. */
  82. JPG_RET_FRAME_NOT_COMPLETE, /**< This means that frame decoding operation was not completed yet, so the given API function call cannot be allowed. */
  83. JPG_RET_INVALID_FRAME_BUFFER, /**< This means that the given source frame buffer pointers were invalid in encoder (not initialized yet or not valid anymore). */
  84. JPG_RET_INSUFFICIENT_FRAME_BUFFERS, /**< This means that the given numbers of frame buffers were not enough for the operations of the given handle. */
  85. JPG_RET_INVALID_STRIDE, /**< This means that the given stride was invalid (for example, 0, not a multiple of 8 or smaller than picture size). */
  86. JPG_RET_WRONG_CALL_SEQUENCE, /**< This means that the current API function call was invalid considering the allowed sequences between API functions (for example, missing one crucial function call before this function call). */
  87. JPG_RET_CALLED_BEFORE, /**< This means that multiple calls of the current API function for a given instance are invalid. */
  88. JPG_RET_NOT_INITIALIZED, /**< This means that JPU was not initialized yet. Before calling any API functions, the initialization API function, JPU_Init(), should be called at the beginning. */
  89. JPG_RET_INSUFFICIENT_RESOURCE, /**< This means that JPU cannot allocate memory due to lack of memory. */
  90. JPG_RET_INST_CTRL_ERROR, /**< This means there was a fault in instance control. */
  91. JPG_RET_NOT_SUPPORT, /**< This means that HOST application uses an API option that is not supported in current hardware. */
  92. } JpgRet;
  93. /**
  94. * @brief
  95. This is a special enumeration type for representing the current encoder states.
  96. */
  97. typedef enum {
  98. ENCODE_STATE_NEW_FRAME = 0, /**< The state indicates the start of a new frame. It appears for slice encoding. */
  99. ENCODE_STATE_FRAME_DONE = 0, /**< The state indicates the completion of encoding a frame. */
  100. ENCODE_STATE_SLICE_DONE = 1 /**< The state indicates the completion of encoding a slice. */
  101. } EncodeState;
  102. /**
  103. * @brief
  104. This is an enumeration type for representing mirroring directions.
  105. */
  106. typedef enum {
  107. MIRDIR_NONE, /**< No mirroring */
  108. MIRDIR_VER, /**< Vertical mirroring */
  109. MIRDIR_HOR, /**< Horizontal mirroring */
  110. MIRDIR_HOR_VER /**< Horizontal and veritical mirroring */
  111. } JpgMirrorDirection;
  112. /**
  113. * @brief
  114. This is an enumeration type for representing frame buffer formats.
  115. */
  116. typedef enum {
  117. FORMAT_420 = 0, /**< YUV420 format */
  118. FORMAT_422 = 1, /**< YUV422 format */
  119. FORMAT_440 = 2, /**< YUV440 format */
  120. FORMAT_444 = 3, /**< YUV444 format */
  121. FORMAT_400 = 4, /**< YUV400 format */
  122. FORMAT_MAX
  123. } FrameFormat;
  124. /**
  125. * @brief
  126. This is an enumeration type for representing a CbCr interleave mode of frame buffer.
  127. */
  128. typedef enum {
  129. CBCR_SEPARATED = 0, /**< Cb data and Cr data are located in each separate plane. */
  130. CBCR_INTERLEAVE, /**< Chroma data are interleaved in Cb and Cr order. */
  131. CRCB_INTERLEAVE /**< Chroma data are interleaved in Cr and Cb order. */
  132. } CbCrInterLeave;
  133. /**
  134. * @brief
  135. This is an enumeration type for representing a packed format of frame buffer.
  136. */
  137. typedef enum {
  138. PACKED_FORMAT_NONE,
  139. PACKED_FORMAT_422_YUYV, /**< This is YUV422 packed format with YUYV component order. */
  140. PACKED_FORMAT_422_UYVY, /**< This is YUV422 packed format with UYVY component order. */
  141. PACKED_FORMAT_422_YVYU, /**< This is YUV422 packed format with YVYU component order. */
  142. PACKED_FORMAT_422_VYUY, /**< This is YUV422 packed format with VYUY component order. */
  143. PACKED_FORMAT_444, /**< This is YUV444 packed format. */
  144. PACKED_FORMAT_MAX
  145. } PackedFormat;
  146. typedef enum {
  147. O_FMT_NONE,
  148. O_FMT_420,
  149. O_FMT_422,
  150. O_FMT_444,
  151. O_FMT_MAX
  152. } OutputFormat;
  153. /* Assume that pixel endianness is big-endian.
  154. * b0 is low address in a framebuffer.
  155. * b1 is high address in a framebuffer.
  156. * pixel consists of b0 and b1.
  157. * RIGHT JUSTIFICATION: (default)
  158. * lsb msb
  159. * |----|--------|
  160. * |0000| pixel |
  161. * |----|--------|
  162. * | b0 | b1 |
  163. * |-------------|
  164. * LEFT JUSTIFICATION:
  165. * lsb msb
  166. * |--------|----|
  167. * | pixel |0000|
  168. * |--------|----|
  169. * | b0 | b1 |
  170. * |-------------|
  171. */
  172. enum JPU_PIXEL_JUSTIFICATION {
  173. PIXEL_16BIT_MSB_JUSTIFIED,
  174. PIXEL_16BIT_LSB_JUSTIFIED,
  175. PIXEL_16BIT_JUSTIFICATION_MAX,
  176. };
  177. /**
  178. * @brief
  179. This is an enumeration type for representing the JPU interrupt reasons.
  180. */
  181. typedef enum {
  182. INT_JPU_DONE = 0, /**< This interrupt indicates the completion of encoding/decoding a frame. */
  183. INT_JPU_ERROR = 1, /**< This interrupt indicates occurrence of error. */
  184. INT_JPU_BIT_BUF_EMPTY = 2, /**< This interrupt indicates JPU encounters empty bitstream buffer while decoding. */
  185. INT_JPU_BIT_BUF_FULL = 2, /**< This interrupt indicates full state of bitstream buffer while encoding. */ /* For encoder */
  186. INT_JPU_SLICE_DONE = 9, /**< This interrupt indicates the completion of encoding a slice. */ /* For encoder */
  187. }InterruptJpu;
  188. /**
  189. * @brief
  190. This is an enumeration type for representing quantization and Huffman table encoding modes.
  191. */
  192. typedef enum {
  193. JPG_TBL_NORMAL,
  194. } JpgTableMode;
  195. /**
  196. * @brief
  197. This is an enumeration type for representing encode header modes.
  198. */
  199. typedef enum {
  200. ENC_HEADER_MODE_NORMAL, /**< Generation of the whole JPEG header syntaxes */
  201. ENC_HEADER_MODE_SOS_ONLY /**< Generation of scan header syntax only */
  202. } JpgEncHeaderMode;
  203. /**
  204. * @brief This is an enumeration type for representing scale down ratios.
  205. */
  206. enum JPU_DOWNSCALE_VAL {
  207. JPG_SCALE_DOWN_NONE, /**< No scaling */
  208. JPG_SCALE_DOWN_ONE_HALF, /**< 1/2 scale*/
  209. JPG_SCALE_DOWN_ONE_QUARTER, /**< 1/4 scale */
  210. JPG_SCALE_DOWN_ONE_EIGHTS, /**< 1/8 scale */
  211. JPG_SCALE_DOWN_MAX
  212. };
  213. /**
  214. * @brief This is an enumeration type for representing a product ID.
  215. */
  216. enum JPU_PRODUCT_ID {
  217. PRODUCT_ID_CODAJ12 = 12,
  218. };
  219. /**
  220. * @brief
  221. @verbatim
  222. This is a data structure for representing frame buffer pointers of each Y/Cb/Cr color
  223. component. In case of CbCr interleave mode, Cb and Cr frame data are written to memory area starting
  224. from the given bufCb address.
  225. All of the Y/Cb/Cr component addresses must be 8-byte aligned.
  226. A pixel value occupies 1 byte for JPEG baseline sequential and 2 bytes for JPEG extended sequential(12bit).
  227. In case the frame format is YCbCr420, the sizes of Cb and Cr buffer are 1/4 of Y buffer size.
  228. Host application must allocate frame buffers for each Y/Cb/Cr component in consideration of alignment and chroma format buffer size .
  229. @endverbatim
  230. */
  231. typedef struct {
  232. PhysicalAddress bufY; /**< It indicates the base address for Y component in the physical address space when linear map is used. */
  233. PhysicalAddress bufCb; /**< It indicates the base address for Cb component in the physical address space when linear map is used. */
  234. PhysicalAddress bufCr; /**< It indicates the base address for Cr component in the physical address space when linear map is used. */
  235. Uint32 stride; /**< A horizontal stride for luma frame buffer */ /* luma stride */
  236. Uint32 strideC;/**< A horizontal stride for chroma frame buffer */ /* chroma stride */
  237. FrameFormat format; /**< <<jpuapi_h_OutputFormat>> */
  238. /**
  239. @verbatim
  240. Bitstream buffer endianess
  241. @* 0 : little endian format
  242. @* 1 : big endian format
  243. @* 2 : 32 bits little endian format
  244. @* 3 : 32 bits big endian format
  245. @endverbatim
  246. */
  247. Uint32 endian;
  248. } FrameBuffer;
  249. struct JpgInst;
  250. /**
  251. * @brief
  252. This is a dedicated type for JPG handle returned when an instance is opened.
  253. An instance can be referred to by the corresponding handle.
  254. Application does not need to care about it.
  255. */
  256. typedef struct JpgInst * JpgHandle;
  257. //------------------------------------------------------------------------------
  258. // decode struct and definition
  259. //------------------------------------------------------------------------------
  260. typedef struct JpgInst JpgDecInst;
  261. /**
  262. * @brief
  263. @verbatim
  264. This is a dedicated type for decoder handle returned when a decoder instance is
  265. opened. A decoder instance can be referred to by the corresponding handle.
  266. JpgDecInst is a type managed internally by API. Application does not need to
  267. care about it.
  268. NOTE: This type is vaild for decoder only.
  269. @endverbatim
  270. */
  271. typedef JpgDecInst * JpgDecHandle;
  272. /* JPU Capabilities */
  273. /**
  274. * @brief
  275. This is a data structure for representing JPU capabilities.
  276. */
  277. typedef struct {
  278. Uint32 productId; /**< Product ID number, 12 */
  279. Uint32 revisoin; /**< Revision number of hardware */
  280. BOOL support12bit; /**< It indicates whether to support an extended sequential JPEG, 12bit. */
  281. } JPUCap;
  282. /**
  283. * @brief
  284. This data structure is used when host application wants to open a new decoder instance.
  285. */
  286. typedef struct {
  287. PhysicalAddress bitstreamBuffer; /**< The start address of bit stream buffer from which the decoder can get the next bitstream. This address must be 8-byte aligned.*/
  288. Uint32 bitstreamBufferSize; /**< The virtual address according to bitstreamBuffer. This address is needed when the host wants to access bitstream.*/
  289. BYTE* pBitStream; /**< The size of the buffer pointed by bitstreamBuffer in byte. This value must be a multiple of 1024. The maximum size is 16383 x 1024 bytes.*/
  290. /**
  291. @verbatim
  292. Bitstream buffer endianess
  293. @* 0 : little endian format
  294. @* 1 : big endian format
  295. @* 2 : 32 bits little endian format
  296. @* 3 : 32 bits big endian format
  297. @endverbatim
  298. */
  299. Uint32 streamEndian;
  300. /**
  301. @verbatim
  302. Frame buffer endianess
  303. * 0 : little endian format
  304. * 1 : big endian format
  305. * 2 : 32 bits little endian format
  306. * 3 : 32 bits big endian format
  307. @endverbatim
  308. */
  309. Uint32 frameEndian;
  310. /**
  311. @verbatim
  312. @* 0: CbCr data is written in separate frame memories (chroma separate mode)
  313. @* 1: CbCr data is interleaved in chroma memory. (chroma interleave mode)
  314. @endverbatim
  315. */
  316. CbCrInterLeave chromaInterleave;
  317. PackedFormat packedFormat; /**< This is for packed image format. It is valid only when source image format is written in YUV444 or RGB24. */
  318. BOOL roiEnable; /**< This enables the ROI (Region of Interest). */
  319. Uint32 roiOffsetX; /**< This is ROI offset for width. */
  320. Uint32 roiOffsetY; /**< This is ROI offset for height. */
  321. Uint32 roiWidth; /**< This is ROI width from RoiOffsetX. */
  322. Uint32 roiHeight; /**< This is ROI width from RoiOffsetY. */
  323. Uint32 pixelJustification; /**< It specifies pixel justification of source image for 12bit encoding mode. */ /* avaliable in 16bit pixel. */
  324. Uint32 intrEnableBit; /**< It specifies an interrupt enable bit. For the meaning of each bit, refer to <<jpuapi_h_InterruptJpu>>. */
  325. Uint32 rotation; /**< It rotates decoded images in 0, 90, 180, or 270 degree */
  326. JpgMirrorDirection mirror; /**< <<jpuapi_h_JpgMirrorDirection>> */
  327. FrameFormat outputFormat; /**< <<jpuapi_h_OutputFormat>> */
  328. } JpgDecOpenParam;
  329. /**
  330. * @brief
  331. Data structure to get information necessary to start decoding from the decoder.
  332. */
  333. typedef struct {
  334. /**
  335. @verbatim
  336. Horizontal picture size in pixels
  337. This width value will be used while allocating decoder frame buffers. In some
  338. cases, this returned value, the display picture width declared on stream header,
  339. should be modified before allocating frame buffers. When picture width is not a
  340. multiple of 16, picture width for buffer allocation should be re-calculated from
  341. the declared display width as follows:
  342. picBufWidth = {( picWidth + 15)/16}* 16,
  343. where picBufWidth is the horizontal picture buffer width. When picWidth is a
  344. multiple of 16, picWidth = picBufWidth.
  345. */
  346. int picWidth;
  347. /**
  348. @verbatim
  349. Vertical picture size in pixels
  350. This height value will be used while allocating decoder frame buffers. In some
  351. cases, this returned value, the display picture height declared on stream
  352. header, should be modified before allocating frame buffers. When picture height
  353. is not a multiple of 16, picture height for buffer allocation should be
  354. re-calculated from the declared display height as follows:
  355. picBufHeight = {( picHeight + 15)/16}* 16,
  356. where picBufHeight is the vertical picture buffer height. When picHeight is a
  357. multiple of 16, picHeight = picBufHeight.
  358. @endverbatim
  359. */
  360. int picHeight;
  361. /**
  362. This is the minimum number of frame buffers required for decoding. Applications
  363. must allocate at least as many as this number of frame buffers and register the
  364. number of buffers to the JPU using JPU_DecRegisterFrameBuffer() before decoding
  365. pictures.
  366. */
  367. int minFrameBufferCount;
  368. FrameFormat sourceFormat; /**< <<jpuapi_h_FrameFormat>> */
  369. int ecsPtr; /**< This is an entropy-coded segment pointer of the first frame. */
  370. int roiFrameWidth; /**< This is width of ROI region. */
  371. int roiFrameHeight;/**< This is height of ROI region. */
  372. int roiFrameOffsetX; /**< This is x position of ROI region. */
  373. int roiFrameOffsetY; /**< This is y position of ROI region. */
  374. Uint32 bitDepth; /**< 8 for baseline sequential, 12 for extended sequential */
  375. } JpgDecInitialInfo;
  376. /**
  377. * @brief
  378. The data structure to set a scaler ratio.
  379. */
  380. typedef struct {
  381. int scaleDownRatioWidth; /**< The ratio of frame width to scale down */
  382. /**
  383. @verbatim
  384. The ratio of frame height to scale down. It might have one of the following values:
  385. @* 0 : no scale
  386. @* 1 : (1/2 scale)
  387. @* 2 : (1/4 scale)
  388. @* 3 : (1/8 scale)
  389. @endverbatim
  390. */
  391. int scaleDownRatioHeight;
  392. } JpgDecParam;
  393. /**
  394. * @brief
  395. The data structure to get result information from decoding a frame.
  396. */
  397. typedef struct {
  398. /**
  399. This is the frame buffer index of a picture to be displayed this time among
  400. frame buffers which were registered using JPU_DecRegisterFrameBuffer(). Frame
  401. data to be displayed this time will be stored into the frame buffer specified by
  402. this index. When delay in display does not exist, this index will always be the
  403. same with indexFrameDecoded.
  404. At the end of sequence decoding, if there is no more output for display, then
  405. this value will have -1 (0xFFFF). So by checking this index, host applications
  406. can easily know whether sequence decoding has been finished or not.
  407. */
  408. int indexFrameDisplay;
  409. int numOfErrMBs; /**< The number of erroneous macroblocks while decoding a picture */
  410. /**
  411. @verbatim
  412. @* 0 : incomplete finish of decoding process
  413. @* 1 : complete finish of decoding process
  414. @endverbatim
  415. */
  416. int decodingSuccess;
  417. int decPicHeight; /**< The JPU reports the height of a decoded picture in pixel unit after decoding one frame. This value will be updated, when sequence information for resolution is changed. */
  418. int decPicWidth; /**< The JPU reports the width of a decoded picture in pixel unit after decoding one frame. This value will be updated, when sequence information for resolution is changed. */
  419. int consumedByte; /**< This means how many bytes are consumed in a bitstream. */
  420. int bytePosFrameStart; /**< This means the position of an SOI maker in bitstream buffer. */
  421. int ecsPtr; /**< This is a pointer to an entropy-coded segment of current frame. */
  422. Uint32 frameCycle; /**< This variable reports the number of clock cycles taken to decode one frame. */ /* clock cycle */
  423. Uint32 rdPtr; /**< The position of read pointer in the bitstream buffer after completion of frame decoding */
  424. Uint32 wrPtr; /**< The position of write pointer in the bitstream buffer after completion of frame decoding */
  425. } JpgDecOutputInfo;
  426. //------------------------------------------------------------------------------
  427. // encode struct and definition
  428. //------------------------------------------------------------------------------
  429. typedef struct JpgInst JpgEncInst;
  430. /**
  431. * @brief
  432. @verbatim
  433. This is a dedicated type for encoder handle returned when an encoder instance is
  434. opened. An encoder instance can be referred to by the corresponding handle.
  435. JpgEncInst is a type managed internally by API. Application does not need to
  436. care about it.
  437. NOTE: This type is vaild for encoder only.
  438. @endverbatim
  439. */
  440. typedef JpgEncInst * JpgEncHandle;
  441. /**
  442. * @brief
  443. This data structure is used when host applications want to open a new encoder
  444. instance.
  445. */
  446. typedef struct {
  447. PhysicalAddress bitstreamBuffer; /**< The start address of bit stream buffer into which encoder puts bit streams. This address must be a multiple of 4, namely, 4 byte-aligned. */
  448. Uint32 bitstreamBufferSize; /**< The size of the buffer in bytes pointed by bitstreamBuffer. This value must be a multiple of 1024. The maximum size is 16383 x 1024 bytes. */
  449. Uint32 picWidth; /**< The width of a picture to be encoded in pixels */
  450. Uint32 picHeight; /**< The height of a picture to be encoded in pixels */
  451. FrameFormat sourceFormat; /**< <<jpuapi_h_FrameFormat>> */
  452. Uint32 restartInterval; /**< The number of MCU in the restart interval */
  453. /**
  454. @verbatim
  455. Bitstream buffer endianess
  456. @* 0 : little endian format
  457. @* 1 : big endian format
  458. @* 2 : 32 bits little endian format
  459. @* 3 : 32 bits big endian format
  460. @endverbatim
  461. */
  462. Uint32 streamEndian;
  463. /**
  464. @verbatim
  465. Frame buffer endianess
  466. @* 0 : little endian format
  467. @* 1 : big endian format
  468. @* 2 : 32 bits little endian format
  469. @* 3 : 32 bits big endian format
  470. @endverbatim
  471. */
  472. Uint32 frameEndian;
  473. /**
  474. @verbatim
  475. @* 0 : CbCr data is written in separate frame memories (chroma separate mode)
  476. @* 1 : CbCr data is interleaved in chroma memory. (chroma interleave mode)
  477. @endverbatim
  478. */
  479. CbCrInterLeave chromaInterleave;
  480. BYTE huffVal[8][256]; /**< A list of the 8-bit symbol values in Huffman tables. */
  481. BYTE huffBits[8][256]; /**< A 16-byte list giving number of codes for each code length from 1 to 16 in Huffman tables. */
  482. short qMatTab[4][64]; /**< Quantization tables */
  483. BOOL jpg12bit; /**< It enables 12bit encoding mode. */
  484. BOOL q_prec0; /**< Luma quantization tables for 12bit encoding mode */
  485. BOOL q_prec1; /**< Chroma quantization tables for 12bit encoding mode */
  486. PackedFormat packedFormat; /**< It specifies a packed image format. It is valid only when source image format is written in YUV444 or RGB24. */
  487. Uint32 pixelJustification; /**< It specifies pixel justification of source image for 12bit encoding mode. */
  488. Uint32 tiledModeEnable; /**< It enables use of tiled mode. */
  489. Uint32 sliceHeight; /**< It specifies a slice height for slice encoding. */
  490. Uint32 intrEnableBit; /**< It specifies an interrupt enable bit. For the meaning of each bit, refer to <<jpuapi_h_InterruptJpu>>. */
  491. BOOL sliceInstMode;
  492. Uint32 rotation; /**< It rotates source images in 0, 90, 180, or 270 degree before encoding. */
  493. Uint32 mirror; /**< <<jpuapi_h_JpgMirrorDirection>> */
  494. } JpgEncOpenParam;
  495. /**
  496. * @brief
  497. This is a data structure for configuring one frame encoding operation.
  498. */
  499. typedef struct {
  500. FrameBuffer * sourceFrame; /**< This member must represent the frame buffer containing source image to be encoded. */
  501. } JpgEncParam;
  502. /**
  503. * @brief
  504. This is a data structure for reporting the results of picture encoding operations.
  505. */
  506. typedef struct {
  507. /**
  508. The Physical address of the starting point of newly encoded picture stream
  509. If dynamic buffer allocation is enabled in line-buffer mode, this value will be
  510. identical with the specified picture stream buffer address by host applications.
  511. */
  512. PhysicalAddress bitstreamBuffer;
  513. Uint32 bitstreamSize; /**< The byte size of encoded bitstream */
  514. PhysicalAddress streamRdPtr; /**< A read pointer of bitstream buffer */
  515. PhysicalAddress streamWrPtr; /**< A write pointer of bitstream buffer */
  516. Uint32 encodedSliceYPos; /**< A vertical position of the currently encoded slice */
  517. EncodeState encodeState; /**< A result of the current encoding, completion of encoding the whole picture or completion of encoding a specific slice */
  518. Uint32 frameCycle; /**< This variable reports the number of clock cycles taken to decode one frame. */ /* clock cycle */
  519. } JpgEncOutputInfo;
  520. /**
  521. * @brief
  522. This is a data structure for generating an encoding header.
  523. */
  524. typedef struct {
  525. PhysicalAddress paraSet; /**< The physical address of bitstream buffer where header bitstream is saved */
  526. BYTE *pParaSet; /**< The virtual address of bitstream buffer where header bitstream is saved */
  527. int size; /**< The allocation size of buffer for saving header bitstream */
  528. /**
  529. @verbatim
  530. Header encoding mode
  531. @* ENC_HEADER_MODE_NORMAL: generates all sorts of headers.
  532. @* ENC_HEADER_MODE_SOS_ONLY: generates only SOS header (not any other such as SOI, APP, DRI, DQT, DHT, and SOF headers).
  533. @endverbatim
  534. */
  535. int headerMode;
  536. /**
  537. @verbatim
  538. Quantization table merge option
  539. @* 0: do not merge quantization table
  540. @* 1: merge quantization table
  541. @endverbatim
  542. */
  543. int quantMode;
  544. /**
  545. @verbatim
  546. Huffman table merge option
  547. @* 0: do not merge huffman table
  548. @* 1: merge huffman table
  549. @endverbatim
  550. */
  551. int huffMode;
  552. int disableAPPMarker; /**< It disables generating an App Marker in encoding header. */
  553. int enableSofStuffing; /**< It enables to fill 0xff at the end of header if it is not 8-byte aligned after encoding the header. (defalut: 0x00) */
  554. } JpgEncParamSet;
  555. #ifdef __cplusplus
  556. extern "C" {
  557. #endif
  558. /**
  559. * @brief This function returns whether the JPU is initialized and ready to be used.
  560. * @return
  561. @verbatim
  562. @* 0: The JPU hardware is not initialized yet. In that case, host application should call JPU_Init().
  563. @* 1: The JPU hardware is initialized.
  564. @endverbatim
  565. */
  566. Uint32 JPU_IsInit(
  567. void
  568. );
  569. /**
  570. * @brief This function waits until an interrupt arises and returns the interrupt reason if it occurs.
  571. * @param handle [Input] An instance handle obtained from JPU_EncOpen() or JPU_DecOpen()
  572. * @param timeout [Input] A timeout value in millisecond
  573. * @return
  574. @verbatim
  575. @* 0: The JPU hardware is not initialized yet. In that case, host application should call JPU_Init().
  576. @* 1: The JPU hardware is initialized.
  577. @endverbatim
  578. */
  579. Int32 JPU_WaitInterrupt(JpgHandle handle, int timeout);
  580. /**
  581. * @brief This function returns whether JPU has completed processing a frame or not.
  582. * @param handle [Input] An instance handle obtained from JPU_EncOpen() or JPU_DecOpen()
  583. * @return
  584. @verbatim
  585. @* 0: The JPU hardware is idle.
  586. @* Non-zero value: The JPU hardware is busy with processing a frame.
  587. @endverbatim
  588. */
  589. int JPU_IsBusy(JpgHandle handle);
  590. /**
  591. * @brief This function returns the reason of JPU interrupt.
  592. * @param handle [Input] An instance handle obtained from JPU_EncOpen() or JPU_DecOpen()
  593. * @return
  594. @verbatim
  595. @* 0: No Interrupt, The JPU hardware is idle.
  596. @* Non-zero value: It is an interrupt reason. Refer to <<jpuapi_h_InterruptJpu>> to know the meaning of each bit.
  597. @endverbatim
  598. */
  599. Uint32 JPU_GetStatus(JpgHandle handle);
  600. /**
  601. * @brief Clearing Interrupt
  602. * @param handle [Input] An instance handle obtained from JPU_EncOpen()
  603. * @param val [Input] The interrupt bit to be cleared
  604. * @return None
  605. */
  606. void JPU_ClrStatus(JpgHandle handle, Uint32 val);
  607. /**
  608. * @brief This function initializes the JPU hardware and proper data structures/resources. Applications
  609. must call this function only once before using the JPU.
  610. * @param None
  611. * @return
  612. @verbatim
  613. *JPG_RET_SUCCESS*::
  614. Operation was done successfully, which means the JPU initialized successfully.
  615. *JPG_RET_FAILURE*::
  616. Operation was failed, which means the JPU initialized with fail.
  617. @endverbatim
  618. */
  619. JpgRet JPU_Init();
  620. /**
  621. * @brief This function frees all the resources allocated by API.
  622. * @param None
  623. * @return None
  624. */
  625. void JPU_DeInit();
  626. /**
  627. * @brief This function returns the number of instances that have opened.
  628. * @param None
  629. * @return The number of instance that is currently running
  630. */
  631. int JPU_GetOpenInstanceNum();
  632. /**
  633. * @brief Applications can read out the version information running on the system.
  634. * @param apiVersion [output] API version ID
  635. * @param hwRevision [output] Hardware versi
  636. * @param hwProductId [output] Product ID
  637. * @return
  638. @verbatim
  639. *JPG_RET_SUCCESS*::
  640. Operation was done successfully, which means version information is acquired
  641. successfully.
  642. *JPG_RET_NOT_INITIALIZED*::
  643. JPU was not initialized at all before calling this function. Application should
  644. initialize JPU by calling JPU_Init() before calling this function.
  645. @endverbatim
  646. */
  647. JpgRet JPU_GetVersionInfo(
  648. Uint32 *apiVersion,
  649. Uint32 *hwRevision,
  650. Uint32 *hwProductId);
  651. /**
  652. * @brief
  653. This function resets JPU and initializes all the internal contexts.
  654. It can be done by user's system reset signal and implmentation of jdi_hw_reset().
  655. * @param None
  656. * @return
  657. @verbatim
  658. *JPG_RET_SUCCESS*::
  659. Operation was done successfully, which means the JPU has been reset successfully.
  660. *JPG_RET_FAILURE*::
  661. Operation was failed, which means the JPU was unable to reset.
  662. @endverbatim
  663. */
  664. JpgRet JPU_HWReset();
  665. /**
  666. * @brief This function resets JPU by using the reset register.
  667. * @param None
  668. * @return
  669. @verbatim
  670. *JPG_RET_SUCCESS*::
  671. Operation was done successfully, which means the JPU has been reset successfully.
  672. @endverbatim
  673. */
  674. JpgRet JPU_SWReset();
  675. // function for decode
  676. /**
  677. * @brief
  678. In order to decode, applications must open the decoder. By calling this
  679. function, applications can get a handle by which they can refer to a decoder
  680. instance. Because the JPU is multiple instance codec, applications need this
  681. kind of handle. Once an application gets a handle, the application must pass
  682. this handle to all subsequent decoder-related functions.
  683. * @param handle [Output] A pointer to a JpgDecHandle type variable which will
  684. specify each instance for application.
  685. * @param openParam [Input] A pointer to a JpgDecOpenParam type structure which describes
  686. required parameters for creating a new decoder instance.
  687. * @return
  688. @verbatim
  689. *JPG_RET_SUCCESS*::
  690. Operation was done successfully, which means a new decoder instance was created
  691. successfully.
  692. *JPG_RET_FAILURE*::
  693. Operation was failed, which means getting a new decoder instance was not done
  694. successfully. If there is no free instance anymore, this value will be returned
  695. in this function call.
  696. *JPG_RET_INVALID_HANDLE*::
  697. This means the given handle for current API function call was invalid (for
  698. example, not initialized yet, improper function call for the given handle,
  699. etc.).
  700. @endverbatim
  701. */
  702. JpgRet JPU_DecOpen(
  703. JpgDecHandle* handle,
  704. JpgDecOpenParam* openParam);
  705. /**
  706. * @brief
  707. When an application finished decoding a sequence and wanted to release this
  708. instance for other processing, the applicaton should close this instance. After
  709. completion of this function call, the instance referred to by handle will get
  710. free. Once an application closes an instance, the application cannot call any
  711. further decoder-specific function with the current handle before re-opening a
  712. new decoder instance with the same handle.
  713. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  714. * @return
  715. @verbatim
  716. *JPG_RET_SUCCESS*::
  717. Operation was done successfully, which means current decoder instance was closed
  718. successfully.
  719. *JPG_RET_INVALID_HANDLE*::
  720. This means the given handle for current API function call was invalid (for
  721. example, not initialized yet, improper function call for the given handle,
  722. etc.).
  723. @endverbatim
  724. */
  725. JpgRet JPU_DecClose(
  726. JpgDecHandle handle);
  727. /**
  728. * @brief
  729. @verbatim
  730. Applications must pass the address of a JpgDecInitialInfo structure, where the
  731. decoder will store information such as picture size, number of necessary frame
  732. buffers, etc. For the details, see definition of the section called
  733. JpgDecInitialInfo data structure. This function should be called once after
  734. creating a decoder instance and before starting frame decoding.
  735. It is application\'s responsibility to provide sufficient amount of bitstream to
  736. the decoder by calling JPU_DecUpdateBitstreamBuffer() so that bitstream buffer
  737. does not get empty before this function returns.
  738. @endverbatim
  739. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  740. * @param info [Output] A pointer to JpgDecInitialInfo data structure
  741. * @return
  742. @verbatim
  743. *JPG_RET_SUCCESS*::
  744. Operation was done successfully, which means required information of the stream
  745. data to be decoded was received successfully.
  746. *JPG_RET_FAILURE*::
  747. Operation was failed, which means there was an error in getting information for
  748. configuring the decoder.
  749. *JPG_RET_INVALID_PARAM*::
  750. The given argument parameter, info, was invalid, which means it has a null
  751. pointer, or given values for some member variables are improper values.
  752. *JPG_RET_INVALID_HANDLE*::
  753. This means the given handle for current API function call was invalid (for
  754. example, not initialized yet, improper function call for the given handle,
  755. etc.).
  756. @endverbatim
  757. */
  758. JpgRet JPU_DecGetInitialInfo(
  759. JpgDecHandle handle,
  760. JpgDecInitialInfo * info);
  761. /**
  762. * @brief
  763. @verbatim
  764. This function is used for registering frame buffers with the acquired
  765. information from JPU_DecGetInitialInfo(). The frame buffers pointed to by
  766. bufArray will be managed internally within the JPU. These include reference
  767. frames, reconstructed frame, etc. Applications must not change the contents of
  768. the array of frame buffers during the life time of the instance, and num must
  769. not be less than minFrameBufferCount obtained by JPU_DecGetInitialInfo().
  770. The distance between a pixel in a row and the corresponding pixel in the next
  771. row is called a stride. The value of stride must be a multiple of 8. The address
  772. of the first pixel in the second row does not necessarily coincide with the
  773. value next to the last pixel in the first row. In other words, a stride can be
  774. greater than the picture width in pixels.
  775. Applications should not set a stride value smaller than the picture width. So,
  776. for Y component, application must allocate at least a space of size (frame
  777. height stride), and Cb or Cr component, (frame height/2 stride/2),
  778. respectively.
  779. But make sure that in Cb/Cr non-interleave (separate Cb/Cr) map, the stride for
  780. luminance frame buffers should be multiple of 16 so that the stride for
  781. chrominance frame buffers can become a multiple of 8.
  782. In case of MJPEG encoding, the address of frame buffer is not necessary and only
  783. stride value is required, which will be used as source image stride.
  784. @endverbatim
  785. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  786. * @param bufArray [Input] A number of the minimum frame buffer count
  787. * @param num [Input] A number of frame buffers
  788. * @param stride [Input] A stride value of the given frame buffers
  789. * @return
  790. @verbatim
  791. *JPG_RET_SUCCESS*::
  792. Operation was done successfully, which means registering frame buffer
  793. information was done successfully.
  794. *JPG_RET_INVALID_HANDLE*::
  795. This means the given handle for current API function call was invalid (for
  796. example, not initialized yet, improper function call for the given handle,
  797. etc.).
  798. *JPG_RET_WRONG_CALL_SEQUENCE*::
  799. This means current API function call was invalid considering the allowed
  800. sequences between API functions. An application might call this function before
  801. calling JPU_DecGetInitialInfo() successfully. This function should be called
  802. after successful calling JPU_DecGetInitialInfo().
  803. *JPG_RET_INVALID_FRAME_BUFFER*::
  804. This happens when bufArray was invalid, which means bufArray was not initialized
  805. yet or not valid anymore.
  806. *JPG_RET_INSUFFICIENT_FRAME_BUFFERS*::
  807. This means the given number of frame buffers, num, was not enough for the
  808. decoder operations of the given handle. It should be greater than or equal to
  809. the value requested by JPU_DecGetInitialInfo().
  810. *JPG_RET_INVALID_STRIDE*::
  811. The given argument stride was invalid, which means it is smaller than the
  812. decoded picture width, or is not a multiple of 8 in this case.
  813. @endverbatim
  814. */
  815. JpgRet JPU_DecRegisterFrameBuffer(
  816. JpgDecHandle handle,
  817. FrameBuffer * bufArray,
  818. int num,
  819. int stride);
  820. /**
  821. * @brief
  822. @verbatim
  823. This function is used for registering frame buffers with the acquired
  824. information from JPU_DecGetInitialInfo(). The frame buffers pointed to by
  825. bufArray will be managed internally within the JPU. These include reference
  826. frames, reconstructed frame, etc. Applications must not change the contents of
  827. the array of frame buffers during the life time of the instance, and num must
  828. not be less than minFrameBufferCount obtained by JPU_DecGetInitialInfo().
  829. The distance between a pixel in a row and the corresponding pixel in the next
  830. row is called a stride. The value of stride must be a multiple of 8. The address
  831. of the first pixel in the second row does not necessarily coincide with the
  832. value next to the last pixel in the first row. In other words, a stride can be
  833. greater than the picture width in pixels.
  834. Applications should not set a stride value smaller than the picture width. So,
  835. for Y component, application must allocate at least a space of size (frame
  836. height stride), and Cb or Cr component, (frame height/2 stride/2),
  837. respectively.
  838. But make sure that in Cb/Cr non-interleave (separate Cb/Cr) map, the stride for
  839. luminance frame buffers should be multiple of 16 so that the stride for
  840. chrominance frame buffers can become a multiple of 8.
  841. In case of MJPEG encoding, the address of frame buffer is not necessary and only
  842. stride value is required, which will be used as source image stride.
  843. @endverbatim
  844. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  845. * @param prdPrt [Input] A stream buffer read pointer for the current decoder instance
  846. * @param pwrPtr [Input] A stream buffer write pointer for the current decoder instance
  847. * @param size [Input] A variable specifying the available space in bitstream buffer for the current decoder instance
  848. * @return
  849. @verbatim
  850. *JPG_RET_SUCCESS*::
  851. Operation was done successfully, which means registering frame buffer
  852. information was done successfully.
  853. *JPG_RET_INVALID_HANDLE*::
  854. This means the given handle for current API function call was invalid (for
  855. example, not initialized yet, improper function call for the given handle,
  856. etc.).
  857. *JPG_RET_WRONG_CALL_SEQUENCE*::
  858. This means current API function call was invalid considering the allowed
  859. sequences between API functions. An application might call this function before
  860. calling JPU_DecGetInitialInfo() successfully. This function should be called
  861. after successful calling JPU_DecGetInitialInfo().
  862. *JPG_RET_INVALID_FRAME_BUFFER*::
  863. This happens when bufArray was invalid, which means bufArray was not initialized
  864. yet or not valid anymore.
  865. *JPG_RET_INSUFFICIENT_FRAME_BUFFERS*::
  866. This means the given number of frame buffers, num, was not enough for the
  867. decoder operations of the given handle. It should be greater than or equal to
  868. the value requested by JPU_DecGetInitialInfo().
  869. *JPG_RET_INVALID_STRIDE*::
  870. The given argument stride was invalid, which means it is smaller than the
  871. decoded picture width, or is not a multiple of 8 in this case.
  872. @endverbatim
  873. */
  874. JpgRet JPU_DecGetBitstreamBuffer(
  875. JpgDecHandle handle,
  876. PhysicalAddress * prdPrt,
  877. PhysicalAddress * pwrPtr,
  878. int * size );
  879. /**
  880. * @brief
  881. Applications must let decoder know how much bitstream has been transferred to
  882. the address obtained from JPU_DecGetBitstreamBuffer(). By just giving the size
  883. as an argument, API automatically handles pointer wrap-around and updates the
  884. write pointer.
  885. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  886. * @param size [Input] A variable specifying the amount of bits transferred into
  887. bitstream buffer for the current decoder instance
  888. * @return
  889. @verbatim
  890. *JPG_RET_SUCCESS*::
  891. Operation was done successfully, which means putting new stream data was done
  892. successfully.
  893. *JPG_RET_INVALID_HANDLE*::
  894. This means the given handle for current API function call was invalid (for
  895. example, not initialized yet, improper function call for the given handle,
  896. etc.).
  897. @endverbatim
  898. */
  899. JpgRet JPU_DecUpdateBitstreamBuffer(
  900. JpgDecHandle handle,
  901. int size);
  902. /**
  903. * @brief
  904. This function starts decoding one frame. Returning from this function does not
  905. mean the completion of decoding one frame, and it is just that decoding one
  906. frame was initiated. Every call of this function should be matched with
  907. JPU_DecGetOutputInfo() with the same handle. Without calling a pair of these
  908. funtions, applications cannot call any other API functions except for
  909. JPU_IsBusy(), JPU_DecGetBitstreamBuffer(), and JPU_DecUpdateBitstreamBuffer().
  910. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  911. * @param param [Input] A pointer to a JpgDecParam type structure which describes picture decoding parameters for the given decoder instance
  912. * @return
  913. @verbatim
  914. *JPG_RET_SUCCESS*::
  915. Operation was done successfully, which means decoding a new frame was started
  916. successfully.
  917. NOTE: This return value does not mean that decoding a frame was completed
  918. successfully.
  919. *JPG_RET_FAIURE*::
  920. Operation was failed, which means there was an error in starting a frame.
  921. *JPG_RET_INVALID_PARAM*::
  922. This happens when param was invalid, which means param was not initialized yet
  923. or not valid anymore.
  924. *JPG_RET_INVALID_HANDLE*::
  925. This means the given handle for current API function call was invalid (for
  926. example, not initialized yet, improper function call for the given handle,
  927. etc.).
  928. *JPG_RET_FRAME_NOT_COMPLETE*::
  929. This means frame decoding operation was not completed yet, so the given API
  930. function call cannot be performed this time. A frame decoding operation should
  931. be completed by calling JPU_DecGetOutputInfo(). Even though the result of the
  932. current frame operation is not necessary, application should call
  933. JPU_DecGetOutputInfo() to proceed this function call.
  934. *JPG_RET_WRONG_CALL_SEQUENCE*::
  935. This means current API function call was invalid considering the allowed
  936. sequences between API functions. An application might call this function before
  937. successfully calling JPU_DecRegisterFrameBuffer(). This function should be
  938. called after calling JPU_ DecRegisterFrameBuffer() successfully.
  939. *JPG_RET_BIT_EMPTY*::
  940. This means the bit-stream buffer is empty. So, API requests the bit-stream data.
  941. *JPG_RET_EOS*::
  942. This means the stream ends.
  943. @endverbatim
  944. */
  945. JpgRet JPU_DecStartOneFrame(
  946. JpgDecHandle handle,
  947. JpgDecParam *param );
  948. /**
  949. * @brief
  950. Application can get the information of output of decoding. The information
  951. includes the information of a frame buffer which contains the reconstructed
  952. image. Host applications should call this function after frame decoding is
  953. finished and before starting the further processing.
  954. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  955. * @param info [Output] A pointer to a JpgDecOutputInfo type structure which
  956. describes picture decoding results for the current decoder instance.
  957. * @return
  958. @verbatim
  959. *JPG_RET_SUCCESS*::
  960. Operation was done successfully, which means receiving the output information of
  961. current frame was done successfully.
  962. *JPG_RET_INVALID_HANDLE*::
  963. This means the given handle for current API function call was invalid (for
  964. example, not initialized yet, improper function call for the given handle,
  965. etc.).
  966. *JPG_RET_WRONG_CALL_SEQUENCE*::
  967. This means current API function call was invalid considering the allowed
  968. sequences between API functions. It might happen because JPU_DecStartOneFrame()
  969. with the same handle was not called before calling this function.
  970. *JPG_RET_INVALID_PARAM*::
  971. The given argument parameter, info, was invalid, which means it has a null
  972. pointer, or given values for some member variables are improper values.
  973. @endverbatim
  974. */
  975. JpgRet JPU_DecGetOutputInfo(
  976. JpgDecHandle handle,
  977. JpgDecOutputInfo * info);
  978. /**
  979. * @brief
  980. @verbatim
  981. This function is provided to let application have a certain level of freedom for
  982. re-configuring decoder operation after creating a decoder instance. Some options
  983. which can be changed dynamically during decoding as the video sequence has been
  984. included. Some command-specific return codes are also presented.
  985. The list of valid commands can be summarized as follows:
  986. @* SET_JPG_SCALE_HOR
  987. @* SET_JPG_SCALE_VER
  988. @* ENABLE_LOGGING
  989. @* DISABLE_LOGGING
  990. @endverbatim
  991. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  992. * @param cmd [Intput] A variable specifying the given command of <<jpuapi_h_JpgCommand>>
  993. * @param parameter [Input/Output] A pointer to command-specific data structure which
  994. describes picture I/O parameters for the current decoder instance
  995. * @return
  996. @verbatim
  997. *JPG_RET_INVALID_COMMAND*::
  998. The given argument, cmd, was invalid, which means the given cmd was undefined,
  999. or not allowed in the current instance.
  1000. *JPG_RET_SUCCESS*::
  1001. Operation was done successfully.
  1002. *JPG_RET_INVALID_HANDLE*::
  1003. This means the given handle for current API function call was invalid (for
  1004. example, not initialized yet, improper function call for the given handle,
  1005. etc.).
  1006. @endverbatim
  1007. */
  1008. JpgRet JPU_DecGiveCommand(
  1009. JpgDecHandle handle,
  1010. JpgCommand cmd,
  1011. void * parameter);
  1012. /**
  1013. * @brief
  1014. This function specifies the location of read pointer in bitstream buffer.
  1015. It can also set a write pointer with same value of read pointer (addr) when updateWrPtr is not a zero value,
  1016. which allows to flush up the bitstream buffer at once.
  1017. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  1018. * @param addr [Input] Updated read or write pointer
  1019. * @param updateWrPtr [Input] A flag whether to update a write pointer or not as well as a read pointer.
  1020. * @return
  1021. @verbatim
  1022. *JPG_RET_SUCCESS*::
  1023. Operation was done successfully, which means required information of the stream data to be
  1024. decoded was received successfully.
  1025. *JPG_RET_FAIURE*::
  1026. Operation was failed, which means there was an error in starting a frame.
  1027. *JPG_RET_INVALID_HANDLE*::
  1028. This means the given handle for current API function call was invalid (for
  1029. example, not initialized yet, improper function call for the given handle,
  1030. etc.).
  1031. *JPG_RET_FRAME_NOT_COMPLETE*::
  1032. This means frame decoding operation was not completed yet, so the given API function call
  1033. cannot be performed this time. A frame decoding operation should be completed by calling
  1034. JPU_DecSetRdPtr().
  1035. @endverbatim
  1036. */
  1037. JpgRet JPU_DecSetRdPtr(
  1038. JpgDecHandle handle,
  1039. PhysicalAddress addr,
  1040. BOOL updateWrPtr);
  1041. /**
  1042. * @brief
  1043. This function is used to change the location of read pointer in bitstream buffer.
  1044. It is useful when host application decodes MJPEG with binary of every frame which is obtained from demuxer.
  1045. After frame decoding, host application can use this function which allows the given read pointer to be the base address of bitstream buffer like in line buffer mode.
  1046. * @param handle [Input] A decoder handle obtained from JPU_DecOpen()
  1047. * @param addr [Input] Updated read or write pointer
  1048. * @param updateWrPtr [Input] A flag whether to update a write pointer or not as well as a read pointer.
  1049. * @return
  1050. @verbatim
  1051. *JPG_RET_SUCCESS*::
  1052. Operation was done successfully, which means required information of the stream data to be
  1053. decoded was received successfully.
  1054. *JPG_RET_FAIURE*::
  1055. Operation was failed, which means there was an error in starting a frame.
  1056. *JPG_RET_INVALID_HANDLE*::
  1057. This means the given handle for current API function call was invalid (for
  1058. example, not initialized yet, improper function call for the given handle,
  1059. etc.).
  1060. *JPG_RET_FRAME_NOT_COMPLETE*::
  1061. This means frame decoding operation was not completed yet, so the given API function call
  1062. cannot be performed this time. A frame decoding operation should be completed by calling
  1063. JPU_DecSetRdPtr().
  1064. @endverbatim
  1065. */
  1066. JpgRet JPU_DecSetRdPtrEx(
  1067. JpgDecHandle handle,
  1068. PhysicalAddress addr,
  1069. BOOL updateWrPtr);
  1070. // function for encode
  1071. /**
  1072. * @brief
  1073. In order to start a new encoder operation, applications must open a new instance
  1074. for this encoder operation.
  1075. * @param handle [Output] A pointer to a JpgEncHandle type variable
  1076. * @param openParam [Input] A pointer to a JpgEncOpenParam type structure
  1077. * @return
  1078. @verbatim
  1079. *JPG_RET_SUCCESS*::
  1080. Operation was done successfully, which means a new encoder instance was opened
  1081. successfully.
  1082. *JPG_RET_FAILURE*::
  1083. Operation was failed, which means getting a new encoder instance was not done
  1084. successfully. If there is no free instance anymore, this value will be returned
  1085. in this function call.
  1086. *JPG_RET_INVALID_HANDLE*::
  1087. This means the given handle for current API function call was invalid (for
  1088. example, not initialized yet, improper function call for the given handle,
  1089. etc.).
  1090. @endverbatim
  1091. */
  1092. JpgRet JPU_EncOpen(
  1093. JpgEncHandle* handle,
  1094. JpgEncOpenParam* openParam);
  1095. /**
  1096. * @brief
  1097. When an application finished encoding operations and wanted to release this
  1098. instance for other processing, the application should close this instance by
  1099. calling this function. After completion of this function call, the instance
  1100. referred to by handle will get free. Once an application closes an instance, the
  1101. application cannot call any further encoder-specific function with the current
  1102. handle before re-opening a new instance with the same handle.
  1103. * @param handle [Input] An encoder handle obtained from JPU_EncOpen()
  1104. * @return
  1105. @verbatim
  1106. *JPG_RET_SUCCESS*::
  1107. Operation was done successfully. That means current encoder instance was closed
  1108. successfully.
  1109. *JPG_RET_INVALID_HANDLE*::
  1110. This means the given handle for current API function call was invalid (for
  1111. example, not initialized yet, improper function call for the given handle,
  1112. etc.).
  1113. *JPG_RET_FRAME_NOT_COMPLETE*::
  1114. This means frame decoding or encoding operation was not completed yet, so the
  1115. given API function call cannot be performed this time. A frame encoding or
  1116. decoding operation should be completed by calling JPU_EncGetOutputInfo() or
  1117. JPU_DecGetOutputInfo(). Even though the result of the current frame operation is
  1118. not necessary, applications should call JPU_EncGetOutputInfo() or
  1119. JPU_DecGetOutputInfo() to proceed this function call.
  1120. @endverbatim
  1121. */
  1122. JpgRet JPU_EncClose(
  1123. JpgEncHandle handle);
  1124. /**
  1125. * @brief
  1126. After encoding frame, applications must get bitstream from the encoder. To do
  1127. that, they must know where to get bitstream and the maximum size. Applications
  1128. can get the information by calling this function.
  1129. * @param handle [Input] A encoder handle obtained from JPU_EncOpen()
  1130. * @param prdPrt [Output] A stream buffer read pointer for the current encoder instance
  1131. * @param pwrPtr [Output] A stream buffer write pointer for the current encoder instance
  1132. * @param size [Output] A variable specifying the available space in bitstream buffer
  1133. for the current encoder instance
  1134. * @return
  1135. @verbatim
  1136. *JPG_RET_SUCCESS*::
  1137. Operation was done successfully, which means required information for encoder
  1138. stream buffer was received successfully.
  1139. *RETCODE_INVALID_PARAM*::
  1140. The given argument parameter, prdPrt, pwrPtr or size, was invalid, which means
  1141. it has a null pointer, or given values for some member variables are improper
  1142. values.
  1143. @endverbatim
  1144. */
  1145. JpgRet JPU_EncGetBitstreamBuffer(
  1146. JpgEncHandle handle,
  1147. PhysicalAddress * prdPrt,
  1148. PhysicalAddress * pwrPtr,
  1149. int * size);
  1150. /**
  1151. * @brief
  1152. Applications must let encoder know how much bitstream has been transferred from
  1153. the address obtained from JPU_EncGetBitstreamBuffer(). By just giving the size
  1154. as an argument, API automatically handles pointer wrap-around and updates the
  1155. read pointer.
  1156. * @param handle [Input] A encoder handle obtained from JPU_EncOpen()
  1157. * @param size [Input] A variable specifying the amount of bits being filled from
  1158. bitstream buffer for the current encoder instance.
  1159. If 0 is given, JPUAPI forces a read pointer and a write pointer to be wrapped around and to be updated.
  1160. * @return
  1161. @verbatim
  1162. *JPG_RET_SUCCESS*::
  1163. Operation was done successfully, which means putting new stream data was done
  1164. successfully.
  1165. *JPG_RET_INVALID_HANDLE*::
  1166. This means the given handle for current API function call was invalid (for
  1167. example, not initialized yet, improper function call for the given handle,
  1168. etc.).
  1169. @endverbatim
  1170. */
  1171. JpgRet JPU_EncUpdateBitstreamBuffer(
  1172. JpgEncHandle handle,
  1173. int size);
  1174. /**
  1175. * @brief
  1176. @verbatim
  1177. This function starts encoding one frame. Returning from this function does not
  1178. mean the completion of encoding one frame, and it is just that encoding one
  1179. frame was initiated.
  1180. Every call of this function should be matched with JPU_EncGetOutputInfo() with
  1181. the same handle. Without calling a pair of these funtions, applications cannot
  1182. call any other API functions except for JPU_IsBusy(),
  1183. JPU_EncGetBitstreamBuffer(), and JPU_EncUpdateBitstreamBuffer().
  1184. @endverbatim
  1185. * @param handle [Input] An encoder handle obtained from JPU_EncOpen()
  1186. * @param param [Input] A pointer to JpgEncParam type structure which describes
  1187. picture encoding parameters for the current encoder instance.
  1188. * @return
  1189. @verbatim
  1190. *JPG_RET_SUCCESS*::
  1191. Operation was done successfully, which means encoding a new frame was started
  1192. successfully.
  1193. NOTE: This return value does not mean that encoding a frame was completed
  1194. successfully.
  1195. *JPG_RET_INVALID_HANDLE*::
  1196. This means the given handle for current API function call was invalid (for
  1197. example, not initialized yet, improper function call for the given handle,
  1198. etc.).
  1199. *JPG_RET_FRAME_NOT_COMPLETE*::
  1200. This means frame decoding or encoding operation was not completed yet, so the
  1201. given API function call cannot be performed this time. A frame encoding or
  1202. decoding operation should be completed by calling JPU_EncGetOutputInfo() or
  1203. JPU_DecGetOutputInfo(). Even though the result of the current frame operation is
  1204. not necessary, applications should call JPU_EncGetOutputInfo() or
  1205. JPU_DecGetOutputInfo() to proceed this function call.
  1206. *JPG_RET_INVALID_PARAM*::
  1207. The given argument parameter, param, was invalid, which means it has a null
  1208. pointer, or given values for some member variables are improper values.
  1209. @endverbatim
  1210. */
  1211. JpgRet JPU_EncStartOneFrame(
  1212. JpgEncHandle handle,
  1213. JpgEncParam * param );
  1214. /**
  1215. * @brief
  1216. This function gets information of the output of encoding. Application can know
  1217. about picture type, the address and size of the generated bitstream, the number
  1218. of generated slices, the end addresses of the slices, and macroblock bit
  1219. position information. Host application should call this function after frame
  1220. encoding is finished, and before starting the further processing.
  1221. * @param handle [Input] An encoder handle obtained from JPU_EncOpen().
  1222. * @param info [Output] A pointer to a JpgEncOutputInfo type structure which
  1223. describes picture encoding results for the current encoder instance.
  1224. * @return
  1225. @verbatim
  1226. *JPG_RET_SUCCESS*::
  1227. Operation was done successfully, which means the output information of current
  1228. frame encoding was received successfully.
  1229. *JPG_RET_INVALID_HANDLE*::
  1230. This means the given handle for current API function call was invalid (for
  1231. example, not initialized yet, improper function call for the given handle,
  1232. etc.).
  1233. *JPG_RET_WRONG_CALL_SEQUENCE*::
  1234. This means current API function call was invalid considering the allowed
  1235. sequences between API functions. An application might call this function before
  1236. calling JPU_EncStartOneFrame() successfully. This function should be called
  1237. after successful calling of JPU_EncStartOneFrame().
  1238. *JPG_RET_INVALID_PARAM*::
  1239. The given argument parameter, info, was invalid, which means it has a null
  1240. pointer, or given values for some member variables are improper values.
  1241. @endverbatim
  1242. */
  1243. JpgRet JPU_EncGetOutputInfo(
  1244. JpgEncHandle handle,
  1245. JpgEncOutputInfo * info);
  1246. /**
  1247. * @brief
  1248. @verbatim
  1249. This function is provided to let application have a certain level of freedom for
  1250. re-configuring encoder operation after creating an encoder instance. Some
  1251. options which can be changed dynamically during encoding as the video sequence
  1252. has been included. Some command-specific return codes are also presented.
  1253. The list of valid commands can be summarized as follows:
  1254. @* SET_JPG_USE_STUFFING_BYTE_FF
  1255. @* ENC_JPG_GET_HEADER
  1256. @* ENABLE_LOGGING
  1257. @* DISABLE_LOGGING
  1258. @endverbatim
  1259. * @param handle [Input] An encoder handle obtained from JPU_EncOpen()
  1260. * @param cmd [Input] A variable specifying the given command of <<jpuapi_h_JpgCommand>>
  1261. * @param param [Input/Output] A pointer to command-specific data structure which
  1262. describes picture I/O parameters for the current encoder instance
  1263. * @return
  1264. @verbatim
  1265. *JPG_RET_INVALID_COMMAND*::
  1266. This means the given argument, cmd, was invalid which means the given cmd was
  1267. undefined, or not allowed in the current instance.
  1268. *JPG_RET_INVALID_PARAM*::
  1269. The given argument parameter, info, was invalid, which means it has a null
  1270. pointer, or given values for some member variables are improper values.
  1271. *JPG_RET_SUCCESS*::
  1272. Operation was done successfully, which means the given cmd was received
  1273. successfully.
  1274. *JPG_RET_INVALID_HANDLE*::
  1275. This means the given handle for current API function call was invalid (for
  1276. example, not initialized yet, improper function call for the given handle,
  1277. etc.).
  1278. @endverbatim
  1279. */
  1280. JpgRet JPU_EncGiveCommand(
  1281. JpgEncHandle handle,
  1282. JpgCommand cmd,
  1283. void * parameter);
  1284. #ifdef __cplusplus
  1285. }
  1286. #endif
  1287. #endif