123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477 |
- /* SPDX-License-Identifier: LGPL-2.1 OR BSD-3-Clause */
- /********************************************************************
- Copyright (C) 2002-2009 Xiph.org Foundation
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
- - Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- - Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in the
- documentation and/or other materials provided with the distribution.
- - Neither the name of the Xiph.org Foundation nor the names of its
- contributors may be used to endorse or promote products derived from
- this software without specific prior written permission.
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION
- OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- ********************************************************************/
- /**\mainpage
- *
- * \section intro Introduction
- *
- * This is the documentation for <tt>libtheora</tt> C API.
- * The current reference
- * implementation for <a href="http://www.theora.org/">Theora</a>, a free,
- * patent-unencumbered video codec.
- * Theora is derived from On2's VP3 codec with additional features and
- * integration with Ogg multimedia formats by
- * <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>.
- * Complete documentation of the format itself is available in
- * <a href="http://www.theora.org/doc/Theora.pdf">the Theora
- * specification</a>.
- *
- * \subsection Organization
- *
- * The functions documented here are actually subdivided into three
- * separate libraries:
- * - <tt>libtheoraenc</tt> contains the encoder interface,
- * described in \ref encfuncs.
- * - <tt>libtheoradec</tt> contains the decoder interface and
- * routines shared with the encoder.
- * You must also link to this if you link to <tt>libtheoraenc</tt>.
- * The routines in this library are described in \ref decfuncs and
- * \ref basefuncs.
- * - <tt>libtheora</tt> contains the \ref oldfuncs.
- *
- * New code should link to <tt>libtheoradec</tt> and, if using encoder
- * features, <tt>libtheoraenc</tt>. Together these two export both
- * the standard and the legacy API, so this is all that is needed by
- * any code. The older <tt>libtheora</tt> library is provided just for
- * compatibility with older build configurations.
- *
- * In general the recommended 1.x API symbols can be distinguished
- * by their <tt>th_</tt> or <tt>TH_</tt> namespace prefix.
- * The older, legacy API uses <tt>theora_</tt> or <tt>OC_</tt>
- * prefixes instead.
- */
- /**\file
- * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API.
- * You don't need to include this directly.*/
- #if !defined(_O_THEORA_CODEC_H_)
- # define _O_THEORA_CODEC_H_ (1)
- #if defined(__cplusplus)
- extern "C" {
- #endif
- #include "stdint.h"
- /**\name Return codes*/
- /*@{*/
- /**An invalid pointer was provided.*/
- #define TH_EFAULT (-1)
- /**An invalid argument was provided.*/
- #define TH_EINVAL (-10)
- /**The contents of the header were incomplete, invalid, or unexpected.*/
- #define TH_EBADHEADER (-20)
- /**The header does not belong to a Theora stream.*/
- #define TH_ENOTFORMAT (-21)
- /**The bitstream version is too high.*/
- #define TH_EVERSION (-22)
- /**The specified function is not implemented.*/
- #define TH_EIMPL (-23)
- /**There were errors in the video data packet.*/
- #define TH_EBADPACKET (-24)
- /**The decoded packet represented a dropped frame.
- The player can continue to display the current frame, as the contents of the
- decoded frame buffer have not changed.*/
- #define TH_DUPFRAME (2)
- /*@}*/
- /**The currently defined color space tags.
- * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
- * specification</a>, Chapter 4, for exact details on the meaning
- * of each of these color spaces.*/
- typedef enum{
- /**The color space was not specified at the encoder.
- It may be conveyed by an external means.*/
- TH_CS_UNSPECIFIED,
- /**A color space designed for NTSC content.*/
- TH_CS_ITU_REC_470M,
- /**A color space designed for PAL/SECAM content.*/
- TH_CS_ITU_REC_470BG,
- /**The total number of currently defined color spaces.*/
- TH_CS_NSPACES
- }th_colorspace;
- /**The currently defined pixel format tags.
- * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
- * specification</a>, Section 4.4, for details on the precise sample
- * locations.*/
- typedef enum{
- /**Chroma decimation by 2 in both the X and Y directions (4:2:0).
- The Cb and Cr chroma planes are half the width and half the
- height of the luma plane.*/
- TH_PF_420,
- /**Currently reserved.*/
- TH_PF_RSVD,
- /**Chroma decimation by 2 in the X direction (4:2:2).
- The Cb and Cr chroma planes are half the width of the luma plane, but full
- height.*/
- TH_PF_422,
- /**No chroma decimation (4:4:4).
- The Cb and Cr chroma planes are full width and full height.*/
- TH_PF_444,
- /**The total number of currently defined pixel formats.*/
- TH_PF_NFORMATS
- }th_pixel_fmt;
- /**Theora bitstream information.
- * This contains the basic playback parameters for a stream, and corresponds to
- * the initial 'info' header packet.
- * To initialize an encoder, the application fills in this structure and
- * passes it to th_encode_alloc().
- * A default encoding mode is chosen based on the values of the #quality and
- * #target_bitrate fields.
- * On decode, it is filled in by th_decode_headerin(), and then passed to
- * th_decode_alloc().
- *
- * Encoded Theora frames must be a multiple of 16 in size;
- * this is what the #frame_width and #frame_height members represent.
- * To handle arbitrary picture sizes, a crop rectangle is specified in the
- * #pic_x, #pic_y, #pic_width and #pic_height members.
- *
- * All frame buffers contain pointers to the full, padded frame.
- * However, the current encoder <em>will not</em> reference pixels outside of
- * the cropped picture region, and the application does not need to fill them
- * in.
- * The decoder <em>will</em> allocate storage for a full frame, but the
- * application <em>should not</em> rely on the padding containing sensible
- * data.
- *
- * It is also generally recommended that the offsets and sizes should still be
- * multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampled.
- * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
- * specification</a>, Section 4.4, for more details.
- *
- * Frame rate, in frames per second, is stored as a rational fraction, as is
- * the pixel aspect ratio.
- * Note that this refers to the aspect ratio of the individual pixels, not of
- * the overall frame itself.
- * The frame aspect ratio can be computed from pixel aspect ratio using the
- * image dimensions.*/
- typedef struct{
- /**\name Theora version
- * Bitstream version information.*/
- /*@{*/
- unsigned char version_major;
- unsigned char version_minor;
- unsigned char version_subminor;
- /*@}*/
- /**The encoded frame width.
- * This must be a multiple of 16, and less than 1048576.*/
- uint32_t frame_width;
- /**The encoded frame height.
- * This must be a multiple of 16, and less than 1048576.*/
- uint32_t frame_height;
- /**The displayed picture width.
- * This must be no larger than width.*/
- uint32_t pic_width;
- /**The displayed picture height.
- * This must be no larger than height.*/
- uint32_t pic_height;
- /**The X offset of the displayed picture.
- * This must be no larger than #frame_width-#pic_width or 255, whichever is
- * smaller.*/
- uint32_t pic_x;
- /**The Y offset of the displayed picture.
- * This must be no larger than #frame_height-#pic_height, and
- * #frame_height-#pic_height-#pic_y must be no larger than 255.
- * This slightly funny restriction is due to the fact that the offset is
- * specified from the top of the image for consistency with the standard
- * graphics left-handed coordinate system used throughout this API, while
- * it is stored in the encoded stream as an offset from the bottom.*/
- uint32_t pic_y;
- /**\name Frame rate
- * The frame rate, as a fraction.
- * If either is 0, the frame rate is undefined.*/
- /*@{*/
- uint32_t fps_numerator;
- uint32_t fps_denominator;
- /*@}*/
- /**\name Aspect ratio
- * The aspect ratio of the pixels.
- * If either value is zero, the aspect ratio is undefined.
- * If not specified by any external means, 1:1 should be assumed.
- * The aspect ratio of the full picture can be computed as
- * \code
- * aspect_numerator*pic_width/(aspect_denominator*pic_height).
- * \endcode */
- /*@{*/
- uint32_t aspect_numerator;
- uint32_t aspect_denominator;
- /*@}*/
- /**The color space.*/
- th_colorspace colorspace;
- /**The pixel format.*/
- th_pixel_fmt pixel_fmt;
- /**The target bit-rate in bits per second.
- If initializing an encoder with this struct, set this field to a non-zero
- value to activate CBR encoding by default.*/
- int32_t target_bitrate;
- /**The target quality level.
- Valid values range from 0 to 63, inclusive, with higher values giving
- higher quality.
- If initializing an encoder with this struct, and #target_bitrate is set
- to zero, VBR encoding at this quality will be activated by default.*/
- /*Currently this is set so that a qi of 0 corresponds to distortions of 24
- times the JND, and each increase by 16 halves that value.
- This gives us fine discrimination at low qualities, yet effective rate
- control at high qualities.
- The qi value 63 is special, however.
- For this, the highest quality, we use one half of a JND for our threshold.
- Due to the lower bounds placed on allowable quantizers in Theora, we will
- not actually be able to achieve quality this good, but this should
- provide as close to visually lossless quality as Theora is capable of.
- We could lift the quantizer restrictions without breaking VP3.1
- compatibility, but this would result in quantized coefficients that are
- too large for the current bitstream to be able to store.
- We'd have to redesign the token syntax to store these large coefficients,
- which would make transcoding complex.*/
- int32_t quality;
- /**The amount to shift to extract the last keyframe number from the granule
- * position.
- * This can be at most 31.
- * th_info_init() will set this to a default value (currently <tt>6</tt>,
- * which is good for streaming applications), but you can set it to 0 to
- * make every frame a keyframe.
- * The maximum distance between key frames is
- * <tt>1<<#keyframe_granule_shift</tt>.
- * The keyframe frequency can be more finely controlled with
- * #TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, which can also be adjusted
- * during encoding (for example, to force the next frame to be a keyframe),
- * but it cannot be set larger than the amount permitted by this field after
- * the headers have been output.*/
- int32_t keyframe_granule_shift;
- }th_info;
- /**The comment information.
- *
- * This structure holds the in-stream metadata corresponding to
- * the 'comment' header packet.
- * The comment header is meant to be used much like someone jotting a quick
- * note on the label of a video.
- * It should be a short, to the point text note that can be more than a couple
- * words, but not more than a short paragraph.
- *
- * The metadata is stored as a series of (tag, value) pairs, in
- * length-encoded string vectors.
- * The first occurrence of the '=' character delimits the tag and value.
- * A particular tag may occur more than once, and order is significant.
- * The character set encoding for the strings is always UTF-8, but the tag
- * names are limited to ASCII, and treated as case-insensitive.
- * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
- * specification</a>, Section 6.3.3 for details.
- *
- * In filling in this structure, th_decode_headerin() will null-terminate
- * the user_comment strings for safety.
- * However, the bitstream format itself treats them as 8-bit clean vectors,
- * possibly containing null characters, and so the length array should be
- * treated as their authoritative length.
- */
- typedef struct th_comment{
- /**The array of comment string vectors.*/
- char **user_comments;
- /**An array of the corresponding length of each vector, in bytes.*/
- int32_t *comment_lengths;
- /**The total number of comment strings.*/
- int32_t comments;
- /**The null-terminated vendor string.
- This identifies the software used to encode the stream.*/
- char *vendor;
- }th_comment;
- /**A single base matrix.*/
- typedef unsigned char th_quant_base[64];
- /**A set of \a qi ranges.*/
- typedef struct{
- /**The number of ranges in the set.*/
- int32_t nranges;
- /**The size of each of the #nranges ranges.
- These must sum to 63.*/
- const int32_t *sizes;
- /**#nranges <tt>+1</tt> base matrices.
- Matrices \a i and <tt>i+1</tt> form the endpoints of range \a i.*/
- const th_quant_base *base_matrices;
- }th_quant_ranges;
- /**A complete set of quantization parameters.
- The quantizer for each coefficient is calculated as:
- \code
- Q=MAX(MIN(qmin[qti][ci!=0],scale[ci!=0][qi]*base[qti][pli][qi][ci]/100),
- 1024).
- \endcode
- \a qti is the quantization type index: 0 for intra, 1 for inter.
- <tt>ci!=0</tt> is 0 for the DC coefficient and 1 for AC coefficients.
- \a qi is the quality index, ranging between 0 (low quality) and 63 (high
- quality).
- \a pli is the color plane index: 0 for Y', 1 for Cb, 2 for Cr.
- \a ci is the DCT coefficient index.
- Coefficient indices correspond to the normal 2D DCT block
- ordering--row-major with low frequencies first--\em not zig-zag order.
- Minimum quantizers are constant, and are given by:
- \code
- qmin[2][2]={{4,2},{8,4}}.
- \endcode
- Parameters that can be stored in the bitstream are as follows:
- - The two scale matrices ac_scale and dc_scale.
- \code
- scale[2][64]={dc_scale,ac_scale}.
- \endcode
- - The base matrices for each \a qi, \a qti and \a pli (up to 384 in all).
- In order to avoid storing a full 384 base matrices, only a sparse set of
- matrices are stored, and the rest are linearly interpolated.
- This is done as follows.
- For each \a qti and \a pli, a series of \a n \a qi ranges is defined.
- The size of each \a qi range can vary arbitrarily, but they must sum to
- 63.
- Then, <tt>n+1</tt> matrices are specified, one for each endpoint of the
- ranges.
- For interpolation purposes, each range's endpoints are the first \a qi
- value it contains and one past the last \a qi value it contains.
- Fractional values are rounded to the nearest integer, with ties rounded
- away from zero.
- Base matrices are stored by reference, so if the same matrices are used
- multiple times, they will only appear once in the bitstream.
- The bitstream is also capable of omitting an entire set of ranges and
- its associated matrices if they are the same as either the previous
- set (indexed in row-major order) or if the inter set is the same as the
- intra set.
- - Loop filter limit values.
- The same limits are used for the loop filter in all color planes, despite
- potentially differing levels of quantization in each.
- For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater
- than <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must
- be no greater than <tt>base[qti][pli][qi-1][ci]</tt>.
- These two conditions ensure that the actual quantizer for a given \a qti,
- \a pli, and \a ci does not increase as \a qi increases.
- This is not required by the decoder.*/
- typedef struct{
- /**The DC scaling factors.*/
- uint16_t dc_scale[64];
- /**The AC scaling factors.*/
- uint16_t ac_scale[64];
- /**The loop filter limit values.*/
- unsigned char loop_filter_limits[64];
- /**The \a qi ranges for each \a ci and \a pli.*/
- th_quant_ranges qi_ranges[2][3];
- }th_quant_info;
- /**\name Functions for manipulating header data*/
- /*@{*/
- /**Initializes a th_info structure.
- * This should be called on a freshly allocated #th_info structure before
- * attempting to use it.
- * \param _info The #th_info struct to initialize.*/
- extern void th_info_init(th_info *_info);
- /**Clears a #th_info structure.
- * This should be called on a #th_info structure after it is no longer
- * needed.
- * \param _info The #th_info struct to clear.*/
- extern void th_info_clear(th_info *_info);
- /**Initialize a #th_comment structure.
- * This should be called on a freshly allocated #th_comment structure
- * before attempting to use it.
- * \param _tc The #th_comment struct to initialize.*/
- extern void th_comment_init(th_comment *_tc);
- /**Add a comment to an initialized #th_comment structure.
- * \note Neither th_comment_add() nor th_comment_add_tag() support
- * comments containing null values, although the bitstream format does
- * support them.
- * To add such comments you will need to manipulate the #th_comment
- * structure directly.
- * \param _tc The #th_comment struct to add the comment to.
- * \param _comment Must be a null-terminated UTF-8 string containing the
- * comment in "TAG=the value" form.*/
- extern void th_comment_add(th_comment *_tc, char *_comment);
- /**Add a comment to an initialized #th_comment structure.
- * \note Neither th_comment_add() nor th_comment_add_tag() support
- * comments containing null values, although the bitstream format does
- * support them.
- * To add such comments you will need to manipulate the #th_comment
- * structure directly.
- * \param _tc The #th_comment struct to add the comment to.
- * \param _tag A null-terminated string containing the tag associated with
- * the comment.
- * \param _val The corresponding value as a null-terminated string.*/
- extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val);
- /**Look up a comment value by its tag.
- * \param _tc An initialized #th_comment structure.
- * \param _tag The tag to look up.
- * \param _count The instance of the tag.
- * The same tag can appear multiple times, each with a distinct
- * value, so an index is required to retrieve them all.
- * The order in which these values appear is significant and
- * should be preserved.
- * Use th_comment_query_count() to get the legal range for
- * the \a _count parameter.
- * \return A pointer to the queried tag's value.
- * This points directly to data in the #th_comment structure.
- * It should not be modified or freed by the application, and
- * modifications to the structure may invalidate the pointer.
- * \retval NULL If no matching tag is found.*/
- extern char *th_comment_query(th_comment *_tc,char *_tag,int32_t _count);
- /**Look up the number of instances of a tag.
- * Call this first when querying for a specific tag and then iterate over the
- * number of instances with separate calls to th_comment_query() to
- * retrieve all the values for that tag in order.
- * \param _tc An initialized #th_comment structure.
- * \param _tag The tag to look up.
- * \return The number on instances of this particular tag.*/
- extern int32_t th_comment_query_count(th_comment *_tc,char *_tag);
- /**Clears a #th_comment structure.
- * This should be called on a #th_comment structure after it is no longer
- * needed.
- * It will free all memory used by the structure members.
- * \param _tc The #th_comment struct to clear.*/
- extern void th_comment_clear(th_comment *_tc);
- /*@}*/
- /*@}*/
- #if defined(__cplusplus)
- }
- #endif
- #endif
|