[xiph-commits] r11161 - experimental/derf/theora-exp/include/theora
tterribe at svn.xiph.org
tterribe at svn.xiph.org
Mon Apr 17 18:22:43 PDT 2006
Author: tterribe
Date: 2006-04-17 18:22:41 -0700 (Mon, 17 Apr 2006)
New Revision: 11161
Modified:
experimental/derf/theora-exp/include/theora/codec.h
experimental/derf/theora-exp/include/theora/theoradec.h
experimental/derf/theora-exp/include/theora/theoraenc.h
Log:
Some documentation clean-up.
Modified: experimental/derf/theora-exp/include/theora/codec.h
===================================================================
--- experimental/derf/theora-exp/include/theora/codec.h 2006-04-18 00:19:08 UTC (rev 11160)
+++ experimental/derf/theora-exp/include/theora/codec.h 2006-04-18 01:22:41 UTC (rev 11161)
@@ -19,9 +19,11 @@
*
* \section intro Introduction
*
- * This is the documentation for the <tt>libtheora</tt> C API.
- * <tt>libtheora</tt> is the reference implementation for
- * <a href="http://www.theora.org/">Theora</a>, a free video codec.
+ * This is the documentation for the <tt>libtheoradec</tt> and
+ * <tt>libtheoraenc</tt> C API.
+ * These were written to replace <tt>libtheora</tt>, 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 for Ogg multimedia formats by
* <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>.
@@ -31,16 +33,17 @@
*
* \subsection Organization
*
- * <tt>libtheora</tt> is actually subdivided into three separate libraries:
+ * The functions documented here are actually subdivided into two separate
+ * libraries:
* - <tt>libtheoraenc</tt>, containing routines exclusive to the encoder.
* You must link to this if you use any of the functions listed in
* \ref encfuncs.
* - <tt>libtheoradec</tt>, contains the decoder and shared routines.
* You must link to this if you use any of the functions listed in
- * this API.*/
+ * this API, i.e., those listed in \ref basefuncs and \ref decfuncs.*/
/**\file
- * The shared <tt>libtheora</tt> C API.*/
+ * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API.*/
#if !defined(_O_THEORA_CODEC_H_)
# define _O_THEORA_CODEC_H_ (1)
@@ -114,10 +117,9 @@
* Each row of pixels is stored contiguously in memory, but successive rows
* need not be.
* Use \a ystride to compute the offset of the next row.
- * The encoder accepts both positive \a ystride values (top-down) and negative
- * (bottom-up).
- * The decoder currently always generates images with positive strides.
- */
+ * The encoder accepts both positive \a ystride values (top-down in memory) and
+ * negative (bottom-up in memory).
+ * The decoder currently always generates images with positive strides.*/
typedef struct{
/**The width of this plane.*/
int width;
@@ -125,7 +127,7 @@
int height;
/**The offset in bytes between successive rows.*/
int ystride;
- /**A pointer to the first row.*/
+ /**A pointer to the beginning of the first row.*/
unsigned char *data;
}th_img_plane;
@@ -140,10 +142,10 @@
* \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
* contexts the U and V channels actually have opposite meanings.
- * To avoid this confusion, we are explicit: the name of the color channels is
+ * To avoid this confusion, we are explicit: the name of the color channels are
* Y'CbCr, and they appear in that order, always.
* 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];
/**Theora bitstream information.
@@ -155,7 +157,7 @@
* #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
@@ -170,7 +172,7 @@
* data.
*
* It is also generally recommended that the offsets and sizes should still be
- * multiples of 2 to avoid chroma sampling shifts.
+ * multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampled.
* See <a href="http://www.theora.org/doc/Theora_I_spec.pdf">the Theora
* specification</a>, Section 4.4, for more details.
*
@@ -179,8 +181,7 @@
* 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.
- */
+ * image dimensions.*/
typedef struct{
/**\name Theora version
* Bitstream version information.*/
@@ -208,8 +209,10 @@
/**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 offset is specified from the top of the image, as this API uses the
- * standard graphics left-handed coordinate system.*/
+ * 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.*/
ogg_uint32_t pic_y;
/**\name Frame rate
* The frame rate, as a fraction.
@@ -221,7 +224,11 @@
/**\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.*/
+ * 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 */
/*@{*/
ogg_uint32_t aspect_numerator;
ogg_uint32_t aspect_denominator;
@@ -334,7 +341,7 @@
\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 the AC coefficient.
+ <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.
@@ -349,12 +356,12 @@
Parameters that can be stored in the bitstream are as follows:
- The two scale matrices ac_scale and dc_scale.
- \code
+ \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 is stored, and the rest are linearly interpolated.
+ 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
@@ -406,8 +413,8 @@
* code.
* There is no requirement that all the tokens in a table have a valid code,
* but the current encoder is not optimized to take advantage of this.
- * If there is not at least one table with a code for every token in each of
- * the five groups of 16 tables, then the encoder may fail to encode certain
+ * If each of the five grouops of 16 tables does not contain at least one table
+ * with a code for every token, then the encoder may fail to encode certain
* frames.
* The complete table in the first group of 16 does not have to be in the same
* place as the complete table in the other groups, but the complete tables in
@@ -463,6 +470,8 @@
* This function does no verification beyond checking the packet type bit, so
* it should not be used for bitstream identification; use
* th_decode_headerin() for that.
+ * As per the Theora specification, an empty (0-byte) packet is treated as a
+ * data packet (a delta frame with no coded blocks).
* \param _op An <tt>ogg_packet</tt> containing encoded Theora data.
* \retval 1 The packet is a header packet
* \retval 0 The packet is a video data packet.*/
@@ -471,6 +480,8 @@
* This function does no verification beyond checking the packet type and
* key frame bits, so it should not be used for bitstream identification; use
* th_decode_headerin() for that.
+ * As per the Theora specification, an empty (0-byte) packet is treated as a
+ * delta frame (with no coded blocks).
* \param _op An <tt>ogg_packet</tt> containing encoded Theora data.
* \retval 1 The packet contains a key frame.
* \retval 0 The packet contains a delta frame.
@@ -522,19 +533,22 @@
* \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
+ * The same tag can appear multiple times, each with a distinct
* value, so an index is required to retrieve them all.
- * The order these values appear in is significant and should be
- * preserved.
+ * 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,int _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 instances in order.
+ * 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.*/
Modified: experimental/derf/theora-exp/include/theora/theoradec.h
===================================================================
--- experimental/derf/theora-exp/include/theora/theoradec.h 2006-04-18 00:19:08 UTC (rev 11160)
+++ experimental/derf/theora-exp/include/theora/theoradec.h 2006-04-18 01:22:41 UTC (rev 11161)
@@ -16,7 +16,7 @@
********************************************************************/
/**\file
- * The <tt>libtheora</tt> C decoding API.*/
+ * The <tt>libtheoradec</tt> C decoding API.*/
#if !defined(_O_THEORA_THEORADEC_H_)
# define _O_THEORA_THEORADEC_H_ (1)
@@ -59,6 +59,8 @@
/**Sets the granule position.
* Call this after a seek, before decoding the first frame, to ensure that the
* proper granule position is returned for all subsequent frames.
+ * If you track timestamps yourself and do not use the granule position
+ * returned by the decoder, then you need not call this function.
*
* \param[in] _buf <tt>ogg_int64_t</tt>: The granule position of the next
* frame.
@@ -72,6 +74,8 @@
* You can pass in a #th_stripe_callback with
* th_stripe_callback#stripe_decoded set to <tt>NULL</tt> to disable the
* callbacks at any point.
+ * Enabling striped decode does not prevent you from calling
+ * th_decode_ycbcr_out() after the frame is fully decoded.
*
* \param[in] _buf #th_stripe_callback: The callback parameters.
* \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
@@ -120,7 +124,7 @@
typedef struct{
/**An application-provided context pointer.
* This will be passed back verbatim to the application.*/
- void *ctx;
+ void *ctx;
/**The callback function pointer.*/
th_stripe_decoded_func stripe_decoded;
}th_stripe_callback;
@@ -203,7 +207,7 @@
* of the header data was invalid.
* \retval TH_EVERSION The packet data was a Theora info header, but for a
* bitstream version not decodable with this version of
- * <tt>libtheora</tt>.
+ * <tt>libtheoradec</tt>.
* \retval TH_ENOTFORMAT The packet was not a Theora header.
*/
extern int th_decode_headerin(th_info *_info,th_comment *_tc,
@@ -260,11 +264,11 @@
* then the application does not need to call this function.
* \param _dec A #th_dec_ctx handle.
* \param _ycbcr A video buffer structure to fill in.
- * <tt>libtheora</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 video
* data.
* The memory for this video data is owned by
- * <tt>libtheora</tt>.
+ * <tt>libtheoradec</tt>.
* It may be freed or overwritten without notification when
* subsequent frames are decoded.
* \retval 0 Success
Modified: experimental/derf/theora-exp/include/theora/theoraenc.h
===================================================================
--- experimental/derf/theora-exp/include/theora/theoraenc.h 2006-04-18 00:19:08 UTC (rev 11160)
+++ experimental/derf/theora-exp/include/theora/theoraenc.h 2006-04-18 01:22:41 UTC (rev 11161)
@@ -16,7 +16,7 @@
********************************************************************/
/**\file
- * The <tt>libtheora</tt> C encoding API.*/
+ * The <tt>libtheoraenc</tt> C encoding API.*/
#if !defined(_O_THEORA_THEORAENC_H_)
# define _O_THEORA_THEORAENC_H_ (1)
@@ -40,7 +40,7 @@
* Valid values range from 0 to 63, inclusive, with higher values giving
* higher quality.
* Note that, in this case, this corresponds to a <em>perceptual</em>
- * quality, and does not translate directly into a quantization setting.
+ * quality, and may not translate directly into a quantization setting.
* Limits on the admissible quantizers can be controlled below.*/
int qi;
/**The minimum quality to use for a keyframe.
@@ -160,8 +160,8 @@
/**Gets the maximum speed level.
* Higher speed levels favor quicker encoding over better quality per bit.
* Depending on the encoding mode, and the internal algorithms used, quality
- * may actually improve, but bitrate will also increase, and overall
- * rate/distortion performance will likely decrease.
+ * may actually improve, but in this case bitrate will also likely increase.
+ * In any case, overall rate/distortion performance will probably decrease.
* The maximum value, and the meaning of each value, may change depending on
* the current encoding mode (VBR vs. CQI, etc.).
*
@@ -193,13 +193,13 @@
* encoding mode is chosen.
*
* \param[in] _buf <tt>#th_vbr_cfg</tt>: the configuration parameters.
- * This may be <tt>NULL</tt>, in which the current VBR
+ * This may be <tt>NULL</tt>, in which case the current VBR
* configuration is unchanged.
* The default is to use the QI setting passed in via the
* #th_info struct when the encoder was initialized, with
* a full range of admissible quantizers.
* \retval OC_EFAULT \a _enc_ctx is <tt>NULL</tt>.
- * \retval TH_EINVAL The configuration parameters do not meet one of their
+ * \retval TH_EINVAL The configuration parameters do not meet one of their
* stated requirements, \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 <tt>sizeof(#th_vbr_cfg)</tt>.
@@ -284,8 +284,8 @@
size_t _buf_sz);
/**Outputs the next header packet.
* This should be called repeatedly after encoder initialization until it
- * returns 0 to get all of the header packets, in order, before encoding
- * actual video data.
+ * returns 0 in order to get all of the header packets, in order, before
+ * encoding actual video data.
* \param _enc A #th_enc_ctx handle.
* \param _comments The metadata to place in the comment header, when it is
* encoded.
@@ -293,7 +293,8 @@
* All of the elements of this structure will be set,
* including a pointer to the header data.
* The memory for the header data is owned by
- * <tt>libtheora</tt>.
+ * <tt>libtheoraenc</tt>, and may be invalidated when the
+ * next encoder function is called.
* \return A positive value indicates that a header packet was successfully
* produced.
* \retval 0 No packet was produced, and no more header packets remain.
@@ -306,15 +307,15 @@
* \retval 0 Success.
* \retval TH_FAULT \a _enc or \a _ycbcr is <tt>NULL</tt>.
* \retval TH_EINVAL The buffer size does not match the frame size the encoder
- * was initialized with, or encoding has already completed.
- */
+ * was initialized with, or encoding has already
+ * completed.*/
extern int th_encode_ycbcr_in(th_enc_ctx *_enc,
th_ycbcr_buffer _ycbcr);
/**Retrieves encoded video data packets.
* This should be called repeatedly after each frame is submitted to flush any
* encoded packets, until it returns 0.
* The encoder will not buffer these packets as subsequent frames are
- * compressed, so a failure to do so function will result in lost video data.
+ * compressed, so a failure to do so will result in lost video data.
* \note Currently the encoder operates in a one-frame-in, one-packet-out
* manner.
* However, this may be changed in the future.
@@ -325,7 +326,9 @@
* \param _op An <tt>ogg_packet</tt> structure to fill.
* All of the elements of this structure will be set, including a
* pointer to the video data.
- * The memory for the video data is owned by <tt>libtheora</tt>.
+ * The memory for the video data is owned by
+ * <tt>libtheoraenc</tt>, and may be invalidated when the next
+ * encoder function is called.
* \return A positive value indicates that a video data packet was successfully
* produced.
* \retval 0 No packet was produced, and no more encoded video data
More information about the commits
mailing list