jpuapi.h 57 KB

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