codec.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477
  1. /* SPDX-License-Identifier: LGPL-2.1 OR BSD-3-Clause */
  2. /********************************************************************
  3. Copyright (C) 2002-2009 Xiph.org Foundation
  4. Redistribution and use in source and binary forms, with or without
  5. modification, are permitted provided that the following conditions
  6. are met:
  7. - Redistributions of source code must retain the above copyright
  8. notice, this list of conditions and the following disclaimer.
  9. - Redistributions in binary form must reproduce the above copyright
  10. notice, this list of conditions and the following disclaimer in the
  11. documentation and/or other materials provided with the distribution.
  12. - Neither the name of the Xiph.org Foundation nor the names of its
  13. contributors may be used to endorse or promote products derived from
  14. this software without specific prior written permission.
  15. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  16. ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  17. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  18. A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION
  19. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  20. SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  21. LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22. DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23. THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24. (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  25. OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26. ********************************************************************/
  27. /**\mainpage
  28. *
  29. * \section intro Introduction
  30. *
  31. * This is the documentation for <tt>libtheora</tt> C API.
  32. * The current reference
  33. * implementation for <a href="http://www.theora.org/">Theora</a>, a free,
  34. * patent-unencumbered video codec.
  35. * Theora is derived from On2's VP3 codec with additional features and
  36. * integration with Ogg multimedia formats by
  37. * <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>.
  38. * Complete documentation of the format itself is available in
  39. * <a href="http://www.theora.org/doc/Theora.pdf">the Theora
  40. * specification</a>.
  41. *
  42. * \subsection Organization
  43. *
  44. * The functions documented here are actually subdivided into three
  45. * separate libraries:
  46. * - <tt>libtheoraenc</tt> contains the encoder interface,
  47. * described in \ref encfuncs.
  48. * - <tt>libtheoradec</tt> contains the decoder interface and
  49. * routines shared with the encoder.
  50. * You must also link to this if you link to <tt>libtheoraenc</tt>.
  51. * The routines in this library are described in \ref decfuncs and
  52. * \ref basefuncs.
  53. * - <tt>libtheora</tt> contains the \ref oldfuncs.
  54. *
  55. * New code should link to <tt>libtheoradec</tt> and, if using encoder
  56. * features, <tt>libtheoraenc</tt>. Together these two export both
  57. * the standard and the legacy API, so this is all that is needed by
  58. * any code. The older <tt>libtheora</tt> library is provided just for
  59. * compatibility with older build configurations.
  60. *
  61. * In general the recommended 1.x API symbols can be distinguished
  62. * by their <tt>th_</tt> or <tt>TH_</tt> namespace prefix.
  63. * The older, legacy API uses <tt>theora_</tt> or <tt>OC_</tt>
  64. * prefixes instead.
  65. */
  66. /**\file
  67. * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API.
  68. * You don't need to include this directly.*/
  69. #if !defined(_O_THEORA_CODEC_H_)
  70. # define _O_THEORA_CODEC_H_ (1)
  71. #if defined(__cplusplus)
  72. extern "C" {
  73. #endif
  74. #include "stdint.h"
  75. /**\name Return codes*/
  76. /*@{*/
  77. /**An invalid pointer was provided.*/
  78. #define TH_EFAULT (-1)
  79. /**An invalid argument was provided.*/
  80. #define TH_EINVAL (-10)
  81. /**The contents of the header were incomplete, invalid, or unexpected.*/
  82. #define TH_EBADHEADER (-20)
  83. /**The header does not belong to a Theora stream.*/
  84. #define TH_ENOTFORMAT (-21)
  85. /**The bitstream version is too high.*/
  86. #define TH_EVERSION (-22)
  87. /**The specified function is not implemented.*/
  88. #define TH_EIMPL (-23)
  89. /**There were errors in the video data packet.*/
  90. #define TH_EBADPACKET (-24)
  91. /**The decoded packet represented a dropped frame.
  92. The player can continue to display the current frame, as the contents of the
  93. decoded frame buffer have not changed.*/
  94. #define TH_DUPFRAME (2)
  95. /*@}*/
  96. /**The currently defined color space tags.
  97. * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
  98. * specification</a>, Chapter 4, for exact details on the meaning
  99. * of each of these color spaces.*/
  100. typedef enum{
  101. /**The color space was not specified at the encoder.
  102. It may be conveyed by an external means.*/
  103. TH_CS_UNSPECIFIED,
  104. /**A color space designed for NTSC content.*/
  105. TH_CS_ITU_REC_470M,
  106. /**A color space designed for PAL/SECAM content.*/
  107. TH_CS_ITU_REC_470BG,
  108. /**The total number of currently defined color spaces.*/
  109. TH_CS_NSPACES
  110. }th_colorspace;
  111. /**The currently defined pixel format tags.
  112. * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
  113. * specification</a>, Section 4.4, for details on the precise sample
  114. * locations.*/
  115. typedef enum{
  116. /**Chroma decimation by 2 in both the X and Y directions (4:2:0).
  117. The Cb and Cr chroma planes are half the width and half the
  118. height of the luma plane.*/
  119. TH_PF_420,
  120. /**Currently reserved.*/
  121. TH_PF_RSVD,
  122. /**Chroma decimation by 2 in the X direction (4:2:2).
  123. The Cb and Cr chroma planes are half the width of the luma plane, but full
  124. height.*/
  125. TH_PF_422,
  126. /**No chroma decimation (4:4:4).
  127. The Cb and Cr chroma planes are full width and full height.*/
  128. TH_PF_444,
  129. /**The total number of currently defined pixel formats.*/
  130. TH_PF_NFORMATS
  131. }th_pixel_fmt;
  132. /**Theora bitstream information.
  133. * This contains the basic playback parameters for a stream, and corresponds to
  134. * the initial 'info' header packet.
  135. * To initialize an encoder, the application fills in this structure and
  136. * passes it to th_encode_alloc().
  137. * A default encoding mode is chosen based on the values of the #quality and
  138. * #target_bitrate fields.
  139. * On decode, it is filled in by th_decode_headerin(), and then passed to
  140. * th_decode_alloc().
  141. *
  142. * Encoded Theora frames must be a multiple of 16 in size;
  143. * this is what the #frame_width and #frame_height members represent.
  144. * To handle arbitrary picture sizes, a crop rectangle is specified in the
  145. * #pic_x, #pic_y, #pic_width and #pic_height members.
  146. *
  147. * All frame buffers contain pointers to the full, padded frame.
  148. * However, the current encoder <em>will not</em> reference pixels outside of
  149. * the cropped picture region, and the application does not need to fill them
  150. * in.
  151. * The decoder <em>will</em> allocate storage for a full frame, but the
  152. * application <em>should not</em> rely on the padding containing sensible
  153. * data.
  154. *
  155. * It is also generally recommended that the offsets and sizes should still be
  156. * multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampled.
  157. * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
  158. * specification</a>, Section 4.4, for more details.
  159. *
  160. * Frame rate, in frames per second, is stored as a rational fraction, as is
  161. * the pixel aspect ratio.
  162. * Note that this refers to the aspect ratio of the individual pixels, not of
  163. * the overall frame itself.
  164. * The frame aspect ratio can be computed from pixel aspect ratio using the
  165. * image dimensions.*/
  166. typedef struct{
  167. /**\name Theora version
  168. * Bitstream version information.*/
  169. /*@{*/
  170. unsigned char version_major;
  171. unsigned char version_minor;
  172. unsigned char version_subminor;
  173. /*@}*/
  174. /**The encoded frame width.
  175. * This must be a multiple of 16, and less than 1048576.*/
  176. uint32_t frame_width;
  177. /**The encoded frame height.
  178. * This must be a multiple of 16, and less than 1048576.*/
  179. uint32_t frame_height;
  180. /**The displayed picture width.
  181. * This must be no larger than width.*/
  182. uint32_t pic_width;
  183. /**The displayed picture height.
  184. * This must be no larger than height.*/
  185. uint32_t pic_height;
  186. /**The X offset of the displayed picture.
  187. * This must be no larger than #frame_width-#pic_width or 255, whichever is
  188. * smaller.*/
  189. uint32_t pic_x;
  190. /**The Y offset of the displayed picture.
  191. * This must be no larger than #frame_height-#pic_height, and
  192. * #frame_height-#pic_height-#pic_y must be no larger than 255.
  193. * This slightly funny restriction is due to the fact that the offset is
  194. * specified from the top of the image for consistency with the standard
  195. * graphics left-handed coordinate system used throughout this API, while
  196. * it is stored in the encoded stream as an offset from the bottom.*/
  197. uint32_t pic_y;
  198. /**\name Frame rate
  199. * The frame rate, as a fraction.
  200. * If either is 0, the frame rate is undefined.*/
  201. /*@{*/
  202. uint32_t fps_numerator;
  203. uint32_t fps_denominator;
  204. /*@}*/
  205. /**\name Aspect ratio
  206. * The aspect ratio of the pixels.
  207. * If either value is zero, the aspect ratio is undefined.
  208. * If not specified by any external means, 1:1 should be assumed.
  209. * The aspect ratio of the full picture can be computed as
  210. * \code
  211. * aspect_numerator*pic_width/(aspect_denominator*pic_height).
  212. * \endcode */
  213. /*@{*/
  214. uint32_t aspect_numerator;
  215. uint32_t aspect_denominator;
  216. /*@}*/
  217. /**The color space.*/
  218. th_colorspace colorspace;
  219. /**The pixel format.*/
  220. th_pixel_fmt pixel_fmt;
  221. /**The target bit-rate in bits per second.
  222. If initializing an encoder with this struct, set this field to a non-zero
  223. value to activate CBR encoding by default.*/
  224. int32_t target_bitrate;
  225. /**The target quality level.
  226. Valid values range from 0 to 63, inclusive, with higher values giving
  227. higher quality.
  228. If initializing an encoder with this struct, and #target_bitrate is set
  229. to zero, VBR encoding at this quality will be activated by default.*/
  230. /*Currently this is set so that a qi of 0 corresponds to distortions of 24
  231. times the JND, and each increase by 16 halves that value.
  232. This gives us fine discrimination at low qualities, yet effective rate
  233. control at high qualities.
  234. The qi value 63 is special, however.
  235. For this, the highest quality, we use one half of a JND for our threshold.
  236. Due to the lower bounds placed on allowable quantizers in Theora, we will
  237. not actually be able to achieve quality this good, but this should
  238. provide as close to visually lossless quality as Theora is capable of.
  239. We could lift the quantizer restrictions without breaking VP3.1
  240. compatibility, but this would result in quantized coefficients that are
  241. too large for the current bitstream to be able to store.
  242. We'd have to redesign the token syntax to store these large coefficients,
  243. which would make transcoding complex.*/
  244. int32_t quality;
  245. /**The amount to shift to extract the last keyframe number from the granule
  246. * position.
  247. * This can be at most 31.
  248. * th_info_init() will set this to a default value (currently <tt>6</tt>,
  249. * which is good for streaming applications), but you can set it to 0 to
  250. * make every frame a keyframe.
  251. * The maximum distance between key frames is
  252. * <tt>1<<#keyframe_granule_shift</tt>.
  253. * The keyframe frequency can be more finely controlled with
  254. * #TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, which can also be adjusted
  255. * during encoding (for example, to force the next frame to be a keyframe),
  256. * but it cannot be set larger than the amount permitted by this field after
  257. * the headers have been output.*/
  258. int32_t keyframe_granule_shift;
  259. }th_info;
  260. /**The comment information.
  261. *
  262. * This structure holds the in-stream metadata corresponding to
  263. * the 'comment' header packet.
  264. * The comment header is meant to be used much like someone jotting a quick
  265. * note on the label of a video.
  266. * It should be a short, to the point text note that can be more than a couple
  267. * words, but not more than a short paragraph.
  268. *
  269. * The metadata is stored as a series of (tag, value) pairs, in
  270. * length-encoded string vectors.
  271. * The first occurrence of the '=' character delimits the tag and value.
  272. * A particular tag may occur more than once, and order is significant.
  273. * The character set encoding for the strings is always UTF-8, but the tag
  274. * names are limited to ASCII, and treated as case-insensitive.
  275. * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
  276. * specification</a>, Section 6.3.3 for details.
  277. *
  278. * In filling in this structure, th_decode_headerin() will null-terminate
  279. * the user_comment strings for safety.
  280. * However, the bitstream format itself treats them as 8-bit clean vectors,
  281. * possibly containing null characters, and so the length array should be
  282. * treated as their authoritative length.
  283. */
  284. typedef struct th_comment{
  285. /**The array of comment string vectors.*/
  286. char **user_comments;
  287. /**An array of the corresponding length of each vector, in bytes.*/
  288. int32_t *comment_lengths;
  289. /**The total number of comment strings.*/
  290. int32_t comments;
  291. /**The null-terminated vendor string.
  292. This identifies the software used to encode the stream.*/
  293. char *vendor;
  294. }th_comment;
  295. /**A single base matrix.*/
  296. typedef unsigned char th_quant_base[64];
  297. /**A set of \a qi ranges.*/
  298. typedef struct{
  299. /**The number of ranges in the set.*/
  300. int32_t nranges;
  301. /**The size of each of the #nranges ranges.
  302. These must sum to 63.*/
  303. const int32_t *sizes;
  304. /**#nranges <tt>+1</tt> base matrices.
  305. Matrices \a i and <tt>i+1</tt> form the endpoints of range \a i.*/
  306. const th_quant_base *base_matrices;
  307. }th_quant_ranges;
  308. /**A complete set of quantization parameters.
  309. The quantizer for each coefficient is calculated as:
  310. \code
  311. Q=MAX(MIN(qmin[qti][ci!=0],scale[ci!=0][qi]*base[qti][pli][qi][ci]/100),
  312. 1024).
  313. \endcode
  314. \a qti is the quantization type index: 0 for intra, 1 for inter.
  315. <tt>ci!=0</tt> is 0 for the DC coefficient and 1 for AC coefficients.
  316. \a qi is the quality index, ranging between 0 (low quality) and 63 (high
  317. quality).
  318. \a pli is the color plane index: 0 for Y', 1 for Cb, 2 for Cr.
  319. \a ci is the DCT coefficient index.
  320. Coefficient indices correspond to the normal 2D DCT block
  321. ordering--row-major with low frequencies first--\em not zig-zag order.
  322. Minimum quantizers are constant, and are given by:
  323. \code
  324. qmin[2][2]={{4,2},{8,4}}.
  325. \endcode
  326. Parameters that can be stored in the bitstream are as follows:
  327. - The two scale matrices ac_scale and dc_scale.
  328. \code
  329. scale[2][64]={dc_scale,ac_scale}.
  330. \endcode
  331. - The base matrices for each \a qi, \a qti and \a pli (up to 384 in all).
  332. In order to avoid storing a full 384 base matrices, only a sparse set of
  333. matrices are stored, and the rest are linearly interpolated.
  334. This is done as follows.
  335. For each \a qti and \a pli, a series of \a n \a qi ranges is defined.
  336. The size of each \a qi range can vary arbitrarily, but they must sum to
  337. 63.
  338. Then, <tt>n+1</tt> matrices are specified, one for each endpoint of the
  339. ranges.
  340. For interpolation purposes, each range's endpoints are the first \a qi
  341. value it contains and one past the last \a qi value it contains.
  342. Fractional values are rounded to the nearest integer, with ties rounded
  343. away from zero.
  344. Base matrices are stored by reference, so if the same matrices are used
  345. multiple times, they will only appear once in the bitstream.
  346. The bitstream is also capable of omitting an entire set of ranges and
  347. its associated matrices if they are the same as either the previous
  348. set (indexed in row-major order) or if the inter set is the same as the
  349. intra set.
  350. - Loop filter limit values.
  351. The same limits are used for the loop filter in all color planes, despite
  352. potentially differing levels of quantization in each.
  353. For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater
  354. than <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must
  355. be no greater than <tt>base[qti][pli][qi-1][ci]</tt>.
  356. These two conditions ensure that the actual quantizer for a given \a qti,
  357. \a pli, and \a ci does not increase as \a qi increases.
  358. This is not required by the decoder.*/
  359. typedef struct{
  360. /**The DC scaling factors.*/
  361. uint16_t dc_scale[64];
  362. /**The AC scaling factors.*/
  363. uint16_t ac_scale[64];
  364. /**The loop filter limit values.*/
  365. unsigned char loop_filter_limits[64];
  366. /**The \a qi ranges for each \a ci and \a pli.*/
  367. th_quant_ranges qi_ranges[2][3];
  368. }th_quant_info;
  369. /**\name Functions for manipulating header data*/
  370. /*@{*/
  371. /**Initializes a th_info structure.
  372. * This should be called on a freshly allocated #th_info structure before
  373. * attempting to use it.
  374. * \param _info The #th_info struct to initialize.*/
  375. extern void th_info_init(th_info *_info);
  376. /**Clears a #th_info structure.
  377. * This should be called on a #th_info structure after it is no longer
  378. * needed.
  379. * \param _info The #th_info struct to clear.*/
  380. extern void th_info_clear(th_info *_info);
  381. /**Initialize a #th_comment structure.
  382. * This should be called on a freshly allocated #th_comment structure
  383. * before attempting to use it.
  384. * \param _tc The #th_comment struct to initialize.*/
  385. extern void th_comment_init(th_comment *_tc);
  386. /**Add a comment to an initialized #th_comment structure.
  387. * \note Neither th_comment_add() nor th_comment_add_tag() support
  388. * comments containing null values, although the bitstream format does
  389. * support them.
  390. * To add such comments you will need to manipulate the #th_comment
  391. * structure directly.
  392. * \param _tc The #th_comment struct to add the comment to.
  393. * \param _comment Must be a null-terminated UTF-8 string containing the
  394. * comment in "TAG=the value" form.*/
  395. extern void th_comment_add(th_comment *_tc, char *_comment);
  396. /**Add a comment to an initialized #th_comment structure.
  397. * \note Neither th_comment_add() nor th_comment_add_tag() support
  398. * comments containing null values, although the bitstream format does
  399. * support them.
  400. * To add such comments you will need to manipulate the #th_comment
  401. * structure directly.
  402. * \param _tc The #th_comment struct to add the comment to.
  403. * \param _tag A null-terminated string containing the tag associated with
  404. * the comment.
  405. * \param _val The corresponding value as a null-terminated string.*/
  406. extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val);
  407. /**Look up a comment value by its tag.
  408. * \param _tc An initialized #th_comment structure.
  409. * \param _tag The tag to look up.
  410. * \param _count The instance of the tag.
  411. * The same tag can appear multiple times, each with a distinct
  412. * value, so an index is required to retrieve them all.
  413. * The order in which these values appear is significant and
  414. * should be preserved.
  415. * Use th_comment_query_count() to get the legal range for
  416. * the \a _count parameter.
  417. * \return A pointer to the queried tag's value.
  418. * This points directly to data in the #th_comment structure.
  419. * It should not be modified or freed by the application, and
  420. * modifications to the structure may invalidate the pointer.
  421. * \retval NULL If no matching tag is found.*/
  422. extern char *th_comment_query(th_comment *_tc,char *_tag,int32_t _count);
  423. /**Look up the number of instances of a tag.
  424. * Call this first when querying for a specific tag and then iterate over the
  425. * number of instances with separate calls to th_comment_query() to
  426. * retrieve all the values for that tag in order.
  427. * \param _tc An initialized #th_comment structure.
  428. * \param _tag The tag to look up.
  429. * \return The number on instances of this particular tag.*/
  430. extern int32_t th_comment_query_count(th_comment *_tc,char *_tag);
  431. /**Clears a #th_comment structure.
  432. * This should be called on a #th_comment structure after it is no longer
  433. * needed.
  434. * It will free all memory used by the structure members.
  435. * \param _tc The #th_comment struct to clear.*/
  436. extern void th_comment_clear(th_comment *_tc);
  437. /*@}*/
  438. /*@}*/
  439. #if defined(__cplusplus)
  440. }
  441. #endif
  442. #endif