PageRenderTime 62ms CodeModel.GetById 10ms app.highlight 30ms RepoModel.GetById 2ms app.codeStats 0ms

/media/libtheora/include/theora/codec.h

http://github.com/zpao/v8monkey
C Header | 591 lines | 96 code | 34 blank | 461 comment | 0 complexity | c10b2e73e1eaaf84664d7fd2d3bf0347 MD5 | raw file
  1/********************************************************************
  2 *                                                                  *
  3 * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE.   *
  4 * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
  5 * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
  6 * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
  7 *                                                                  *
  8 * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009                *
  9 * by the Xiph.Org Foundation http://www.xiph.org/                  *
 10 *                                                                  *
 11 ********************************************************************
 12
 13  function:
 14  last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
 15
 16 ********************************************************************/
 17
 18/**\mainpage
 19 * 
 20 * \section intro Introduction
 21 *
 22 * This is the documentation for <tt>libtheora</tt> C API.
 23 * The current reference
 24 * implementation for <a href="http://www.theora.org/">Theora</a>, a free,
 25 * patent-unencumbered video codec.
 26 * Theora is derived from On2's VP3 codec with additional features and
 27 *  integration with Ogg multimedia formats by
 28 *  <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>.
 29 * Complete documentation of the format itself is available in
 30 * <a href="http://www.theora.org/doc/Theora.pdf">the Theora
 31 *  specification</a>.
 32 *
 33 * \subsection Organization
 34 *
 35 * The functions documented here are actually subdivided into three 
 36 * separate libraries:
 37 * - <tt>libtheoraenc</tt> contains the encoder interface,
 38 *   described in \ref encfuncs.
 39 * - <tt>libtheoradec</tt> contains the decoder interface and
 40 *   routines shared with the encoder.
 41 *   You must also link to this if you link to <tt>libtheoraenc</tt>.
 42 *   The routines in this library are described in \ref decfuncs and 
 43 *   \ref basefuncs.
 44 * - <tt>libtheora</tt> contains the \ref oldfuncs.
 45 *
 46 * New code should link to <tt>libtheoradec</tt> and, if using encoder
 47 * features, <tt>libtheoraenc</tt>. Together these two export both
 48 * the standard and the legacy API, so this is all that is needed by
 49 * any code. The older <tt>libtheora</tt> library is provided just for
 50 * compatibility with older build configurations.
 51 *
 52 * In general the recommended 1.x API symbols can be distinguished
 53 * by their <tt>th_</tt> or <tt>TH_</tt> namespace prefix.
 54 * The older, legacy API uses <tt>theora_</tt> or <tt>OC_</tt>
 55 * prefixes instead.
 56 */
 57
 58/**\file
 59 * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API.
 60 * You don't need to include this directly.*/
 61
 62#if !defined(_O_THEORA_CODEC_H_)
 63# define _O_THEORA_CODEC_H_ (1)
 64# include <ogg/ogg.h>
 65
 66#if defined(__cplusplus)
 67extern "C" {
 68#endif
 69
 70
 71
 72/**\name Return codes*/
 73/*@{*/
 74/**An invalid pointer was provided.*/
 75#define TH_EFAULT     (-1)
 76/**An invalid argument was provided.*/
 77#define TH_EINVAL     (-10)
 78/**The contents of the header were incomplete, invalid, or unexpected.*/
 79#define TH_EBADHEADER (-20)
 80/**The header does not belong to a Theora stream.*/
 81#define TH_ENOTFORMAT (-21)
 82/**The bitstream version is too high.*/
 83#define TH_EVERSION   (-22)
 84/**The specified function is not implemented.*/
 85#define TH_EIMPL      (-23)
 86/**There were errors in the video data packet.*/
 87#define TH_EBADPACKET (-24)
 88/**The decoded packet represented a dropped frame.
 89   The player can continue to display the current frame, as the contents of the
 90    decoded frame buffer have not changed.*/
 91#define TH_DUPFRAME   (1)
 92/*@}*/
 93
 94/**The currently defined color space tags.
 95 * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
 96 *  specification</a>, Chapter 4, for exact details on the meaning
 97 *  of each of these color spaces.*/
 98typedef enum{
 99  /**The color space was not specified at the encoder.
100      It may be conveyed by an external means.*/
101  TH_CS_UNSPECIFIED,
102  /**A color space designed for NTSC content.*/
103  TH_CS_ITU_REC_470M,
104  /**A color space designed for PAL/SECAM content.*/
105  TH_CS_ITU_REC_470BG,
106  /**The total number of currently defined color spaces.*/
107  TH_CS_NSPACES
108}th_colorspace;
109
110/**The currently defined pixel format tags.
111 * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
112 *  specification</a>, Section 4.4, for details on the precise sample
113 *  locations.*/
114typedef enum{
115  /**Chroma decimation by 2 in both the X and Y directions (4:2:0).
116     The Cb and Cr chroma planes are half the width and half the
117      height of the luma plane.*/
118  TH_PF_420,
119  /**Currently reserved.*/
120  TH_PF_RSVD,
121  /**Chroma decimation by 2 in the X direction (4:2:2).
122     The Cb and Cr chroma planes are half the width of the luma plane, but full
123      height.*/
124  TH_PF_422,
125  /**No chroma decimation (4:4:4).
126     The Cb and Cr chroma planes are full width and full height.*/
127  TH_PF_444,
128  /**The total number of currently defined pixel formats.*/
129  TH_PF_NFORMATS
130}th_pixel_fmt;
131
132
133
134/**A buffer for a single color plane in an uncompressed image.
135 * This contains the image data in a left-to-right, top-down format.
136 * Each row of pixels is stored contiguously in memory, but successive
137 *  rows need not be.
138 * Use \a stride to compute the offset of the next row.
139 * The encoder accepts both positive \a stride values (top-down in memory)
140 *  and negative (bottom-up in memory).
141 * The decoder currently always generates images with positive strides.*/
142typedef struct{
143  /**The width of this plane.*/
144  int            width;
145  /**The height of this plane.*/
146  int            height;
147  /**The offset in bytes between successive rows.*/
148  int            stride;
149  /**A pointer to the beginning of the first row.*/
150  unsigned char *data;
151}th_img_plane;
152
153/**A complete image buffer for an uncompressed frame.
154 * The chroma planes may be decimated by a factor of two in either
155 *  direction, as indicated by th_info#pixel_fmt.
156 * The width and height of the Y' plane must be multiples of 16.
157 * They may need to be cropped for display, using the rectangle
158 *  specified by th_info#pic_x, th_info#pic_y, th_info#pic_width,
159 *  and th_info#pic_height.
160 * All samples are 8 bits.
161 * \note The term YUV often used to describe a colorspace is ambiguous.
162 * The exact parameters of the RGB to YUV conversion process aside, in
163 *  many contexts the U and V channels actually have opposite meanings.
164 * To avoid this confusion, we are explicit: the name of the color
165 *  channels are Y'CbCr, and they appear in that order, always.
166 * The prime symbol denotes that the Y channel is non-linear.
167 * Cb and Cr stand for "Chroma blue" and "Chroma red", respectively.*/
168typedef th_img_plane th_ycbcr_buffer[3];
169
170/**Theora bitstream information.
171 * This contains the basic playback parameters for a stream, and corresponds to 
172 *  the initial 'info' header packet.
173 * To initialize an encoder, the application fills in this structure and
174 *  passes it to th_encode_alloc().
175 * A default encoding mode is chosen based on the values of the #quality and
176 *  #target_bitrate fields.
177 * On decode, it is filled in by th_decode_headerin(), and then passed to
178 *  th_decode_alloc().
179 *
180 * Encoded Theora frames must be a multiple of 16 in size;
181 *  this is what the #frame_width and #frame_height members represent.
182 * To handle arbitrary picture sizes, a crop rectangle is specified in the
183 *  #pic_x, #pic_y, #pic_width and #pic_height members.
184 *
185 * All frame buffers contain pointers to the full, padded frame.
186 * However, the current encoder <em>will not</em> reference pixels outside of
187 *  the cropped picture region, and the application does not need to fill them
188 *  in.
189 * The decoder <em>will</em> allocate storage for a full frame, but the
190 *  application <em>should not</em> rely on the padding containing sensible
191 *  data.
192 *
193 * It is also generally recommended that the offsets and sizes should still be
194 *  multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampled.
195 * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
196 *  specification</a>, Section 4.4, for more details.
197 *
198 * Frame rate, in frames per second, is stored as a rational fraction, as is
199 *  the pixel aspect ratio.
200 * Note that this refers to the aspect ratio of the individual pixels, not of
201 *  the overall frame itself.
202 * The frame aspect ratio can be computed from pixel aspect ratio using the
203 *  image dimensions.*/
204typedef struct{
205  /**\name Theora version
206   * Bitstream version information.*/
207  /*@{*/
208  unsigned char version_major;
209  unsigned char version_minor;
210  unsigned char version_subminor;
211  /*@}*/
212  /**The encoded frame width.
213   * This must be a multiple of 16, and less than 1048576.*/
214  ogg_uint32_t  frame_width;
215  /**The encoded frame height.
216   * This must be a multiple of 16, and less than 1048576.*/
217  ogg_uint32_t  frame_height;
218  /**The displayed picture width.
219   * This must be no larger than width.*/
220  ogg_uint32_t  pic_width;
221  /**The displayed picture height.
222   * This must be no larger than height.*/
223  ogg_uint32_t  pic_height;
224  /**The X offset of the displayed picture.
225   * This must be no larger than #frame_width-#pic_width or 255, whichever is
226   *  smaller.*/
227  ogg_uint32_t  pic_x;
228  /**The Y offset of the displayed picture.
229   * This must be no larger than #frame_height-#pic_height, and
230   *  #frame_height-#pic_height-#pic_y must be no larger than 255.
231   * This slightly funny restriction is due to the fact that the offset is
232   *  specified from the top of the image for consistency with the standard
233   *  graphics left-handed coordinate system used throughout this API, while
234   *  it is stored in the encoded stream as an offset from the bottom.*/
235  ogg_uint32_t  pic_y;
236  /**\name Frame rate
237   * The frame rate, as a fraction.
238   * If either is 0, the frame rate is undefined.*/
239  /*@{*/
240  ogg_uint32_t  fps_numerator;
241  ogg_uint32_t  fps_denominator;
242  /*@}*/
243  /**\name Aspect ratio
244   * The aspect ratio of the pixels.
245   * If either value is zero, the aspect ratio is undefined.
246   * If not specified by any external means, 1:1 should be assumed.
247   * The aspect ratio of the full picture can be computed as
248   * \code
249   *  aspect_numerator*pic_width/(aspect_denominator*pic_height).
250   * \endcode */
251  /*@{*/
252  ogg_uint32_t  aspect_numerator;
253  ogg_uint32_t  aspect_denominator;
254  /*@}*/
255  /**The color space.*/
256  th_colorspace colorspace;
257  /**The pixel format.*/
258  th_pixel_fmt  pixel_fmt;
259  /**The target bit-rate in bits per second.
260     If initializing an encoder with this struct, set this field to a non-zero
261      value to activate CBR encoding by default.*/
262  int           target_bitrate;
263  /**The target quality level.
264     Valid values range from 0 to 63, inclusive, with higher values giving
265      higher quality.
266     If initializing an encoder with this struct, and #target_bitrate is set
267      to zero, VBR encoding at this quality will be activated by default.*/
268  /*Currently this is set so that a qi of 0 corresponds to distortions of 24
269     times the JND, and each increase by 16 halves that value.
270    This gives us fine discrimination at low qualities, yet effective rate
271     control at high qualities.
272    The qi value 63 is special, however.
273    For this, the highest quality, we use one half of a JND for our threshold.
274    Due to the lower bounds placed on allowable quantizers in Theora, we will
275     not actually be able to achieve quality this good, but this should
276     provide as close to visually lossless quality as Theora is capable of.
277    We could lift the quantizer restrictions without breaking VP3.1
278     compatibility, but this would result in quantized coefficients that are
279     too large for the current bitstream to be able to store.
280    We'd have to redesign the token syntax to store these large coefficients,
281     which would make transcoding complex.*/
282  int           quality;
283  /**The amount to shift to extract the last keyframe number from the granule
284   *  position.
285   * This can be at most 31.
286   * th_info_init() will set this to a default value (currently <tt>6</tt>,
287   *  which is good for streaming applications), but you can set it to 0 to
288   *  make every frame a keyframe.
289   * The maximum distance between key frames is
290   *  <tt>1<<#keyframe_granule_shift</tt>.
291   * The keyframe frequency can be more finely controlled with
292   *  #TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, which can also be adjusted
293   *  during encoding (for example, to force the next frame to be a keyframe),
294   *  but it cannot be set larger than the amount permitted by this field after
295   *  the headers have been output.*/
296  int           keyframe_granule_shift;
297}th_info;
298
299/**The comment information.
300 *
301 * This structure holds the in-stream metadata corresponding to
302 *  the 'comment' header packet.
303 * The comment header is meant to be used much like someone jotting a quick
304 *  note on the label of a video.
305 * It should be a short, to the point text note that can be more than a couple
306 *  words, but not more than a short paragraph.
307 *
308 * The metadata is stored as a series of (tag, value) pairs, in
309 *  length-encoded string vectors.
310 * The first occurrence of the '=' character delimits the tag and value.
311 * A particular tag may occur more than once, and order is significant.
312 * The character set encoding for the strings is always UTF-8, but the tag
313 *  names are limited to ASCII, and treated as case-insensitive.
314 * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
315 *  specification</a>, Section 6.3.3 for details.
316 *
317 * In filling in this structure, th_decode_headerin() will null-terminate
318 *  the user_comment strings for safety.
319 * However, the bitstream format itself treats them as 8-bit clean vectors,
320 *  possibly containing null characters, and so the length array should be
321 *  treated as their authoritative length.
322 */
323typedef struct th_comment{
324  /**The array of comment string vectors.*/
325  char **user_comments;
326  /**An array of the corresponding length of each vector, in bytes.*/
327  int   *comment_lengths;
328  /**The total number of comment strings.*/
329  int    comments;
330  /**The null-terminated vendor string.
331     This identifies the software used to encode the stream.*/
332  char  *vendor;
333}th_comment;
334
335
336
337/**A single base matrix.*/
338typedef unsigned char th_quant_base[64];
339
340/**A set of \a qi ranges.*/
341typedef struct{
342  /**The number of ranges in the set.*/
343  int                  nranges;
344  /**The size of each of the #nranges ranges.
345     These must sum to 63.*/
346  const int           *sizes;
347  /**#nranges <tt>+1</tt> base matrices.
348     Matrices \a i and <tt>i+1</tt> form the endpoints of range \a i.*/
349  const th_quant_base *base_matrices;
350}th_quant_ranges;
351
352/**A complete set of quantization parameters.
353   The quantizer for each coefficient is calculated as:
354   \code
355    Q=MAX(MIN(qmin[qti][ci!=0],scale[ci!=0][qi]*base[qti][pli][qi][ci]/100),
356     1024).
357   \endcode
358
359   \a qti is the quantization type index: 0 for intra, 1 for inter.
360   <tt>ci!=0</tt> is 0 for the DC coefficient and 1 for AC coefficients.
361   \a qi is the quality index, ranging between 0 (low quality) and 63 (high
362    quality).
363   \a pli is the color plane index: 0 for Y', 1 for Cb, 2 for Cr.
364   \a ci is the DCT coefficient index.
365   Coefficient indices correspond to the normal 2D DCT block
366    ordering--row-major with low frequencies first--\em not zig-zag order.
367
368   Minimum quantizers are constant, and are given by:
369   \code
370   qmin[2][2]={{4,2},{8,4}}.
371   \endcode
372
373   Parameters that can be stored in the bitstream are as follows:
374    - The two scale matrices ac_scale and dc_scale.
375      \code
376      scale[2][64]={dc_scale,ac_scale}.
377      \endcode
378    - The base matrices for each \a qi, \a qti and \a pli (up to 384 in all).
379      In order to avoid storing a full 384 base matrices, only a sparse set of
380       matrices are stored, and the rest are linearly interpolated.
381      This is done as follows.
382      For each \a qti and \a pli, a series of \a n \a qi ranges is defined.
383      The size of each \a qi range can vary arbitrarily, but they must sum to
384       63.
385      Then, <tt>n+1</tt> matrices are specified, one for each endpoint of the
386       ranges.
387      For interpolation purposes, each range's endpoints are the first \a qi
388       value it contains and one past the last \a qi value it contains.
389      Fractional values are rounded to the nearest integer, with ties rounded
390       away from zero.
391
392      Base matrices are stored by reference, so if the same matrices are used
393       multiple times, they will only appear once in the bitstream.
394      The bitstream is also capable of omitting an entire set of ranges and
395       its associated matrices if they are the same as either the previous
396       set (indexed in row-major order) or if the inter set is the same as the
397       intra set.
398
399    - Loop filter limit values.
400      The same limits are used for the loop filter in all color planes, despite
401       potentially differing levels of quantization in each.
402
403   For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater
404    than <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must
405    be no greater than <tt>base[qti][pli][qi-1][ci]</tt>.
406   These two conditions ensure that the actual quantizer for a given \a qti,
407    \a pli, and \a ci does not increase as \a qi increases.
408   This is not required by the decoder.*/
409typedef struct{
410  /**The DC scaling factors.*/
411  ogg_uint16_t    dc_scale[64];
412  /**The AC scaling factors.*/
413  ogg_uint16_t    ac_scale[64];
414  /**The loop filter limit values.*/
415  unsigned char   loop_filter_limits[64];
416  /**The \a qi ranges for each \a ci and \a pli.*/
417  th_quant_ranges qi_ranges[2][3];
418}th_quant_info;
419
420
421
422/**The number of Huffman tables used by Theora.*/
423#define TH_NHUFFMAN_TABLES (80)
424/**The number of DCT token values in each table.*/
425#define TH_NDCT_TOKENS     (32)
426
427/**A Huffman code for a Theora DCT token.
428 * Each set of Huffman codes in a given table must form a complete, prefix-free
429 *  code.
430 * There is no requirement that all the tokens in a table have a valid code,
431 *  but the current encoder is not optimized to take advantage of this.
432 * If each of the five grouops of 16 tables does not contain at least one table
433 *  with a code for every token, then the encoder may fail to encode certain
434 *  frames.
435 * The complete table in the first group of 16 does not have to be in the same
436 *  place as the complete table in the other groups, but the complete tables in
437 *  the remaining four groups must all be in the same place.*/
438typedef struct{
439  /**The bit pattern for the code, with the LSbit of the pattern aligned in
440   *   the LSbit of the word.*/
441  ogg_uint32_t pattern;
442  /**The number of bits in the code.
443   * This must be between 0 and 32, inclusive.*/
444  int          nbits;
445}th_huff_code;
446
447
448
449/**\defgroup basefuncs Functions Shared by Encode and Decode*/
450/*@{*/
451/**\name Basic shared functions*/
452/*@{*/
453/**Retrieves a human-readable string to identify the library vendor and
454 *  version.
455 * \return the version string.*/
456extern const char *th_version_string(void);
457/**Retrieves the library version number.
458 * This is the highest bitstream version that the encoder library will produce,
459 *  or that the decoder library can decode.
460 * This number is composed of a 16-bit major version, 8-bit minor version
461 * and 8 bit sub-version, composed as follows:
462 * \code
463 * (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)
464 * \endcode
465 * \return the version number.*/
466extern ogg_uint32_t th_version_number(void);
467/**Converts a granule position to an absolute frame index, starting at
468 *  <tt>0</tt>.
469 * The granule position is interpreted in the context of a given
470 *  #th_enc_ctx or #th_dec_ctx handle (either will suffice).
471 * \param _encdec  A previously allocated #th_enc_ctx or #th_dec_ctx
472 *                  handle.
473 * \param _granpos The granule position to convert.
474 * \returns The absolute frame index corresponding to \a _granpos.
475 * \retval -1 The given granule position was invalid (i.e. negative).*/
476extern ogg_int64_t th_granule_frame(void *_encdec,ogg_int64_t _granpos);
477/**Converts a granule position to an absolute time in seconds.
478 * The granule position is interpreted in the context of a given
479 *  #th_enc_ctx or #th_dec_ctx handle (either will suffice).
480 * \param _encdec  A previously allocated #th_enc_ctx or #th_dec_ctx
481 *                  handle.
482 * \param _granpos The granule position to convert.
483 * \return The absolute time in seconds corresponding to \a _granpos.
484 *         This is the "end time" for the frame, or the latest time it should
485 *          be displayed.
486 *         It is not the presentation time.
487 * \retval -1 The given granule position was invalid (i.e. negative).*/
488extern double th_granule_time(void *_encdec,ogg_int64_t _granpos);
489/**Determines whether a Theora packet is a header or not.
490 * This function does no verification beyond checking the packet type bit, so
491 *  it should not be used for bitstream identification; use
492 *  th_decode_headerin() for that.
493 * As per the Theora specification, an empty (0-byte) packet is treated as a
494 *  data packet (a delta frame with no coded blocks).
495 * \param _op An <tt>ogg_packet</tt> containing encoded Theora data.
496 * \retval 1 The packet is a header packet
497 * \retval 0 The packet is a video data packet.*/
498extern int th_packet_isheader(ogg_packet *_op);
499/**Determines whether a theora packet is a key frame or not.
500 * This function does no verification beyond checking the packet type and
501 *  key frame bits, so it should not be used for bitstream identification; use
502 *  th_decode_headerin() for that.
503 * As per the Theora specification, an empty (0-byte) packet is treated as a
504 *  delta frame (with no coded blocks).
505 * \param _op An <tt>ogg_packet</tt> containing encoded Theora data.
506 * \retval 1  The packet contains a key frame.
507 * \retval 0  The packet contains a delta frame.
508 * \retval -1 The packet is not a video data packet.*/
509extern int th_packet_iskeyframe(ogg_packet *_op);
510/*@}*/
511
512
513/**\name Functions for manipulating header data*/
514/*@{*/
515/**Initializes a th_info structure.
516 * This should be called on a freshly allocated #th_info structure before
517 *  attempting to use it.
518 * \param _info The #th_info struct to initialize.*/
519extern void th_info_init(th_info *_info);
520/**Clears a #th_info structure.
521 * This should be called on a #th_info structure after it is no longer
522 *  needed.
523 * \param _info The #th_info struct to clear.*/
524extern void th_info_clear(th_info *_info);
525
526/**Initialize a #th_comment structure.
527 * This should be called on a freshly allocated #th_comment structure
528 *  before attempting to use it.
529 * \param _tc The #th_comment struct to initialize.*/
530extern void th_comment_init(th_comment *_tc);
531/**Add a comment to an initialized #th_comment structure.
532 * \note Neither th_comment_add() nor th_comment_add_tag() support
533 *  comments containing null values, although the bitstream format does
534 *  support them.
535 * To add such comments you will need to manipulate the #th_comment
536 *  structure directly.
537 * \param _tc      The #th_comment struct to add the comment to.
538 * \param _comment Must be a null-terminated UTF-8 string containing the
539 *                  comment in "TAG=the value" form.*/
540extern void th_comment_add(th_comment *_tc, char *_comment);
541/**Add a comment to an initialized #th_comment structure.
542 * \note Neither th_comment_add() nor th_comment_add_tag() support
543 *  comments containing null values, although the bitstream format does
544 *  support them.
545 * To add such comments you will need to manipulate the #th_comment
546 *  structure directly.
547 * \param _tc  The #th_comment struct to add the comment to.
548 * \param _tag A null-terminated string containing the tag  associated with
549 *              the comment.
550 * \param _val The corresponding value as a null-terminated string.*/
551extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val);
552/**Look up a comment value by its tag.
553 * \param _tc    An initialized #th_comment structure.
554 * \param _tag   The tag to look up.
555 * \param _count The instance of the tag.
556 *               The same tag can appear multiple times, each with a distinct
557 *                value, so an index is required to retrieve them all.
558 *               The order in which these values appear is significant and
559 *                should be preserved.
560 *               Use th_comment_query_count() to get the legal range for
561 *                the \a _count parameter.
562 * \return A pointer to the queried tag's value.
563 *         This points directly to data in the #th_comment structure.
564 *         It should not be modified or freed by the application, and
565 *          modifications to the structure may invalidate the pointer.
566 * \retval NULL If no matching tag is found.*/
567extern char *th_comment_query(th_comment *_tc,char *_tag,int _count);
568/**Look up the number of instances of a tag.
569 * Call this first when querying for a specific tag and then iterate over the
570 *  number of instances with separate calls to th_comment_query() to
571 *  retrieve all the values for that tag in order.
572 * \param _tc    An initialized #th_comment structure.
573 * \param _tag   The tag to look up.
574 * \return The number on instances of this particular tag.*/
575extern int th_comment_query_count(th_comment *_tc,char *_tag);
576/**Clears a #th_comment structure.
577 * This should be called on a #th_comment structure after it is no longer
578 *  needed.
579 * It will free all memory used by the structure members.
580 * \param _tc The #th_comment struct to clear.*/
581extern void th_comment_clear(th_comment *_tc);
582/*@}*/
583/*@}*/
584
585
586
587#if defined(__cplusplus)
588}
589#endif
590
591#endif