[xiph-commits] r17787 - trunk/theora/include/theora
giles at svn.xiph.org
giles at svn.xiph.org
Thu Jan 20 15:00:15 PST 2011
Author: giles
Date: 2011-01-20 15:00:15 -0800 (Thu, 20 Jan 2011)
New Revision: 17787
Modified:
trunk/theora/include/theora/codec.h
trunk/theora/include/theora/theora.h
trunk/theora/include/theora/theoradec.h
trunk/theora/include/theora/theoraenc.h
Log:
Remove trailing whitespace in the public headers.
Modified: trunk/theora/include/theora/codec.h
===================================================================
--- trunk/theora/include/theora/codec.h 2011-01-19 06:25:41 UTC (rev 17786)
+++ trunk/theora/include/theora/codec.h 2011-01-20 23:00:15 UTC (rev 17787)
@@ -16,7 +16,7 @@
********************************************************************/
/**\mainpage
- *
+ *
* \section intro Introduction
*
* This is the documentation for <tt>libtheora</tt> C API.
@@ -32,14 +32,14 @@
*
* \subsection Organization
*
- * The functions documented here are actually subdivided into three
+ * 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
+ * The routines in this library are described in \ref decfuncs and
* \ref basefuncs.
* - <tt>libtheora</tt> contains the \ref oldfuncs.
*
@@ -168,7 +168,7 @@
typedef th_img_plane th_ycbcr_buffer[3];
/**Theora bitstream information.
- * This contains the basic playback parameters for a stream, and corresponds to
+ * 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().
Modified: trunk/theora/include/theora/theora.h
===================================================================
--- trunk/theora/include/theora/theora.h 2011-01-19 06:25:41 UTC (rev 17786)
+++ trunk/theora/include/theora/theora.h 2011-01-20 23:00:15 UTC (rev 17787)
@@ -34,41 +34,41 @@
*
* \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 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.
*
* libtheora is the reference implementation for
* <a href="http://www.theora.org/">Theora</a>, a free video codec.
* 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>.
- *
+ *
* \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 or
- * need to be embedded in an Ogg stream. Use
- * <a href="http://xiph.org/ogg/">libogg</a> or
+ * need to be embedded in an Ogg stream. Use
+ * <a href="http://xiph.org/ogg/">libogg</a> or
* <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a>
* to extract/package these packets.
*
* \section decoding Decoding Process
*
* Decoding can be separated into the following steps:
- * -# initialise theora_info and theora_comment structures using
+ * -# initialise theora_info and theora_comment structures using
* theora_info_init() and theora_comment_init():
\verbatim
theora_info info;
theora_comment comment;
-
+
theora_info_init(&info);
theora_comment_init(&comment);
\endverbatim
- * -# retrieve header packets from Ogg stream (there should be 3) and decode
- * into theora_info and theora_comment structures using
- * theora_decode_header(). See \ref identification for more information on
+ * -# retrieve header packets from Ogg stream (there should be 3) and decode
+ * into theora_info and theora_comment structures using
+ * theora_decode_header(). See \ref identification for more information on
* identifying which packets are theora packets.
\verbatim
int i;
@@ -79,14 +79,14 @@
}
\endverbatim
* -# initialise the decoder based on the information retrieved into the
- * theora_info struct by theora_decode_header(). You will need a
+ * theora_info struct by theora_decode_header(). You will need a
* theora_state struct.
\verbatim
theora_state state;
-
+
theora_decode_init(&state, &info);
\endverbatim
- * -# pass in packets and retrieve decoded frames! See the yuv_buffer
+ * -# pass in packets and retrieve decoded frames! See the yuv_buffer
* documentation for information on how to retrieve raw YUV data.
\verbatim
yuf_buffer buffer;
@@ -96,20 +96,20 @@
theora_decode_YUVout(&state, &buffer);
}
\endverbatim
- *
*
+ *
* \subsection identification Identifying Theora Packets
*
- * All streams inside an Ogg file have a unique serial_no attached to the
- * stream. Typically, you will want to
- * - retrieve the serial_no for each b_o_s (beginning of stream) page
- * encountered within the Ogg file;
- * - test the first (only) packet on that page to determine if it is a theora
+ * All streams inside an Ogg file have a unique serial_no attached to the
+ * stream. Typically, you will want to
+ * - retrieve the serial_no for each b_o_s (beginning of stream) page
+ * encountered within the Ogg file;
+ * - test the first (only) packet on that page to determine if it is a theora
* 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.
- *
- * 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
* checking beyond whether a header bit is present. Instead, use the
* theora_decode_header() function and check the return value; or examine the
@@ -124,9 +124,9 @@
* 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
* 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
- * 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
* the decoder may need to be cropped for display.
*
@@ -135,8 +135,8 @@
* are ordered from left to right.
*
* During decode, the yuv_buffer struct is allocated by the user, but all
- * fields (including luma and chroma pointers) are filled by the library.
- * These pointers address library-internal memory and their contents should
+ * fields (including luma and chroma pointers) are filled by the library.
+ * These pointers address library-internal memory and their contents should
* not be modified.
*
* Conversely, during encode the user allocates the struct and fills out all
@@ -186,7 +186,7 @@
* Theora bitstream info.
* Contains the basic playback parameters for a stream,
* corresponding to the initial 'info' header packet.
- *
+ *
* Encoded theora frames must be a multiple of 16 in width and height.
* To handle other frame sizes, a crop rectangle is specified in
* frame_height and frame_width, offset_x and * offset_y. The offset
@@ -198,7 +198,7 @@
* fraction. Aspect ratio is also stored as a rational fraction, and
* refers to the aspect ratio of the frame pixels, not of the
* overall frame itself.
- *
+ *
* See <a href="http://svn.xiph.org/trunk/theora/examples/encoder_example.c">
* examples/encoder_example.c</a> for usage examples of the
* other paramters and good default settings for the encoder parameters.
@@ -253,14 +253,14 @@
} theora_state;
-/**
+/**
* Comment header metadata.
*
* This structure holds the in-stream metadata corresponding to
* the 'comment' header packet.
*
* Meta data is stored as a series of (tag, value) pairs, in
- * length-encoded string vectors. The first occurence of the
+ * length-encoded string vectors. The first occurence of the
* '=' character delimits the tag and value. A particular tag
* may occur more than once. The character set encoding for
* the strings is always UTF-8, but the tag names are limited
@@ -285,7 +285,7 @@
/* \anchor decctlcodes_old
* These are the available request codes for theora_control()
* when called with a decoder instance.
- * By convention decoder control codes are odd, to distinguish
+ * By convention decoder control codes are odd, to distinguish
* them from \ref encctlcodes_old "encoder control codes" which
* are even.
*
@@ -306,7 +306,7 @@
#define TH_DECCTL_GET_PPLEVEL_MAX (1)
/**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
* compressed stream. This must be a value between zero (off)
* and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
*/
@@ -345,9 +345,9 @@
* \param[in] buf #th_quant_info
* \retval OC_FAULT \a theora_state is <tt>NULL</tt>.
* \retval OC_EINVAL Encoding has already begun, the quantization parameters
- * are not acceptable to this version of the encoder,
- * \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
+ * are not acceptable to this version of the encoder,
+ * \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_quant_info)</tt>.
* \retval OC_IMPL Not supported by this implementation.*/
#define TH_ENCCTL_SET_QUANT_PARAMS (2)
@@ -424,7 +424,7 @@
#define OC_NEWPACKET -25 /**< Packet is an (ignorable) unhandled extension */
#define OC_DUPFRAME 1 /**< Packet is a dropped frame */
-/**
+/**
* Retrieve a human-readable string to identify the encoder vendor and version.
* \returns A version string.
*/
@@ -462,7 +462,7 @@
extern int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv);
/**
- * Request the next packet of encoded video.
+ * Request the next packet of encoded video.
* The encoded data is placed in a user-provided ogg_packet structure.
* \param t A theora_state handle previously initialized for encoding.
* \param last_p whether this is the last packet the encoder should produce.
@@ -581,8 +581,8 @@
* \param th A theora_state handle previously initialized for decoding.
* \param yuv A yuv_buffer in which libtheora should place the decoded data.
* Note that the buffer struct itself is allocated by the user, but
- * that the luma and chroma pointers will be filled in by the
- * library. Also note that these luma and chroma regions should be
+ * that the luma and chroma pointers will be filled in by the
+ * library. Also note that these luma and chroma regions should be
* considered read-only by the user.
* \retval 0 Success
*/
@@ -617,22 +617,22 @@
/**
* Report the granulepos shift radix
*
- * When embedded in Ogg, Theora uses a two-part granulepos,
+ * When embedded in Ogg, Theora uses a two-part granulepos,
* splitting the 64-bit field into two pieces. The more-significant
* section represents the frame count at the last keyframe,
* and the less-significant section represents the count of
* frames since the last keyframe. In this way the overall
* field is still non-decreasing with time, but usefully encodes
* a pointer to the last keyframe, which is necessary for
- * correctly restarting decode after a seek.
+ * correctly restarting decode after a seek.
*
* This function reports the number of bits used to represent
* the distance to the last keyframe, and thus how the granulepos
* field must be shifted or masked to obtain the two parts.
- *
+ *
* Since libtheora returns compressed data in an ogg_packet
* structure, this may be generally useful even if the Theora
- * packets are not being used in an Ogg container.
+ * packets are not being used in an Ogg container.
*
* \param ti A previously initialized theora_info struct
* \returns The bit shift dividing the two granulepos fields
@@ -644,7 +644,7 @@
/**
* Convert a granulepos to an absolute frame index, starting at 0.
* The granulepos is interpreted in the context of a given theora_state handle.
- *
+ *
* Note that while the granulepos encodes the frame count (i.e. starting
* from 1) this call returns the frame index, starting from zero. Thus
* One can calculate the presentation time by multiplying the index by
@@ -671,7 +671,7 @@
* be displayed.
* It is not the presentation time.
* \retval -1. The given granulepos is undefined (i.e. negative), or
- * \retval -1. The function has been disabled because floating
+ * \retval -1. The function has been disabled because floating
* point support is not available.
*/
extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos);
@@ -699,7 +699,7 @@
/**
* Initialize an allocated theora_comment structure
- * \param tc An allocated theora_comment structure
+ * \param tc An allocated theora_comment structure
**/
extern void theora_comment_init(theora_comment *tc);
@@ -720,7 +720,7 @@
/**
* Add a comment to an initialized theora_comment structure.
* \param tc A previously initialized theora comment structure
- * \param tag A null-terminated string containing the tag
+ * \param tag A null-terminated string containing the tag
* associated with the comment.
* \param value The corresponding value as a null-terminated string
*
@@ -752,9 +752,9 @@
* \param tc An initialized theora_comment structure
* \param tag The tag to look up
* \returns The number on instances of a particular tag.
- *
+ *
* Call this first when querying for a specific tag and then interate
- * over the number of instances with separate calls to
+ * over the number of instances with separate calls to
* theora_comment_query() to retrieve all instances in order.
**/
extern int theora_comment_query_count(theora_comment *tc, char *tag);
@@ -769,7 +769,7 @@
* This is used to provide advanced control the encoding process.
* \param th A #theora_state handle.
* \param req The control code to process.
- * See \ref encctlcodes_old "the list of available
+ * See \ref encctlcodes_old "the list of available
* control codes" for details.
* \param buf The parameters for this control code.
* \param buf_sz The size of the parameter buffer.*/
Modified: trunk/theora/include/theora/theoradec.h
===================================================================
--- trunk/theora/include/theora/theoradec.h 2011-01-19 06:25:41 UTC (rev 17786)
+++ trunk/theora/include/theora/theoradec.h 2011-01-20 23:00:15 UTC (rev 17787)
@@ -171,7 +171,7 @@
/**\defgroup decfuncs Functions for Decoding*/
/*@{*/
/**\name Functions for decoding
- * You must link to <tt>libtheoradec</tt> if you use any of the
+ * You must link to <tt>libtheoradec</tt> if you use any of the
* functions in this section.
*
* The functions are listed in the order they are used in a typical decode.
Modified: trunk/theora/include/theora/theoraenc.h
===================================================================
--- trunk/theora/include/theora/theoraenc.h 2011-01-19 06:25:41 UTC (rev 17786)
+++ trunk/theora/include/theora/theoraenc.h 2011-01-20 23:00:15 UTC (rev 17787)
@@ -58,7 +58,7 @@
*
* \param[in] _buf #th_quant_info
* \retval TH_EFAULT \a _enc is <tt>NULL</tt>.
- * \retval TH_EINVAL Encoding has already begun, \a _buf is
+ * \retval TH_EINVAL Encoding has already begun, \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_quant_info)</tt>.
@@ -495,7 +495,7 @@
* picture offsets may require an unexpected chroma plane size,
* and their use is generally discouraged, as they will not be
* well-supported by players and other media frameworks.
- * See Section 4.4 of
+ * See Section 4.4 of
* <a href="http://www.theora.org/doc/Theora.pdf">the Theora
* specification</a> for details if you wish to use them anyway.
* \retval 0 Success.
More information about the commits
mailing list