src/lib/doslib/ext/vorbtool/theora.h

   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-2003                *
   9  * by the Xiph.Org Foundation http://www.xiph.org/                  *
  10  *                                                                  *
  11  ********************************************************************
  12
  13   function:
  14   last mod: $Id: theora.h 16826 2010-01-27 04:16:24Z xiphmont $
  15
  16  ********************************************************************/
  17
  18 #include <ext/libogg/ogg.h>
  19
  20 /**
  21  * A Colorspace.
  22  */
  23 typedef enum {
  24   OC_CS_UNSPECIFIED,    /**< the colorspace is unknown or unspecified */
  25   OC_CS_ITU_REC_470M,   /**< best option for 'NTSC' content */
  26   OC_CS_ITU_REC_470BG,  /**< best option for 'PAL' content */
  27   OC_CS_NSPACES         /* mark the end of the defined colorspaces */
  28 } theora_colorspace;
  29
  30 /**
  31  * A Chroma subsampling
  32  *
  33  * These enumerate the available chroma subsampling options supported
  34  * by the theora format. See Section 4.4 of the specification for
  35  * exact definitions.
  36  */
  37 typedef enum {
  38   OC_PF_420,    /**< Chroma subsampling by 2 in each direction (4:2:0) */
  39   OC_PF_RSVD,   /**< reserved value */
  40   OC_PF_422,    /**< Horizonatal chroma subsampling by 2 (4:2:2) */
  41   OC_PF_444,    /**< No chroma subsampling at all (4:4:4) */
  42 } theora_pixelformat;
  43
  44 /**
  45  * Theora bitstream info.
  46  * Contains the basic playback parameters for a stream,
  47  * corresponds to the initial 'info' header packet.
  48  *
  49  * Encoded theora frames must be a multiple of 16 is size;
  50  * this is what the width and height members represent. To
  51  * handle other sizes, a crop rectangle is specified in
  52  * frame_height and frame_width, offset_x and offset_y. The
  53  * offset and size should still be a power of 2 to avoid
  54  * chroma sampling shifts.
  55  *
  56  * Frame rate, in frames per second is stored as a rational
  57  * fraction. So is the aspect ratio. Note that this refers
  58  * to the aspect ratio of the frame pixels, not of the
  59  * overall frame itself.
  60  *
  61  * see the example code for use of the other parameters and
  62  * good default settings for the encoder parameters.
  63  */
  64 typedef struct {
  65   ogg_uint32_t  width;
  66   ogg_uint32_t  height;
  67   ogg_uint32_t  frame_width;
  68   ogg_uint32_t  frame_height;
  69   ogg_uint32_t  offset_x;
  70   ogg_uint32_t  offset_y;
  71   ogg_uint32_t  fps_numerator;
  72   ogg_uint32_t  fps_denominator;
  73   ogg_uint32_t  aspect_numerator;
  74   ogg_uint32_t  aspect_denominator;
  75   theora_colorspace colorspace;
  76   int           target_bitrate;
  77   int           quality;  /**< nominal quality setting, 0-63 */
  78   int           quick_p;  /**< quick encode/decode */
  79
  80   /* decode only */
  81   unsigned char version_major;
  82   unsigned char version_minor;
  83   unsigned char version_subminor;
  84
  85   int granule_shift;
  86
  87   void *codec_setup;
  88
  89   /* encode only */
  90   int           dropframes_p;
  91   int           keyframe_auto_p;
  92   ogg_uint32_t  keyframe_frequency;
  93   ogg_uint32_t  keyframe_data_target_bitrate;
  94   ogg_int32_t   keyframe_auto_threshold;
  95   ogg_uint32_t  keyframe_mindistance;
  96   ogg_int32_t   noise_sensitivity;
  97   ogg_int32_t   sharpness;
  98
  99   theora_pixelformat pixelformat;
 100
 101 } theora_info;
 102
 103 /**
 104  * Comment header metadata.
 105  *
 106  * This structure holds the in-stream metadata corresponding to
 107  * the 'comment' header packet.
 108  *
 109  * Meta data is stored as a series of (tag, value) pairs, in
 110  * length-encoded string vectors. The first occurence of the
 111  * '=' character delimits the tag and value. A particular tag
 112  * may occur more than once. The character set encoding for
 113  * the strings is always utf-8, but the tag names are limited
 114  * to case-insensitive ascii. See the spec for details.
 115  *
 116  * In filling in this structure, theora_decode_header() will
 117  * null-terminate the user_comment strings for safety. However,
 118  * the bitstream format itself treats them as 8-bit clean,
 119  * and so the length array should be treated as authoritative
 120  * for their length.
 121  */
 122 typedef struct theora_comment{
 123   char **user_comments;         /**< an array of comment string vectors */
 124   int   *comment_lengths;       /**< an array of corresponding string vector lengths in bytes */
 125   int    comments;              /**< the total number of comment string vectors */
 126   char  *vendor;                /**< the vendor string identifying the encoder, null terminated */
 127
 128 } theora_comment;
 129
 130 #define OC_FAULT       -1       /**< general failure */
 131 #define OC_EINVAL      -10      /**< library encountered invalid internal data */
 132 #define OC_DISABLED    -11      /**< requested action is disabled */
 133 #define OC_BADHEADER   -20      /**< header packet was corrupt/invalid */
 134 #define OC_NOTFORMAT   -21      /**< packet is not a theora packet */
 135 #define OC_VERSION     -22      /**< bitstream version is not handled */
 136 #define OC_IMPL        -23      /**< feature or action not implemented */
 137 #define OC_BADPACKET   -24      /**< packet is corrupt */
 138 #define OC_NEWPACKET   -25      /**< packet is an (ignorable) unhandled extension */
 139
 140 /**
 141  * Decode an Ogg packet, with the expectation that the packet contains
 142  * an initial header, comment data or codebook tables.
 143  *
 144  * \param ci A theora_info structure to fill. This must have been previously
 145  *           initialized with theora_info_init(). If \a op contains an initial
 146  *           header, theora_decode_header() will fill \a ci with the
 147  *           parsed header values. If \a op contains codebook tables,
 148  *           theora_decode_header() will parse these and attach an internal
 149  *           representation to \a ci->codec_setup.
 150  * \param cc A theora_comment structure to fill. If \a op contains comment
 151  *           data, theora_decode_header() will fill \a cc with the parsed
 152  *           comments.
 153  * \param op An ogg_packet structure which you expect contains an initial
 154  *           header, comment data or codebook tables.
 155  *
 156  * \retval OC_BADHEADER \a op is NULL; OR the first byte of \a op->packet
 157  *                      has the signature of an initial packet, but op is
 158  *                      not a b_o_s packet; OR this packet has the signature
 159  *                      of an initial header packet, but an initial header
 160  *                      packet has already been seen; OR this packet has the
 161  *                      signature of a comment packet, but the initial header
 162  *                      has not yet been seen; OR this packet has the signature
 163  *                      of a comment packet, but contains invalid data; OR
 164  *                      this packet has the signature of codebook tables,
 165  *                      but the initial header or comments have not yet
 166  *                      been seen; OR this packet has the signature of codebook
 167  *                      tables, but contains invalid data;
 168  *                      OR the stream being decoded has a compatible version
 169  *                      but this packet does not have the signature of a
 170  *                      theora initial header, comments, or codebook packet
 171  * \retval OC_VERSION   The packet data of \a op is an initial header with
 172  *                      a version which is incompatible with this version of
 173  *                      libtheora.
 174  * \retval OC_NEWPACKET the stream being decoded has an incompatible (future)
 175  *                      version and contains an unknown signature.
 176  * \retval 0            Success
 177  *
 178  * \note The normal usage is that theora_decode_header() be called on the
 179  *       first three packets of a theora logical bitstream in succession.
 180  */
 181 extern int theora_decode_header(theora_info *ci, theora_comment *cc,
 182                                 ogg_packet *op);
 183
 184 void theora_info_clear(theora_info *c);
 185 void theora_comment_clear(theora_comment *tc);