codec.h   codec.h 
/******************************************************************** /********************************************************************
* * * *
* THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. * * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
* USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
* GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
* IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
* * * *
* THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2007 * * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
* by the Xiph.Org Foundation http://www.xiph.org/ * * by the Xiph.Org Foundation http://www.xiph.org/ *
* * * *
******************************************************************** ********************************************************************
function: function:
last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $ last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
********************************************************************/ ********************************************************************/
/**\mainpage /**\mainpage
* *
* \section intro Introduction * \section intro Introduction
* *
* This is the documentation for <tt>libtheora</tt> C API. * This is the documentation for <tt>libtheora</tt> C API.
* The current reference * The current reference
* implementation for <a href="http://www.theora.org/">Theora</a>, a free, * implementation for <a href="http://www.theora.org/">Theora</a>, a free,
* patent-unencumbered video codec. * patent-unencumbered video codec.
* Theora is derived from On2's VP3 codec with additional features and * Theora is derived from On2's VP3 codec with additional features and
* integration for Ogg multimedia formats by * integration with Ogg multimedia formats by
* <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>. * <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>.
* Complete documentation of the format itself is available in * Complete documentation of the format itself is available in
* <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora * <a href="http://www.theora.org/doc/Theora.pdf">the Theora
* specification</a>. * specification</a>.
* *
* \subsection Organization * \subsection Organization
* *
* The functions documented here are actually subdivided into three * The functions documented here are actually subdivided into three
* separate libraries: * separate libraries:
* - <tt>libtheoraenc</tt> contains the encoder interface, * - <tt>libtheoraenc</tt> contains the encoder interface,
* described in \ref encfuncs. * described in \ref encfuncs.
* - <tt>libtheoradec</tt> contains the decoder interface and * - <tt>libtheoradec</tt> contains the decoder interface and
* routines shared with the encoder. * routines shared with the encoder.
skipping to change at line 93 skipping to change at line 93
#define TH_EIMPL (-23) #define TH_EIMPL (-23)
/**There were errors in the video data packet.*/ /**There were errors in the video data packet.*/
#define TH_EBADPACKET (-24) #define TH_EBADPACKET (-24)
/**The decoded packet represented a dropped frame. /**The decoded packet represented a dropped frame.
The player can continue to display the current frame, as the contents of the The player can continue to display the current frame, as the contents of the
decoded frame buffer have not changed.*/ decoded frame buffer have not changed.*/
#define TH_DUPFRAME (1) #define TH_DUPFRAME (1)
/*@}*/ /*@}*/
/**The currently defined color space tags. /**The currently defined color space tags.
* See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
* specification</a>, Chapter 4, for exact details on the meaning of each * specification</a>, Chapter 4, for exact details on the meaning
of * of each of these color spaces.*/
* these color spaces.*/
typedef enum{ typedef enum{
/**The color space was not specified at the encoder. /**The color space was not specified at the encoder.
It may be conveyed by an external means.*/ It may be conveyed by an external means.*/
TH_CS_UNSPECIFIED, TH_CS_UNSPECIFIED,
/**A color space designed for NTSC content.*/ /**A color space designed for NTSC content.*/
TH_CS_ITU_REC_470M, TH_CS_ITU_REC_470M,
/**A color space designed for PAL/SECAM content.*/ /**A color space designed for PAL/SECAM content.*/
TH_CS_ITU_REC_470BG, TH_CS_ITU_REC_470BG,
/**The total number of currently defined color spaces.*/ /**The total number of currently defined color spaces.*/
TH_CS_NSPACES TH_CS_NSPACES
}th_colorspace; }th_colorspace;
/**The currently defined pixel format tags. /**The currently defined pixel format tags.
* See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
* specification</a>, Section 4.4, for details on the precise sample * specification</a>, Section 4.4, for details on the precise sample
* locations.*/ * locations.*/
typedef enum{ typedef enum{
/**Chroma decimation by 2 in both the X and Y directions (4:2:0). /**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 Cb and Cr chroma planes are half the width and half the
the height of the luma plane.*/
luma plane.*/
TH_PF_420, TH_PF_420,
/**Currently reserved.*/ /**Currently reserved.*/
TH_PF_RSVD, TH_PF_RSVD,
/**Chroma decimation by 2 in the X direction (4:2:2). /**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 The Cb and Cr chroma planes are half the width of the luma plane, but full
height.*/ height.*/
TH_PF_422, TH_PF_422,
/**No chroma decimation (4:4:4). /**No chroma decimation (4:4:4).
The Cb and Cr chroma planes are full width and full height.*/ The Cb and Cr chroma planes are full width and full height.*/
TH_PF_444, TH_PF_444,
/**The total number of currently defined pixel formats.*/ /**The total number of currently defined pixel formats.*/
TH_PF_NFORMATS TH_PF_NFORMATS
}th_pixel_fmt; }th_pixel_fmt;
/**A buffer for a single color plane in an uncompressed image. /**A buffer for a single color plane in an uncompressed image.
* This contains the image data in a left-to-right, top-down format. * This contains the image data in a left-to-right, top-down format.
* Each row of pixels is stored contiguously in memory, but successive rows * Each row of pixels is stored contiguously in memory, but successive
* need not be. * rows need not be.
* Use \a stride to compute the offset of the next row. * Use \a stride to compute the offset of the next row.
* The encoder accepts both positive \a stride values (top-down in memory) * The encoder accepts both positive \a stride values (top-down in memory)
and * and negative (bottom-up in memory).
* negative (bottom-up in memory).
* The decoder currently always generates images with positive strides.*/ * The decoder currently always generates images with positive strides.*/
typedef struct{ typedef struct{
/**The width of this plane.*/ /**The width of this plane.*/
int width; int width;
/**The height of this plane.*/ /**The height of this plane.*/
int height; int height;
/**The offset in bytes between successive rows.*/ /**The offset in bytes between successive rows.*/
int stride; int stride;
/**A pointer to the beginning of the first row.*/ /**A pointer to the beginning of the first row.*/
unsigned char *data; unsigned char *data;
}th_img_plane; }th_img_plane;
/**A complete image buffer for an uncompressed frame. /**A complete image buffer for an uncompressed frame.
* The chroma planes may be decimated by a factor of two in either directio * The chroma planes may be decimated by a factor of two in either
n, * direction, as indicated by th_info#pixel_fmt.
* as indicated by th_info#pixel_fmt.
* The width and height of the Y' plane must be multiples of 16. * The width and height of the Y' plane must be multiples of 16.
* They may need to be cropped for display, using the rectangle specified b * They may need to be cropped for display, using the rectangle
y * specified by th_info#pic_x, th_info#pic_y, th_info#pic_width,
* th_info#pic_x, th_info#pic_y, th_info#pic_width, and * and th_info#pic_height.
* th_info#pic_height.
* All samples are 8 bits. * All samples are 8 bits.
* \note The term YUV often used to describe a colorspace is ambiguous. * \note The term YUV often used to describe a colorspace is ambiguous.
* The exact parameters of the RGB to YUV conversion process aside, in many * The exact parameters of the RGB to YUV conversion process aside, in
* contexts the U and V channels actually have opposite meanings. * many contexts the U and V channels actually have opposite meanings.
* To avoid this confusion, we are explicit: the name of the color channels * To avoid this confusion, we are explicit: the name of the color
are * channels are Y'CbCr, and they appear in that order, always.
* Y'CbCr, and they appear in that order, always.
* The prime symbol denotes that the Y channel is non-linear. * The prime symbol denotes that the Y channel is non-linear.
* Cb and Cr stand for "Chroma blue" and "Chroma red", respectively.*/ * Cb and Cr stand for "Chroma blue" and "Chroma red", respectively.*/
typedef th_img_plane th_ycbcr_buffer[3]; typedef th_img_plane th_ycbcr_buffer[3];
/**Theora bitstream information. /**Theora bitstream information.
* This contains the basic playback parameters for a stream, and correspond s to * This contains the basic playback parameters for a stream, and correspond s to
* the initial 'info' header packet. * the initial 'info' header packet.
* To initialize an encoder, the application fills in this structure and * To initialize an encoder, the application fills in this structure and
* passes it to th_encode_alloc(). * passes it to th_encode_alloc().
* A default encoding mode is chosen based on the values of the #quality an d * A default encoding mode is chosen based on the values of the #quality an d
skipping to change at line 191 skipping to change at line 191
* All frame buffers contain pointers to the full, padded frame. * All frame buffers contain pointers to the full, padded frame.
* However, the current encoder <em>will not</em> reference pixels outside of * However, the current encoder <em>will not</em> reference pixels outside of
* the cropped picture region, and the application does not need to fill t hem * the cropped picture region, and the application does not need to fill t hem
* in. * in.
* The decoder <em>will</em> allocate storage for a full frame, but the * The decoder <em>will</em> allocate storage for a full frame, but the
* application <em>should not</em> rely on the padding containing sensible * application <em>should not</em> rely on the padding containing sensible
* data. * data.
* *
* It is also generally recommended that the offsets and sizes should still be * 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-sampl ed. * multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampl ed.
* See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
* specification</a>, Section 4.4, for more details. * specification</a>, Section 4.4, for more details.
* *
* Frame rate, in frames per second, is stored as a rational fraction, as i s * Frame rate, in frames per second, is stored as a rational fraction, as i s
* the pixel aspect ratio. * the pixel aspect ratio.
* Note that this refers to the aspect ratio of the individual pixels, not of * Note that this refers to the aspect ratio of the individual pixels, not of
* the overall frame itself. * the overall frame itself.
* The frame aspect ratio can be computed from pixel aspect ratio using the * The frame aspect ratio can be computed from pixel aspect ratio using the
* image dimensions.*/ * image dimensions.*/
typedef struct{ typedef struct{
/**\name Theora version /**\name Theora version
skipping to change at line 229 skipping to change at line 229
ogg_uint32_t pic_height; ogg_uint32_t pic_height;
/**The X offset of the displayed picture. /**The X offset of the displayed picture.
* This must be no larger than #frame_width-#pic_width or 255, whichever is * This must be no larger than #frame_width-#pic_width or 255, whichever is
* smaller.*/ * smaller.*/
ogg_uint32_t pic_x; ogg_uint32_t pic_x;
/**The Y offset of the displayed picture. /**The Y offset of the displayed picture.
* This must be no larger than #frame_height-#pic_height, and * This must be no larger than #frame_height-#pic_height, and
* #frame_height-#pic_height-#pic_y must be no larger than 255. * #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 * 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 * specified from the top of the image for consistency with the standard
* graphics left-handed coordinate system used throughout this API, whil * graphics left-handed coordinate system used throughout this API, whil
e it e
* is stored in the encoded stream as an offset from the bottom.*/ * it is stored in the encoded stream as an offset from the bottom.*/
ogg_uint32_t pic_y; ogg_uint32_t pic_y;
/**\name Frame rate /**\name Frame rate
* The frame rate, as a fraction. * The frame rate, as a fraction.
* If either is 0, the frame rate is undefined.*/ * If either is 0, the frame rate is undefined.*/
/*@{*/ /*@{*/
ogg_uint32_t fps_numerator; ogg_uint32_t fps_numerator;
ogg_uint32_t fps_denominator; ogg_uint32_t fps_denominator;
/*@}*/ /*@}*/
/**\name Aspect ratio /**\name Aspect ratio
* The aspect ratio of the pixels. * The aspect ratio of the pixels.
skipping to change at line 258 skipping to change at line 258
ogg_uint32_t aspect_numerator; ogg_uint32_t aspect_numerator;
ogg_uint32_t aspect_denominator; ogg_uint32_t aspect_denominator;
/*@}*/ /*@}*/
/**The color space.*/ /**The color space.*/
th_colorspace colorspace; th_colorspace colorspace;
/**The pixel format.*/ /**The pixel format.*/
th_pixel_fmt pixel_fmt; th_pixel_fmt pixel_fmt;
/**The target bit-rate in bits per second. /**The target bit-rate in bits per second.
If initializing an encoder with this struct, set this field to a non-z ero If initializing an encoder with this struct, set this field to a non-z ero
value to activate CBR encoding by default.*/ value to activate CBR encoding by default.*/
/*TODO: Current encoder does not support CBR mode, or anything like it.
We also don't really know what nominal rate each quality level
corresponds to yet.*/
int target_bitrate; int target_bitrate;
/**The target quality level. /**The target quality level.
Valid values range from 0 to 63, inclusive, with higher values giving Valid values range from 0 to 63, inclusive, with higher values giving
higher quality. higher quality.
If initializing an encoder with this struct, and #target_bitrate is se t If initializing an encoder with this struct, and #target_bitrate is se t
to zero, VBR encoding at this quality will be activated by default.*/ 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 2 4 /*Currently this is set so that a qi of 0 corresponds to distortions of 2 4
times the JND, and each increase by 16 halves that value. times the JND, and each increase by 16 halves that value.
This gives us fine discrimination at low qualities, yet effective rate This gives us fine discrimination at low qualities, yet effective rate
control at high qualities. control at high qualities.
skipping to change at line 313 skipping to change at line 310
* note on the label of a video. * note on the label of a video.
* It should be a short, to the point text note that can be more than a cou ple * It should be a short, to the point text note that can be more than a cou ple
* words, but not more than a short paragraph. * words, but not more than a short paragraph.
* *
* The metadata is stored as a series of (tag, value) pairs, in * The metadata is stored as a series of (tag, value) pairs, in
* length-encoded string vectors. * length-encoded string vectors.
* The first occurrence of the '=' character delimits the tag and value. * The first occurrence of the '=' character delimits the tag and value.
* A particular tag may occur more than once, and order is significant. * 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 * The character set encoding for the strings is always UTF-8, but the tag
* names are limited to ASCII, and treated as case-insensitive. * names are limited to ASCII, and treated as case-insensitive.
* See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
* specification</a>, Section 6.3.3 for details. * specification</a>, Section 6.3.3 for details.
* *
* In filling in this structure, th_decode_headerin() will null-terminate * In filling in this structure, th_decode_headerin() will null-terminate
* the user_comment strings for safety. * the user_comment strings for safety.
* However, the bitstream format itself treats them as 8-bit clean vectors, * However, the bitstream format itself treats them as 8-bit clean vectors,
* possibly containing null characters, and so the length array should be * possibly containing null characters, and so the length array should be
* treated as their authoritative length. * treated as their authoritative length.
*/ */
typedef struct th_comment{ typedef struct th_comment{
/**The array of comment string vectors.*/ /**The array of comment string vectors.*/
 End of changes. 15 change blocks. 
36 lines changed or deleted 27 lines changed or added


 theora.h   theora.h 
/******************************************************************** /********************************************************************
* * * *
* THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. * * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
* USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
* GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
* IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
* * * *
* THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2007 * * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
* by the Xiph.Org Foundation http://www.xiph.org/ * * by the Xiph.Org Foundation http://www.xiph.org/ *
* * * *
******************************************************************** ********************************************************************
function: function:
last mod: $Id: theora.h,v 1.17 2003/12/06 18:06:19 arc Exp $ last mod: $Id: theora.h,v 1.17 2003/12/06 18:06:19 arc Exp $
********************************************************************/ ********************************************************************/
#ifndef _O_THEORA_H_ #ifndef _O_THEORA_H_
skipping to change at line 30 skipping to change at line 30
#ifdef __cplusplus #ifdef __cplusplus
extern "C" extern "C"
{ {
#endif /* __cplusplus */ #endif /* __cplusplus */
#include <stddef.h> /* for size_t */ #include <stddef.h> /* for size_t */
#include <ogg/ogg.h> #include <ogg/ogg.h>
/** \defgroup oldfuncs Legacy pre-1.0 C API */ /** \file
/* @{ */ * The libtheora pre-1.0 legacy C API.
*
/** \mainpage * \ingroup oldfuncs
* *
* \section intro Introduction * \section intro Introduction
* *
* This is the documentation for the libtheora legacy C API, declared in * This is the documentation for the libtheora legacy C API, declared in
* the theora.h header, which describes the old interface used before * the theora.h header, which describes the old interface used before
* the 1.0 release. This API was widely deployed for several years and * the 1.0 release. This API was widely deployed for several years and
* remains supported, but for new code we recommend the cleaner API * remains supported, but for new code we recommend the cleaner API
* declared in theoradec.h and theoraenc.h. * declared in theoradec.h and theoraenc.h.
* *
* libtheora is the reference implementation for * libtheora is the reference implementation for
* <a href="http://www.theora.org/">Theora</a>, a free video codec. * <a href="http://www.theora.org/">Theora</a>, a free video codec.
* Theora is derived from On2's VP3 codec with improved integration for * Theora is derived from On2's VP3 codec with improved integration with
* Ogg multimedia formats by <a href="http://www.xiph.org/">Xiph.Org</a>. * Ogg multimedia formats by <a href="http://www.xiph.org/">Xiph.Org</a>.
* *
* \section overview Overview * \section overview Overview
* *
* This library will both decode and encode theora packets to/from raw YUV * This library will both decode and encode theora packets to/from raw YUV
* frames. In either case, the packets will most likely either come from o r * frames. In either case, the packets will most likely either come from o r
* need to be embedded in an Ogg stream. Use * need to be embedded in an Ogg stream. Use
* <a href="http://xiph.org/ogg/">libogg</a> or * <a href="http://xiph.org/ogg/">libogg</a> or
* <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a> * <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a>
* to extract/package these packets. * to extract/package these packets.
skipping to change at line 117 skipping to change at line 117
* - test the first (only) packet on that page to determine if it is a the ora * - test the first (only) packet on that page to determine if it is a the ora
* packet; * packet;
* - once you have found a theora b_o_s page then use the retrieved serial _no * - once you have found a theora b_o_s page then use the retrieved serial _no
* to identify future packets belonging to the same theora stream. * to identify future packets belonging to the same theora stream.
* *
* Note that you \e cannot use theora_packet_isheader() to determine if a * Note that you \e cannot use theora_packet_isheader() to determine if a
* packet is a theora packet or not, as this function does not perform any * packet is a theora packet or not, as this function does not perform any
* checking beyond whether a header bit is present. Instead, use the * checking beyond whether a header bit is present. Instead, use the
* theora_decode_header() function and check the return value; or examine t he * theora_decode_header() function and check the return value; or examine t he
* header bytes at the beginning of the Ogg page. * header bytes at the beginning of the Ogg page.
*
* \subsection example Example Decoder
*
* See <a href="http://svn.xiph.org/trunk/theora/examples/dump_video.c">
* examples/dump_video.c</a> for a simple decoder implementation.
*
* \section encoding Encoding Process
*
* See <a href="http://svn.xiph.org/trunk/theora/examples/encoder_example.c
">
* examples/encoder_example.c</a> for a simple encoder implementation.
*/ */
/** \file /** \defgroup oldfuncs Legacy pre-1.0 C API */
* The libtheora pre-1.0 legacy C API. /* @{ */
*/
/** /**
* A YUV buffer for passing uncompressed frames to and from the codec. * A YUV buffer for passing uncompressed frames to and from the codec.
* This holds a Y'CbCr frame in planar format. The CbCr planes can be * This holds a Y'CbCr frame in planar format. The CbCr planes can be
* subsampled and have their own separate dimensions and row stride * subsampled and have their own separate dimensions and row stride
* offsets. Note that the strides may be negative in some * offsets. Note that the strides may be negative in some
* configurations. For theora the width and height of the largest plane * configurations. For theora the width and height of the largest plane
* must be a multiple of 16. The actual meaningful picture size and * must be a multiple of 16. The actual meaningful picture size and
* offset are stored in the theora_info structure; frames returned by * offset are stored in the theora_info structure; frames returned by
* the decoder may need to be cropped for display. * the decoder may need to be cropped for display.
skipping to change at line 294 skipping to change at line 283
*/ */
typedef struct theora_comment{ typedef struct theora_comment{
char **user_comments; /**< An array of comment string vectors */ char **user_comments; /**< An array of comment string vectors */
int *comment_lengths; /**< An array of corresponding string vecto r lengths in bytes */ int *comment_lengths; /**< An array of corresponding string vecto r lengths in bytes */
int comments; /**< The total number of comment string vec tors */ int comments; /**< The total number of comment string vec tors */
char *vendor; /**< The vendor string identifying the enco der, null terminated */ char *vendor; /**< The vendor string identifying the enco der, null terminated */
} theora_comment; } theora_comment;
/**\name theora_control() codes */ /**\name theora_control() codes */
/* \anchor decctlcodes_old
/**\anchor decctlcodes
* These are the available request codes for theora_control() * These are the available request codes for theora_control()
* when called with a decoder instance. * when called with a decoder instance.
* By convention, these are odd, to distinguish them from the * By convention decoder control codes are odd, to distinguish
* \ref encctlcodes "encoder control codes". * them from \ref encctlcodes_old "encoder control codes" which
* are even.
*
* Note that since the 1.0 release, both the legacy and the final
* implementation accept all the same control codes, but only the
* final API declares the newer codes.
*
* Keep any experimental or vendor-specific values above \c 0x8000.*/ * Keep any experimental or vendor-specific values above \c 0x8000.*/
/*@{*/
/**Get the maximum post-processing level. /**Get the maximum post-processing level.
* The decoder supports a post-processing filter that can improve * The decoder supports a post-processing filter that can improve
* the appearance of the decoded images. This returns the highest * the appearance of the decoded images. This returns the highest
* level setting for this post-processor, corresponding to maximum * level setting for this post-processor, corresponding to maximum
* improvement and computational expense. * improvement and computational expense.
*/ */
#define TH_DECCTL_GET_PPLEVEL_MAX (1) #define TH_DECCTL_GET_PPLEVEL_MAX (1)
/**Set the post-processing level. /**Set the post-processing level.
* Sets the level of post-processing to use when decoding the * Sets the level of post-processing to use when decoding the
skipping to change at line 326 skipping to change at line 322
/**Sets the maximum distance between key frames. /**Sets the maximum distance between key frames.
* This can be changed during an encode, but will be bounded by * This can be changed during an encode, but will be bounded by
* <tt>1<<th_info#keyframe_granule_shift</tt>. * <tt>1<<th_info#keyframe_granule_shift</tt>.
* If it is set before encoding begins, th_info#keyframe_granule_shift will * If it is set before encoding begins, th_info#keyframe_granule_shift will
* be enlarged appropriately. * be enlarged appropriately.
* *
* \param[in] buf <tt>ogg_uint32_t</tt>: The maximum distance between key * \param[in] buf <tt>ogg_uint32_t</tt>: The maximum distance between key
* frames. * frames.
* \param[out] buf <tt>ogg_uint32_t</tt>: The actual maximum distance set. * \param[out] buf <tt>ogg_uint32_t</tt>: The actual maximum distance set.
* \retval TH_FAULT \a theora_state or \a buf is <tt>NULL</tt>. * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>. * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/ * \retval OC_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4) #define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
/**Set the granule position. /**Set the granule position.
* Call this after a seek, to update the internal granulepos * Call this after a seek, to update the internal granulepos
* in the decoder, to insure that subsequent frames are marked * in the decoder, to insure that subsequent frames are marked
* properly. If you track timestamps yourself and do not use * properly. If you track timestamps yourself and do not use
* the granule postion returned by the decoder, then you do * the granule postion returned by the decoder, then you do
* not need to use this control. * not need to use this control.
*/ */
#define TH_DECCTL_SET_GRANPOS (5) #define TH_DECCTL_SET_GRANPOS (5)
/**\anchor encctlcodes /**\anchor encctlcodes_old */
* These are the available request codes for theora_control()
* when called with an encoder instance.
* By convention, these are even, to distinguish them from the
* \ref decctlcodes "decoder control codes".
* Keep any experimental or vendor-specific values above \c 0x8000.*/
/*@{*/
/**Sets the quantization parameters to use. /**Sets the quantization parameters to use.
* The parameters are copied, not stored by reference, so they can be freed * The parameters are copied, not stored by reference, so they can be freed
* after this call. * after this call.
* <tt>NULL</tt> may be specified to revert to the default parameters. * <tt>NULL</tt> may be specified to revert to the default parameters.
* For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater th
an
* <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.
* *
* \param[in] buf #th_quant_info * \param[in] buf #th_quant_info
* \retval TH_FAULT \a theora_state is <tt>NULL</tt>. * \retval OC_FAULT \a theora_state is <tt>NULL</tt>.
* \retval TH_EINVAL Encoding has already begun, the quantization parameter * \retval OC_EINVAL Encoding has already begun, the quantization parameter
s s
* do not meet one of the above stated conditions, \a bu * are not acceptable to this version of the encoder,
f * \a buf is <tt>NULL</tt> and \a buf_sz is not zero,
* is <tt>NULL</tt> and \a buf_sz is not zero, or \a buf * or \a buf is non-<tt>NULL</tt> and \a buf_sz is
* is non-<tt>NULL</tt> and \a buf_sz is not * not <tt>sizeof(#th_quant_info)</tt>.
* <tt>sizeof(#th_quant_info)</tt>. * \retval OC_IMPL Not supported by this implementation.*/
* \retval TH_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_QUANT_PARAMS (2) #define TH_ENCCTL_SET_QUANT_PARAMS (2)
/**Disables any encoder features that would prevent lossless transcoding ba ck /**Disables any encoder features that would prevent lossless transcoding ba ck
* to VP3. * to VP3.
* This primarily means disabling block-level QI values and not using 4MV m ode * This primarily means disabling block-level QI values and not using 4MV m ode
* when any of the luma blocks in a macro block are not coded. * when any of the luma blocks in a macro block are not coded.
* It also includes using the VP3 quantization tables and Huffman codes; if you * It also includes using the VP3 quantization tables and Huffman codes; if you
* set them explicitly after calling this function, the resulting stream w ill * set them explicitly after calling this function, the resulting stream w ill
* not be VP3-compatible. * not be VP3-compatible.
* If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source
* material, or when using a picture region smaller than the full frame (e .g. * material, or when using a picture region smaller than the full frame (e .g.
* a non-multiple-of-16 width or height), then non-VP3 bitstream features will * a non-multiple-of-16 width or height), then non-VP3 bitstream features will
skipping to change at line 390 skipping to change at line 377
* be enabled or disabled as requested. * be enabled or disabled as requested.
* *
* \param[in] buf <tt>int</tt>: a non-zero value to enable VP3 compatibili ty, * \param[in] buf <tt>int</tt>: a non-zero value to enable VP3 compatibili ty,
* or 0 to disable it (the default). * or 0 to disable it (the default).
* \param[out] buf <tt>int</tt>: 1 if all bitstream features required for * \param[out] buf <tt>int</tt>: 1 if all bitstream features required for
* VP3-compatibility could be set, and 0 otherwise. * VP3-compatibility could be set, and 0 otherwise.
* The latter will be returned if the pixel format is not * The latter will be returned if the pixel format is not
* 4:2:0, the picture region is smaller than the full fra me, * 4:2:0, the picture region is smaller than the full fra me,
* or if encoding has begun, preventing the quantization * or if encoding has begun, preventing the quantization
* tables and codebooks from being set. * tables and codebooks from being set.
* \retval TH_FAULT \a theora_state or \a buf is <tt>NULL</tt>. * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>. * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/ * \retval OC_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_VP3_COMPATIBLE (10) #define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
/**Gets the maximum speed level. /**Gets the maximum speed level.
* Higher speed levels favor quicker encoding over better quality per bit. * Higher speed levels favor quicker encoding over better quality per bit.
* Depending on the encoding mode, and the internal algorithms used, qualit y * Depending on the encoding mode, and the internal algorithms used, qualit y
* may actually improve, but in this case bitrate will also likely increas e. * may actually improve, but in this case bitrate will also likely increas e.
* In any case, overall rate/distortion performance will probably decrease. * In any case, overall rate/distortion performance will probably decrease.
* The maximum value, and the meaning of each value, may change depending o n * The maximum value, and the meaning of each value, may change depending o n
* the current encoding mode (VBR vs. CQI, etc.). * the current encoding mode (VBR vs. CQI, etc.).
* *
* \param[out] buf int: The maximum encoding speed level. * \param[out] buf int: The maximum encoding speed level.
* \retval TH_FAULT \a theora_state or \a buf is <tt>NULL</tt>. * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>. * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
* \retval TH_IMPL Not supported by this implementation in the current * \retval OC_IMPL Not supported by this implementation in the current
* encoding mode.*/ * encoding mode.*/
#define TH_ENCCTL_GET_SPLEVEL_MAX (12) #define TH_ENCCTL_GET_SPLEVEL_MAX (12)
/**Sets the speed level. /**Sets the speed level.
* By default a speed value of 1 is used. * By default a speed value of 1 is used.
* *
* \param[in] buf int: The new encoding speed level. * \param[in] buf int: The new encoding speed level.
* 0 is slowest, larger values use less CPU. * 0 is slowest, larger values use less CPU.
* \retval TH_FAULT \a theora_state or \a buf is <tt>NULL</tt>. * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>, or the * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>, or the
* encoding speed level is out of bounds. * encoding speed level is out of bounds.
* The maximum encoding speed level may be * The maximum encoding speed level may be
* implementation- and encoding mode-specific, and can b e * implementation- and encoding mode-specific, and can b e
* obtained via #TH_ENCCTL_GET_SPLEVEL_MAX. * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
* \retval TH_IMPL Not supported by this implementation in the current * \retval OC_IMPL Not supported by this implementation in the current
* encoding mode.*/ * encoding mode.*/
#define TH_ENCCTL_SET_SPLEVEL (14) #define TH_ENCCTL_SET_SPLEVEL (14)
/*@}*/ /*@}*/
#define OC_FAULT -1 /**< General failure */ #define OC_FAULT -1 /**< General failure */
#define OC_EINVAL -10 /**< Library encountered invalid internal d ata */ #define OC_EINVAL -10 /**< Library encountered invalid internal d ata */
#define OC_DISABLED -11 /**< Requested action is disabled */ #define OC_DISABLED -11 /**< Requested action is disabled */
#define OC_BADHEADER -20 /**< Header packet was corrupt/invalid */ #define OC_BADHEADER -20 /**< Header packet was corrupt/invalid */
#define OC_NOTFORMAT -21 /**< Packet is not a theora packet */ #define OC_NOTFORMAT -21 /**< Packet is not a theora packet */
#define OC_VERSION -22 /**< Bitstream version is not handled */ #define OC_VERSION -22 /**< Bitstream version is not handled */
#define OC_IMPL -23 /**< Feature or action not implemented */ #define OC_IMPL -23 /**< Feature or action not implemented */
#define OC_BADPACKET -24 /**< Packet is corrupt */ #define OC_BADPACKET -24 /**< Packet is corrupt */
skipping to change at line 780 skipping to change at line 770
/** /**
* Clear an allocated theora_comment struct so that it can be freed. * Clear an allocated theora_comment struct so that it can be freed.
* \param tc An allocated theora_comment structure. * \param tc An allocated theora_comment structure.
**/ **/
extern void theora_comment_clear(theora_comment *tc); extern void theora_comment_clear(theora_comment *tc);
/**Encoder control function. /**Encoder control function.
* This is used to provide advanced control the encoding process. * This is used to provide advanced control the encoding process.
* \param th A #theora_state handle. * \param th A #theora_state handle.
* \param req The control code to process. * \param req The control code to process.
* See \ref encctlcodes "the list of available control codes * See \ref encctlcodes_old "the list of available
" * control codes" for details.
* for details.
* \param buf The parameters for this control code. * \param buf The parameters for this control code.
* \param buf_sz The size of the parameter buffer.*/ * \param buf_sz The size of the parameter buffer.*/
extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz) ; extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz) ;
/* @} */ /* end oldfuncs doxygen group */ /* @} */ /* end oldfuncs doxygen group */
#ifdef __cplusplus #ifdef __cplusplus
} }
#endif /* __cplusplus */ #endif /* __cplusplus */
 End of changes. 21 change blocks. 
63 lines changed or deleted 47 lines changed or added


 theoradec.h   theoradec.h 
/******************************************************************** /********************************************************************
* * * *
* THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. * * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
* USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
* GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
* IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
* * * *
* THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2007 * * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
* by the Xiph.Org Foundation http://www.xiph.org/ * * by the Xiph.Org Foundation http://www.xiph.org/ *
* * * *
******************************************************************** ********************************************************************
function: function:
last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $ last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
********************************************************************/ ********************************************************************/
/**\file /**\file
skipping to change at line 39 skipping to change at line 39
#endif #endif
/**\name th_decode_ctl() codes /**\name th_decode_ctl() codes
* \anchor decctlcodes * \anchor decctlcodes
* These are the available request codes for th_decode_ctl(). * These are the available request codes for th_decode_ctl().
* By convention, these are odd, to distinguish them from the * By convention, these are odd, to distinguish them from the
* \ref encctlcodes "encoder control codes". * \ref encctlcodes "encoder control codes".
* Keep any experimental or vendor-specific values above \c 0x8000.*/ * Keep any experimental or vendor-specific values above \c 0x8000.*/
/*@{*/ /*@{*/
/**Gets the maximum post-processing level. /**Gets the maximum post-processing level.
* The decoder supports a post-processing filter that can improve
* the appearance of the decoded images. This returns the highest
* level setting for this post-processor, corresponding to maximum
* improvement and computational expense.
* *
* \param[out] _buf int: The maximum post-processing level. * \param[out] _buf int: The maximum post-processing level.
* \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>. * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>. * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
* \retval TH_EIMPL Not supported by this implementation.*/ * \retval TH_EIMPL Not supported by this implementation.*/
#define TH_DECCTL_GET_PPLEVEL_MAX (1) #define TH_DECCTL_GET_PPLEVEL_MAX (1)
/**Sets the post-processing level. /**Sets the post-processing level.
* By default, post-processing is disabled. * By default, post-processing is disabled.
* *
* Sets the level of post-processing to use when decoding the
* compressed stream. This must be a value between zero (off)
* and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
*
* \param[in] _buf int: The new post-processing level. * \param[in] _buf int: The new post-processing level.
* 0 to disable; larger values use more CPU. * 0 to disable; larger values use more CPU.
* \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>. * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
* post-processing level is out of bounds. * post-processing level is out of bounds.
* The maximum post-processing level may be * The maximum post-processing level may be
* implementation-specific, and can be obtained via * implementation-specific, and can be obtained via
* #TH_DECCTL_GET_PPLEVEL_MAX. * #TH_DECCTL_GET_PPLEVEL_MAX.
* \retval TH_EIMPL Not supported by this implementation.*/ * \retval TH_EIMPL Not supported by this implementation.*/
#define TH_DECCTL_SET_PPLEVEL (3) #define TH_DECCTL_SET_PPLEVEL (3)
skipping to change at line 84 skipping to change at line 92
* th_stripe_callback#stripe_decoded set to <tt>NULL</tt> to disable the * th_stripe_callback#stripe_decoded set to <tt>NULL</tt> to disable the
* callbacks at any point. * callbacks at any point.
* Enabling striped decode does not prevent you from calling * Enabling striped decode does not prevent you from calling
* th_decode_ycbcr_out() after the frame is fully decoded. * th_decode_ycbcr_out() after the frame is fully decoded.
* *
* \param[in] _buf #th_stripe_callback: The callback parameters. * \param[in] _buf #th_stripe_callback: The callback parameters.
* \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>. * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not * \retval TH_EINVAL \a _buf_sz is not
* <tt>sizeof(th_stripe_callback)</tt>.*/ * <tt>sizeof(th_stripe_callback)</tt>.*/
#define TH_DECCTL_SET_STRIPE_CB (7) #define TH_DECCTL_SET_STRIPE_CB (7)
/**Enables telemetry and sets the macroblock display mode */
#define TH_DECCTL_SET_TELEMETRY_MBMODE (9)
/**Enables telemetry and sets the motion vector display mode */
#define TH_DECCTL_SET_TELEMETRY_MV (11)
/**Enables telemetry and sets the adaptive quantization display mode */
#define TH_DECCTL_SET_TELEMETRY_QI (13)
/**Enables telemetry and sets the bitstream breakdown visualization mode */
#define TH_DECCTL_SET_TELEMETRY_BITS (15)
/*@}*/ /*@}*/
/**A callback function for striped decode. /**A callback function for striped decode.
* This is a function pointer to an application-provided function that will be * This is a function pointer to an application-provided function that will be
* called each time a section of the image is fully decoded in * called each time a section of the image is fully decoded in
* th_decode_packetin(). * th_decode_packetin().
* This allows the application to process the section immediately, while it is * This allows the application to process the section immediately, while it is
* still in cache. * still in cache.
* Note that the frame is decoded bottom to top, so \a _yfrag0 will steadil y * Note that the frame is decoded bottom to top, so \a _yfrag0 will steadil y
* decrease with each call until it reaches 0, at which point the full fra me * decrease with each call until it reaches 0, at which point the full fra me
skipping to change at line 284 skipping to change at line 301
* \param _dec A #th_dec_ctx handle. * \param _dec A #th_dec_ctx handle.
* \param _ycbcr A video buffer structure to fill in. * \param _ycbcr A video buffer structure to fill in.
* <tt>libtheoradec</tt> will fill in all the members of this * <tt>libtheoradec</tt> will fill in all the members of this
* structure, including the pointers to the uncompressed vid eo * structure, including the pointers to the uncompressed vid eo
* data. * data.
* The memory for this video data is owned by * The memory for this video data is owned by
* <tt>libtheoradec</tt>. * <tt>libtheoradec</tt>.
* It may be freed or overwritten without notification when * It may be freed or overwritten without notification when
* subsequent frames are decoded. * subsequent frames are decoded.
* \retval 0 Success * \retval 0 Success
* \retval TH_EFAULT \a _dec or \a _ycbcr was <tt>NULL</tt>.
*/ */
extern int th_decode_ycbcr_out(th_dec_ctx *_dec, extern int th_decode_ycbcr_out(th_dec_ctx *_dec,
th_ycbcr_buffer _ycbcr); th_ycbcr_buffer _ycbcr);
/**Frees an allocated decoder instance. /**Frees an allocated decoder instance.
* \param _dec A #th_dec_ctx handle.*/ * \param _dec A #th_dec_ctx handle.*/
extern void th_decode_free(th_dec_ctx *_dec); extern void th_decode_free(th_dec_ctx *_dec);
/*@}*/ /*@}*/
/*@}*/ /*@}*/
#if defined(__cplusplus) #if defined(__cplusplus)
 End of changes. 5 change blocks. 
1 lines changed or deleted 19 lines changed or added


 theoraenc.h   theoraenc.h 
/******************************************************************** /********************************************************************
* * * *
* THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. * * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
* USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
* GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
* IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
* * * *
* THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2003 * * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
* by the Xiph.Org Foundation http://www.xiph.org/ * * by the Xiph.Org Foundation http://www.xiph.org/ *
* * * *
******************************************************************** ********************************************************************
function: function:
last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $ last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
********************************************************************/ ********************************************************************/
/**\file /**\file
skipping to change at line 50 skipping to change at line 50
* this call. * this call.
* <tt>NULL</tt> may be specified to revert to the default tables. * <tt>NULL</tt> may be specified to revert to the default tables.
* *
* \param[in] _buf <tt>#th_huff_code[#TH_NHUFFMAN_TABLES][#TH_NDCT_TOKENS]< /tt> * \param[in] _buf <tt>#th_huff_code[#TH_NHUFFMAN_TABLES][#TH_NDCT_TOKENS]< /tt>
* \retval TH_EFAULT \a _enc_ctx is <tt>NULL</tt>. * \retval TH_EFAULT \a _enc_ctx is <tt>NULL</tt>.
* \retval TH_EINVAL Encoding has already begun or one or more of the given * \retval TH_EINVAL Encoding has already begun or one or more of the given
* tables is not full or prefix-free, \a _buf is * tables is not full or prefix-free, \a _buf is
* <tt>NULL</tt> and \a _buf_sz is not zero, or \a _buf is * <tt>NULL</tt> and \a _buf_sz is not zero, or \a _buf is
* non-<tt>NULL</tt> and \a _buf_sz is not * non-<tt>NULL</tt> and \a _buf_sz is not
* <tt>sizeof(#th_huff_code)*#TH_NHUFFMAN_TABLES*#TH_ND CT_TOKENS</tt>. * <tt>sizeof(#th_huff_code)*#TH_NHUFFMAN_TABLES*#TH_ND CT_TOKENS</tt>.
* \retval TH_IMPL Not supported by this implementation.*/ * \retval TH_EIMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_HUFFMAN_CODES (0) #define TH_ENCCTL_SET_HUFFMAN_CODES (0)
/**Sets the quantization parameters to use. /**Sets the quantization parameters to use.
* The parameters are copied, not stored by reference, so they can be freed * The parameters are copied, not stored by reference, so they can be freed
* after this call. * after this call.
* <tt>NULL</tt> may be specified to revert to the default parameters. * <tt>NULL</tt> may be specified to revert to the default parameters.
* For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater th
an
* <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.
* *
* \param[in] _buf #th_quant_info * \param[in] _buf #th_quant_info
* \retval TH_EFAULT \a _enc_ctx is <tt>NULL</tt>. * \retval TH_EFAULT \a _enc_ctx is <tt>NULL</tt>.
* \retval TH_EINVAL Encoding has already begun, the quantization parameter * \retval TH_EINVAL Encoding has already begun, \a _buf is
s * <tt>NULL</tt> and \a _buf_sz is not zero,
* do not meet one of the above stated conditions, \a _b * or \a _buf is non-<tt>NULL</tt> and
uf * \a _buf_sz is not <tt>sizeof(#th_quant_info)</tt>.
* is <tt>NULL</tt> and \a _buf_sz is not zero, or \a _b * \retval TH_EIMPL Not supported by this implementation.*/
uf
* is non-<tt>NULL</tt> and \a _buf_sz is not
* <tt>sizeof(#th_quant_info)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_QUANT_PARAMS (2) #define TH_ENCCTL_SET_QUANT_PARAMS (2)
/**Sets the maximum distance between key frames. /**Sets the maximum distance between key frames.
* This can be changed during an encode, but will be bounded by * This can be changed during an encode, but will be bounded by
* <tt>1<<th_info#keyframe_granule_shift</tt>. * <tt>1<<th_info#keyframe_granule_shift</tt>.
* If it is set before encoding begins, th_info#keyframe_granule_shift will * If it is set before encoding begins, th_info#keyframe_granule_shift will
* be enlarged appropriately. * be enlarged appropriately.
* *
* \param[in] _buf <tt>ogg_uint32_t</tt>: The maximum distance between key * \param[in] _buf <tt>ogg_uint32_t</tt>: The maximum distance between key
* frames. * frames.
* \param[out] _buf <tt>ogg_uint32_t</tt>: The actual maximum distance set. * \param[out] _buf <tt>ogg_uint32_t</tt>: The actual maximum distance set.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>. * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/ * \retval TH_EIMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4) #define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
/**Disables any encoder features that would prevent lossless transcoding ba ck /**Disables any encoder features that would prevent lossless transcoding ba ck
* to VP3. * to VP3.
* This primarily means disabling block-level QI values and not using 4MV m * This primarily means disabling block-adaptive quantization and always co
ode ding
* when any of the luma blocks in a macro block are not coded. * all four luma blocks in a macro block when 4MV is used.
* It also includes using the VP3 quantization tables and Huffman codes; if you * It also includes using the VP3 quantization tables and Huffman codes; if you
* set them explicitly after calling this function, the resulting stream w ill * set them explicitly after calling this function, the resulting stream w ill
* not be VP3-compatible. * not be VP3-compatible.
* If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source
* material, or when using a picture region smaller than the full frame (e .g. * material, or when using a picture region smaller than the full frame (e .g.
* a non-multiple-of-16 width or height), then non-VP3 bitstream features will * a non-multiple-of-16 width or height), then non-VP3 bitstream features will
* still be disabled, but the stream will still not be VP3-compatible, as VP3 * still be disabled, but the stream will still not be VP3-compatible, as VP3
* was not capable of encoding such formats. * was not capable of encoding such formats.
* If you call this after encoding has already begun, then the quantization * If you call this after encoding has already begun, then the quantization
* tables and codebooks cannot be changed, but the frame-level features wi ll * tables and codebooks cannot be changed, but the frame-level features wi ll
skipping to change at line 110 skipping to change at line 104
* \param[in] _buf <tt>int</tt>: a non-zero value to enable VP3 compatibil ity, * \param[in] _buf <tt>int</tt>: a non-zero value to enable VP3 compatibil ity,
* or 0 to disable it (the default). * or 0 to disable it (the default).
* \param[out] _buf <tt>int</tt>: 1 if all bitstream features required for * \param[out] _buf <tt>int</tt>: 1 if all bitstream features required for
* VP3-compatibility could be set, and 0 otherwise. * VP3-compatibility could be set, and 0 otherwise.
* The latter will be returned if the pixel format is not * The latter will be returned if the pixel format is not
* 4:2:0, the picture region is smaller than the full fra me, * 4:2:0, the picture region is smaller than the full fra me,
* or if encoding has begun, preventing the quantization * or if encoding has begun, preventing the quantization
* tables and codebooks from being set. * tables and codebooks from being set.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>. * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
* \retval TH_IMPL Not supported by this implementation.*/ * \retval TH_EIMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_VP3_COMPATIBLE (10) #define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
/**Gets the maximum speed level. /**Gets the maximum speed level.
* Higher speed levels favor quicker encoding over better quality per bit. * Higher speed levels favor quicker encoding over better quality per bit.
* Depending on the encoding mode, and the internal algorithms used, qualit y * Depending on the encoding mode, and the internal algorithms used, qualit y
* may actually improve, but in this case bitrate will also likely increas e. * may actually improve, but in this case bitrate will also likely increas e.
* In any case, overall rate/distortion performance will probably decrease. * In any case, overall rate/distortion performance will probably decrease.
* The maximum value, and the meaning of each value, may change depending o n * The maximum value, and the meaning of each value, may change depending o n
* the current encoding mode (VBR vs. CQI, etc.). * the current encoding mode (VBR vs. constant quality, etc.).
* *
* \param[out] _buf int: The maximum encoding speed level. * \param[out] _buf <tt>int</tt>: The maximum encoding speed level.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>. * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
* \retval TH_IMPL Not supported by this implementation in the current * \retval TH_EIMPL Not supported by this implementation in the current
* encoding mode.*/ * encoding mode.*/
#define TH_ENCCTL_GET_SPLEVEL_MAX (12) #define TH_ENCCTL_GET_SPLEVEL_MAX (12)
/**Sets the speed level. /**Sets the speed level.
* By default, the slowest speed (0) is used. * The current speed level may be retrieved using #TH_ENCCTL_GET_SPLEVEL.
* *
* \param[in] _buf int: The new encoding speed level. * \param[in] _buf <tt>int</tt>: The new encoding speed level.
* 0 is slowest, larger values use less CPU. * 0 is slowest, larger values use less CPU.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
* encoding speed level is out of bounds. * encoding speed level is out of bounds.
* The maximum encoding speed level may be * The maximum encoding speed level may be
* implementation- and encoding mode-specific, and can b e * implementation- and encoding mode-specific, and can b e
* obtained via #TH_ENCCTL_GET_SPLEVEL_MAX. * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
* \retval TH_IMPL Not supported by this implementation in the current * \retval TH_EIMPL Not supported by this implementation in the current
* encoding mode.*/ * encoding mode.*/
#define TH_ENCCTL_SET_SPLEVEL (14) #define TH_ENCCTL_SET_SPLEVEL (14)
/**Gets the current speed level.
* The default speed level may vary according to encoder implementation, bu
t if
* this control code is not supported (it returns #TH_EIMPL), the default
may
* be assumed to be the slowest available speed (0).
* The maximum encoding speed level may be implementation- and encoding
* mode-specific, and can be obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
*
* \param[out] _buf <tt>int</tt>: The current encoding speed level.
* 0 is slowest, larger values use less CPU.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
* \retval TH_EIMPL Not supported by this implementation in the current
* encoding mode.*/
#define TH_ENCCTL_GET_SPLEVEL (16)
/**Sets the number of duplicates of the next frame to produce.
* Although libtheora can encode duplicate frames very cheaply, it costs so
me
* amount of CPU to detect them, and a run of duplicates cannot span a
* keyframe boundary.
* This control code tells the encoder to produce the specified number of e
xtra
* duplicates of the next frame.
* This allows the encoder to make smarter keyframe placement decisions and
* rate control decisions, and reduces CPU usage as well, when compared to
* just submitting the same frame for encoding multiple times.
* This setting only applies to the next frame submitted for encoding.
* You MUST call th_encode_packetout() repeatedly until it returns 0, or th
e
* extra duplicate frames will be lost.
*
* \param[in] _buf <tt>int</tt>: The number of duplicates to produce.
* If this is negative or zero, no duplicates will be produ
ced.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
* number of duplicates is greater than or equal to the
* maximum keyframe interval.
* In the latter case, NO duplicate frames will be produc
ed.
* You must ensure that the maximum keyframe interval is
set
* larger than the maximum number of duplicates you will
* ever wish to insert prior to encoding.
* \retval TH_EIMPL Not supported by this implementation in the current
* encoding mode.*/
#define TH_ENCCTL_SET_DUP_COUNT (18)
/**Modifies the default bitrate management behavior.
* Use to allow or disallow frame dropping, and to enable or disable cappin
g
* bit reservoir overflows and underflows.
* See \ref encctlcodes "the list of available flags".
* The flags are set by default to
* <tt>#TH_RATECTL_DROP_FRAMES|#TH_RATECTL_CAP_OVERFLOW</tt>.
*
* \param[in] _buf <tt>int</tt>: Any combination of
* \ref ratectlflags "the available flags":
* - #TH_RATECTL_DROP_FRAMES: Enable frame dropping.
* - #TH_RATECTL_CAP_OVERFLOW: Don't bank excess bits for l
ater
* use.
* - #TH_RATECTL_CAP_UNDERFLOW: Don't try to make up shortf
alls
* later.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt> or rate control
* is not enabled.
* \retval TH_EIMPL Not supported by this implementation in the current
* encoding mode.*/
#define TH_ENCCTL_SET_RATE_FLAGS (20)
/**Sets the size of the bitrate management bit reservoir as a function
* of number of frames.
* The reservoir size affects how quickly bitrate management reacts to
* instantaneous changes in the video complexity.
* Larger reservoirs react more slowly, and provide better overall quality,
but
* require more buffering by a client, adding more latency to live streams
.
* By default, libtheora sets the reservoir to the maximum distance between
* keyframes, subject to a minimum and maximum limit.
* This call may be used to increase or decrease the reservoir, increasing
or
* decreasing the allowed temporary variance in bitrate.
* An implementation may impose some limits on the size of a reservoir it c
an
* handle, in which case the actual reservoir size may not be exactly what
was
* requested.
* The actual value set will be returned.
*
* \param[in] _buf <tt>int</tt>: Requested size of the reservoir measured
in
* frames.
* \param[out] _buf <tt>int</tt>: The actual size of the reservoir set.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or rate contro
l
* is not enabled. The buffer has an implementation
* defined minimum and maximum size and the value in _bu
f
* will be adjusted to match the actual value set.
* \retval TH_EIMPL Not supported by this implementation in the current
* encoding mode.*/
#define TH_ENCCTL_SET_RATE_BUFFER (22)
/**Enable pass 1 of two-pass encoding mode and retrieve the first pass metr
ics.
* Pass 1 mode must be enabled before the first frame is encoded, and a tar
get
* bitrate must have already been specified to the encoder.
* Although this does not have to be the exact rate that will be used in th
e
* second pass, closer values may produce better results.
* The first call returns the size of the two-pass header data, along with
some
* placeholder content, and sets the encoder into pass 1 mode implicitly.
* This call sets the encoder to pass 1 mode implicitly.
* Then, a subsequent call must be made after each call to
* th_encode_ycbcr_in() to retrieve the metrics for that frame.
* An additional, final call must be made to retrieve the summary data,
* containing such information as the total number of frames, etc.
* This must be stored in place of the placeholder data that was returned
* in the first call, before the frame metrics data.
* All of this data must be presented back to the encoder during pass 2 usi
ng
* #TH_ENCCTL_2PASS_IN.
*
* \param[out] <tt>char *</tt>_buf: Returns a pointer to internal storage
* containing the two pass metrics data.
* This storage is only valid until the next call, or until the
* encoder context is freed, and must be copied by the
* application.
* \retval >=0 The number of bytes of metric data available in the
* returned buffer.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(char *)</tt>, no target
* bitrate has been set, or the first call was made afte
r
* the first frame was submitted for encoding.
* \retval TH_EIMPL Not supported by this implementation.*/
#define TH_ENCCTL_2PASS_OUT (24)
/**Submits two-pass encoding metric data collected the first encoding pass
to
* the second pass.
* The first call must be made before the first frame is encoded, and a tar
get
* bitrate must have already been specified to the encoder.
* It sets the encoder to pass 2 mode implicitly; this cannot be disabled.
* The encoder may require reading data from some or all of the frames in
* advance, depending on, e.g., the reservoir size used in the second pass
.
* You must call this function repeatedly before each frame to provide data
* until either a) it fails to consume all of the data presented or b) all
of
* the pass 1 data has been consumed.
* In the first case, you must save the remaining data to be presented afte
r
* the next frame.
* You can call this function with a NULL argument to get an upper bound on
* the number of bytes that will be required before the next frame.
*
* When pass 2 is first enabled, the default bit reservoir is set to the en
tire
* file; this gives maximum flexibility but can lead to very high peak rat
es.
* You can subsequently set it to another value with #TH_ENCCTL_SET_RATE_BU
FFER
* (e.g., to set it to the keyframe interval for non-live streaming), howe
ver,
* you may then need to provide more data before the next frame.
*
* \param[in] _buf <tt>char[]</tt>: A buffer containing the data returned b
y
* #TH_ENCCTL_2PASS_OUT in pass 1.
* You may pass <tt>NULL</tt> for \a _buf to return an uppe
r
* bound on the number of additional bytes needed before t
he
* next frame.
* The summary data returned at the end of pass 1 must be a
t
* the head of the buffer on the first call with a
* non-<tt>NULL</tt> \a _buf, and the placeholder data
* returned at the start of pass 1 should be omitted.
* After each call you should advance this buffer by the nu
mber
* of bytes consumed.
* \retval >0 The number of bytes of metric data required/consum
ed.
* \retval 0 No more data is required before the next frame.
* \retval TH_EFAULT \a _enc_ctx is <tt>NULL</tt>.
* \retval TH_EINVAL No target bitrate has been set, or the first call
was
* made after the first frame was submitted for
* encoding.
* \retval TH_ENOTFORMAT The data did not appear to be pass 1 from a compat
ible
* implementation of this library.
* \retval TH_EBADHEADER The data was invalid; this may be returned when
* attempting to read an aborted pass 1 file that st
ill
* has the placeholder data in place of the summary
* data.
* \retval TH_EIMPL Not supported by this implementation.*/
#define TH_ENCCTL_2PASS_IN (26)
/**Sets the current encoding quality.
* This is only valid so long as no bitrate has been specified, either thro
ugh
* the #th_info struct used to initialize the encoder or through
* #TH_ENCCTL_SET_BITRATE (this restriction may be relaxed in a future
* version).
* If it is set before the headers are emitted, the target quality encoded
in
* them will be updated.
*
* \param[in] _buf <tt>int</tt>: The new target quality, in the range 0...6
3,
* inclusive.
* \retval 0 Success.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL A target bitrate has already been specified, or th
e
* quality index was not in the range 0...63.
* \retval TH_EIMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_QUALITY (28)
/**Sets the current encoding bitrate.
* Once a bitrate is set, the encoder must use a rate-controlled mode for a
ll
* future frames (this restriction may be relaxed in a future version).
* If it is set before the headers are emitted, the target bitrate encoded
in
* them will be updated.
* Due to the buffer delay, the exact bitrate of each section of the encode
is
* not guaranteed.
* The encoder may have already used more bits than allowed for the frames
it
* has encoded, expecting to make them up in future frames, or it may have
* used fewer, holding the excess in reserve.
* The exact transition between the two bitrates is not well-defined by thi
s
* API, but may be affected by flags set with #TH_ENCCTL_SET_RATE_FLAGS.
* After a number of frames equal to the buffer delay, one may expect furth
er
* output to average at the target bitrate.
*
* \param[in] _buf <tt>long</tt>: The new target bitrate, in bits per secon
d.
* \retval 0 Success.
* \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>.
* \retval TH_EINVAL The target bitrate was not positive.
* \retval TH_EIMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_BITRATE (30)
/*@}*/
/**\name TH_ENCCTL_SET_RATE_FLAGS flags
* \anchor ratectlflags
* These are the flags available for use with #TH_ENCCTL_SET_RATE_FLAGS.*/
/*@{*/
/**Drop frames to keep within bitrate buffer constraints.
* This can have a severe impact on quality, but is the only way to ensure
that
* bitrate targets are met at low rates during sudden bursts of activity.*
/
#define TH_RATECTL_DROP_FRAMES (0x1)
/**Ignore bitrate buffer overflows.
* If the encoder uses so few bits that the reservoir of available bits
* overflows, ignore the excess.
* The encoder will not try to use these extra bits in future frames.
* At high rates this may cause the result to be undersized, but allows a
* client to play the stream using a finite buffer; it should normally be
* enabled.*/
#define TH_RATECTL_CAP_OVERFLOW (0x2)
/**Ignore bitrate buffer underflows.
* If the encoder uses so many bits that the reservoir of available bits
* underflows, ignore the deficit.
* The encoder will not try to make up these extra bits in future frames.
* At low rates this may cause the result to be oversized; it should normal
ly
* be disabled.*/
#define TH_RATECTL_CAP_UNDERFLOW (0x4)
/*@}*/ /*@}*/
/**The quantization parameters used by VP3.*/ /**The quantization parameters used by VP3.*/
extern const th_quant_info TH_VP31_QUANT_INFO; extern const th_quant_info TH_VP31_QUANT_INFO;
/**The Huffman tables used by VP3.*/ /**The Huffman tables used by VP3.*/
extern const th_huff_code extern const th_huff_code
TH_VP31_HUFF_CODES[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS]; TH_VP31_HUFF_CODES[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS];
/**\name Encoder state /**\name Encoder state
 End of changes. 14 change blocks. 
31 lines changed or deleted 301 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/