michael@0: /********************************************************************
michael@0:  *                                                                  *
michael@0:  * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE.   *
michael@0:  * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
michael@0:  * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
michael@0:  * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
michael@0:  *                                                                  *
michael@0:  * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009                *
michael@0:  * by the Xiph.Org Foundation http://www.xiph.org/                  *
michael@0:  *                                                                  *
michael@0:  ********************************************************************
michael@0: 
michael@0:   function:
michael@0:   last mod: $Id: theora.h,v 1.17 2003/12/06 18:06:19 arc Exp $
michael@0: 
michael@0:  ********************************************************************/
michael@0: 
michael@0: #ifndef _O_THEORA_H_
michael@0: #define _O_THEORA_H_
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: extern "C"
michael@0: {
michael@0: #endif /* __cplusplus */
michael@0: 
michael@0: #include <stddef.h>	/* for size_t */
michael@0: 
michael@0: #include <ogg/ogg.h>
michael@0: 
michael@0: /** \file
michael@0:  * The libtheora pre-1.0 legacy C API.
michael@0:  *
michael@0:  * \ingroup oldfuncs
michael@0:  *
michael@0:  * \section intro Introduction
michael@0:  *
michael@0:  * This is the documentation for the libtheora legacy C API, declared in 
michael@0:  * the theora.h header, which describes the old interface used before
michael@0:  * the 1.0 release. This API was widely deployed for several years and
michael@0:  * remains supported, but for new code we recommend the cleaner API 
michael@0:  * declared in theoradec.h and theoraenc.h.
michael@0:  *
michael@0:  * libtheora is the reference implementation for
michael@0:  * <a href="http://www.theora.org/">Theora</a>, a free video codec.
michael@0:  * Theora is derived from On2's VP3 codec with improved integration with
michael@0:  * Ogg multimedia formats by <a href="http://www.xiph.org/">Xiph.Org</a>.
michael@0:  * 
michael@0:  * \section overview Overview
michael@0:  *
michael@0:  * This library will both decode and encode theora packets to/from raw YUV 
michael@0:  * frames.  In either case, the packets will most likely either come from or
michael@0:  * need to be embedded in an Ogg stream.  Use 
michael@0:  * <a href="http://xiph.org/ogg/">libogg</a> or 
michael@0:  * <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a>
michael@0:  * to extract/package these packets.
michael@0:  *
michael@0:  * \section decoding Decoding Process
michael@0:  *
michael@0:  * Decoding can be separated into the following steps:
michael@0:  * -# initialise theora_info and theora_comment structures using 
michael@0:  *    theora_info_init() and theora_comment_init():
michael@0:  \verbatim
michael@0:  theora_info     info;
michael@0:  theora_comment  comment;
michael@0:    
michael@0:  theora_info_init(&info);
michael@0:  theora_comment_init(&comment);
michael@0:  \endverbatim
michael@0:  * -# retrieve header packets from Ogg stream (there should be 3) and decode 
michael@0:  *    into theora_info and theora_comment structures using 
michael@0:  *    theora_decode_header().  See \ref identification for more information on 
michael@0:  *    identifying which packets are theora packets.
michael@0:  \verbatim
michael@0:  int i;
michael@0:  for (i = 0; i < 3; i++)
michael@0:  {
michael@0:    (get a theora packet "op" from the Ogg stream)
michael@0:    theora_decode_header(&info, &comment, op);
michael@0:  }
michael@0:  \endverbatim
michael@0:  * -# initialise the decoder based on the information retrieved into the
michael@0:  *    theora_info struct by theora_decode_header().  You will need a 
michael@0:  *    theora_state struct.
michael@0:  \verbatim
michael@0:  theora_state state;
michael@0:  
michael@0:  theora_decode_init(&state, &info);
michael@0:  \endverbatim
michael@0:  * -# pass in packets and retrieve decoded frames!  See the yuv_buffer 
michael@0:  *    documentation for information on how to retrieve raw YUV data.
michael@0:  \verbatim
michael@0:  yuf_buffer buffer;
michael@0:  while (last packet was not e_o_s) {
michael@0:    (get a theora packet "op" from the Ogg stream)
michael@0:    theora_decode_packetin(&state, op);
michael@0:    theora_decode_YUVout(&state, &buffer);
michael@0:  }
michael@0:  \endverbatim
michael@0:  *  
michael@0:  *
michael@0:  * \subsection identification Identifying Theora Packets
michael@0:  *
michael@0:  * All streams inside an Ogg file have a unique serial_no attached to the 
michael@0:  * stream.  Typically, you will want to 
michael@0:  *  - retrieve the serial_no for each b_o_s (beginning of stream) page 
michael@0:  *    encountered within the Ogg file; 
michael@0:  *  - test the first (only) packet on that page to determine if it is a theora 
michael@0:  *    packet;
michael@0:  *  - once you have found a theora b_o_s page then use the retrieved serial_no 
michael@0:  *    to identify future packets belonging to the same theora stream.
michael@0:  * 
michael@0:  * Note that you \e cannot use theora_packet_isheader() to determine if a 
michael@0:  * packet is a theora packet or not, as this function does not perform any
michael@0:  * checking beyond whether a header bit is present.  Instead, use the
michael@0:  * theora_decode_header() function and check the return value; or examine the
michael@0:  * header bytes at the beginning of the Ogg page.
michael@0:  */
michael@0: 
michael@0: 
michael@0: /** \defgroup oldfuncs Legacy pre-1.0 C API */
michael@0: /*  @{ */
michael@0: 
michael@0: /**
michael@0:  * A YUV buffer for passing uncompressed frames to and from the codec.
michael@0:  * This holds a Y'CbCr frame in planar format. The CbCr planes can be
michael@0:  * subsampled and have their own separate dimensions and row stride
michael@0:  * offsets. Note that the strides may be negative in some 
michael@0:  * configurations. For theora the width and height of the largest plane
michael@0:  * must be a multiple of 16. The actual meaningful picture size and 
michael@0:  * offset are stored in the theora_info structure; frames returned by
michael@0:  * the decoder may need to be cropped for display.
michael@0:  *
michael@0:  * All samples are 8 bits. Within each plane samples are ordered by
michael@0:  * row from the top of the frame to the bottom. Within each row samples
michael@0:  * are ordered from left to right.
michael@0:  *
michael@0:  * During decode, the yuv_buffer struct is allocated by the user, but all
michael@0:  * fields (including luma and chroma pointers) are filled by the library.  
michael@0:  * These pointers address library-internal memory and their contents should 
michael@0:  * not be modified.
michael@0:  *
michael@0:  * Conversely, during encode the user allocates the struct and fills out all
michael@0:  * fields.  The user also manages the data addressed by the luma and chroma
michael@0:  * pointers.  See the encoder_example.c and dump_video.c example files in
michael@0:  * theora/examples/ for more information.
michael@0:  */
michael@0: typedef struct {
michael@0:     int   y_width;      /**< Width of the Y' luminance plane */
michael@0:     int   y_height;     /**< Height of the luminance plane */
michael@0:     int   y_stride;     /**< Offset in bytes between successive rows */
michael@0: 
michael@0:     int   uv_width;     /**< Width of the Cb and Cr chroma planes */
michael@0:     int   uv_height;    /**< Height of the chroma planes */
michael@0:     int   uv_stride;    /**< Offset between successive chroma rows */
michael@0:     unsigned char *y;   /**< Pointer to start of luminance data */
michael@0:     unsigned char *u;   /**< Pointer to start of Cb data */
michael@0:     unsigned char *v;   /**< Pointer to start of Cr data */
michael@0: 
michael@0: } yuv_buffer;
michael@0: 
michael@0: /**
michael@0:  * A Colorspace.
michael@0:  */
michael@0: typedef enum {
michael@0:   OC_CS_UNSPECIFIED,    /**< The colorspace is unknown or unspecified */
michael@0:   OC_CS_ITU_REC_470M,   /**< This is the best option for 'NTSC' content */
michael@0:   OC_CS_ITU_REC_470BG,  /**< This is the best option for 'PAL' content */
michael@0:   OC_CS_NSPACES         /**< This marks the end of the defined colorspaces */
michael@0: } theora_colorspace;
michael@0: 
michael@0: /**
michael@0:  * A Chroma subsampling
michael@0:  *
michael@0:  * These enumerate the available chroma subsampling options supported
michael@0:  * by the theora format. See Section 4.4 of the specification for
michael@0:  * exact definitions.
michael@0:  */
michael@0: typedef enum {
michael@0:   OC_PF_420,    /**< Chroma subsampling by 2 in each direction (4:2:0) */
michael@0:   OC_PF_RSVD,   /**< Reserved value */
michael@0:   OC_PF_422,    /**< Horizonatal chroma subsampling by 2 (4:2:2) */
michael@0:   OC_PF_444     /**< No chroma subsampling at all (4:4:4) */
michael@0: } theora_pixelformat;
michael@0: 
michael@0: /**
michael@0:  * Theora bitstream info.
michael@0:  * Contains the basic playback parameters for a stream,
michael@0:  * corresponding to the initial 'info' header packet.
michael@0:  * 
michael@0:  * Encoded theora frames must be a multiple of 16 in width and height.
michael@0:  * To handle other frame sizes, a crop rectangle is specified in
michael@0:  * frame_height and frame_width, offset_x and * offset_y. The offset
michael@0:  * and size should still be a multiple of 2 to avoid chroma sampling
michael@0:  * shifts. Offset values in this structure are measured from the
michael@0:  * upper left of the image.
michael@0:  *
michael@0:  * Frame rate, in frames per second, is stored as a rational
michael@0:  * fraction. Aspect ratio is also stored as a rational fraction, and
michael@0:  * refers to the aspect ratio of the frame pixels, not of the
michael@0:  * overall frame itself.
michael@0:  * 
michael@0:  * See <a href="http://svn.xiph.org/trunk/theora/examples/encoder_example.c">
michael@0:  * examples/encoder_example.c</a> for usage examples of the
michael@0:  * other paramters and good default settings for the encoder parameters.
michael@0:  */
michael@0: typedef struct {
michael@0:   ogg_uint32_t  width;		/**< encoded frame width  */
michael@0:   ogg_uint32_t  height;		/**< encoded frame height */
michael@0:   ogg_uint32_t  frame_width;	/**< display frame width  */
michael@0:   ogg_uint32_t  frame_height;	/**< display frame height */
michael@0:   ogg_uint32_t  offset_x;	/**< horizontal offset of the displayed frame */
michael@0:   ogg_uint32_t  offset_y;	/**< vertical offset of the displayed frame */
michael@0:   ogg_uint32_t  fps_numerator;	    /**< frame rate numerator **/
michael@0:   ogg_uint32_t  fps_denominator;    /**< frame rate denominator **/
michael@0:   ogg_uint32_t  aspect_numerator;   /**< pixel aspect ratio numerator */
michael@0:   ogg_uint32_t  aspect_denominator; /**< pixel aspect ratio denominator */
michael@0:   theora_colorspace colorspace;	    /**< colorspace */
michael@0:   int           target_bitrate;	    /**< nominal bitrate in bits per second */
michael@0:   int           quality;  /**< Nominal quality setting, 0-63 */
michael@0:   int           quick_p;  /**< Quick encode/decode */
michael@0: 
michael@0:   /* decode only */
michael@0:   unsigned char version_major;
michael@0:   unsigned char version_minor;
michael@0:   unsigned char version_subminor;
michael@0: 
michael@0:   void *codec_setup;
michael@0: 
michael@0:   /* encode only */
michael@0:   int           dropframes_p;
michael@0:   int           keyframe_auto_p;
michael@0:   ogg_uint32_t  keyframe_frequency;
michael@0:   ogg_uint32_t  keyframe_frequency_force;  /* also used for decode init to
michael@0:                                               get granpos shift correct */
michael@0:   ogg_uint32_t  keyframe_data_target_bitrate;
michael@0:   ogg_int32_t   keyframe_auto_threshold;
michael@0:   ogg_uint32_t  keyframe_mindistance;
michael@0:   ogg_int32_t   noise_sensitivity;
michael@0:   ogg_int32_t   sharpness;
michael@0: 
michael@0:   theora_pixelformat pixelformat;	/**< chroma subsampling mode to expect */
michael@0: 
michael@0: } theora_info;
michael@0: 
michael@0: /** Codec internal state and context.
michael@0:  */
michael@0: typedef struct{
michael@0:   theora_info *i;
michael@0:   ogg_int64_t granulepos;
michael@0: 
michael@0:   void *internal_encode;
michael@0:   void *internal_decode;
michael@0: 
michael@0: } theora_state;
michael@0: 
michael@0: /** 
michael@0:  * Comment header metadata.
michael@0:  *
michael@0:  * This structure holds the in-stream metadata corresponding to
michael@0:  * the 'comment' header packet.
michael@0:  *
michael@0:  * Meta data is stored as a series of (tag, value) pairs, in
michael@0:  * length-encoded string vectors. The first occurence of the 
michael@0:  * '=' character delimits the tag and value. A particular tag
michael@0:  * may occur more than once. The character set encoding for
michael@0:  * the strings is always UTF-8, but the tag names are limited
michael@0:  * to case-insensitive ASCII. See the spec for details.
michael@0:  *
michael@0:  * In filling in this structure, theora_decode_header() will
michael@0:  * null-terminate the user_comment strings for safety. However,
michael@0:  * the bitstream format itself treats them as 8-bit clean,
michael@0:  * and so the length array should be treated as authoritative
michael@0:  * for their length.
michael@0:  */
michael@0: typedef struct theora_comment{
michael@0:   char **user_comments;         /**< An array of comment string vectors */
michael@0:   int   *comment_lengths;       /**< An array of corresponding string vector lengths in bytes */
michael@0:   int    comments;              /**< The total number of comment string vectors */
michael@0:   char  *vendor;                /**< The vendor string identifying the encoder, null terminated */
michael@0: 
michael@0: } theora_comment;
michael@0: 
michael@0: 
michael@0: /**\name theora_control() codes */
michael@0: /* \anchor decctlcodes_old
michael@0:  * These are the available request codes for theora_control()
michael@0:  * when called with a decoder instance.
michael@0:  * By convention decoder control codes are odd, to distinguish 
michael@0:  * them from \ref encctlcodes_old "encoder control codes" which
michael@0:  * are even.
michael@0:  *
michael@0:  * Note that since the 1.0 release, both the legacy and the final
michael@0:  * implementation accept all the same control codes, but only the
michael@0:  * final API declares the newer codes.
michael@0:  *
michael@0:  * Keep any experimental or vendor-specific values above \c 0x8000.*/
michael@0: 
michael@0: /*@{*/
michael@0: 
michael@0: /**Get the maximum post-processing level.
michael@0:  * The decoder supports a post-processing filter that can improve
michael@0:  * the appearance of the decoded images. This returns the highest
michael@0:  * level setting for this post-processor, corresponding to maximum
michael@0:  * improvement and computational expense.
michael@0:  */
michael@0: #define TH_DECCTL_GET_PPLEVEL_MAX (1)
michael@0: 
michael@0: /**Set the post-processing level.
michael@0:  * Sets the level of post-processing to use when decoding the 
michael@0:  * compressed stream. This must be a value between zero (off)
michael@0:  * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
michael@0:  */
michael@0: #define TH_DECCTL_SET_PPLEVEL (3)
michael@0: 
michael@0: /**Sets the maximum distance between key frames.
michael@0:  * This can be changed during an encode, but will be bounded by
michael@0:  *  <tt>1<<th_info#keyframe_granule_shift</tt>.
michael@0:  * If it is set before encoding begins, th_info#keyframe_granule_shift will
michael@0:  *  be enlarged appropriately.
michael@0:  *
michael@0:  * \param[in]  buf <tt>ogg_uint32_t</tt>: The maximum distance between key
michael@0:  *                   frames.
michael@0:  * \param[out] buf <tt>ogg_uint32_t</tt>: The actual maximum distance set.
michael@0:  * \retval OC_FAULT  \a theora_state or \a buf is <tt>NULL</tt>.
michael@0:  * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>.
michael@0:  * \retval OC_IMPL   Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
michael@0: 
michael@0: /**Set the granule position.
michael@0:  * Call this after a seek, to update the internal granulepos
michael@0:  * in the decoder, to insure that subsequent frames are marked
michael@0:  * properly. If you track timestamps yourself and do not use
michael@0:  * the granule postion returned by the decoder, then you do
michael@0:  * not need to use this control.
michael@0:  */
michael@0: #define TH_DECCTL_SET_GRANPOS (5)
michael@0: 
michael@0: /**\anchor encctlcodes_old */
michael@0: 
michael@0: /**Sets the quantization parameters to use.
michael@0:  * The parameters are copied, not stored by reference, so they can be freed
michael@0:  *  after this call.
michael@0:  * <tt>NULL</tt> may be specified to revert to the default parameters.
michael@0:  *
michael@0:  * \param[in] buf #th_quant_info
michael@0:  * \retval OC_FAULT  \a theora_state is <tt>NULL</tt>.
michael@0:  * \retval OC_EINVAL Encoding has already begun, the quantization parameters
michael@0:  *                    are not acceptable to this version of the encoder, 
michael@0:  *                    \a buf is <tt>NULL</tt> and \a buf_sz is not zero, 
michael@0:  *                    or \a buf is non-<tt>NULL</tt> and \a buf_sz is 
michael@0:  *                    not <tt>sizeof(#th_quant_info)</tt>.
michael@0:  * \retval OC_IMPL   Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_QUANT_PARAMS (2)
michael@0: 
michael@0: /**Disables any encoder features that would prevent lossless transcoding back
michael@0:  *  to VP3.
michael@0:  * This primarily means disabling block-level QI values and not using 4MV mode
michael@0:  *  when any of the luma blocks in a macro block are not coded.
michael@0:  * It also includes using the VP3 quantization tables and Huffman codes; if you
michael@0:  *  set them explicitly after calling this function, the resulting stream will
michael@0:  *  not be VP3-compatible.
michael@0:  * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source
michael@0:  *  material, or when using a picture region smaller than the full frame (e.g.
michael@0:  *  a non-multiple-of-16 width or height), then non-VP3 bitstream features will
michael@0:  *  still be disabled, but the stream will still not be VP3-compatible, as VP3
michael@0:  *  was not capable of encoding such formats.
michael@0:  * If you call this after encoding has already begun, then the quantization
michael@0:  *  tables and codebooks cannot be changed, but the frame-level features will
michael@0:  *  be enabled or disabled as requested.
michael@0:  *
michael@0:  * \param[in]  buf <tt>int</tt>: a non-zero value to enable VP3 compatibility,
michael@0:  *                   or 0 to disable it (the default).
michael@0:  * \param[out] buf <tt>int</tt>: 1 if all bitstream features required for
michael@0:  *                   VP3-compatibility could be set, and 0 otherwise.
michael@0:  *                  The latter will be returned if the pixel format is not
michael@0:  *                   4:2:0, the picture region is smaller than the full frame,
michael@0:  *                   or if encoding has begun, preventing the quantization
michael@0:  *                   tables and codebooks from being set.
michael@0:  * \retval OC_FAULT  \a theora_state or \a buf is <tt>NULL</tt>.
michael@0:  * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
michael@0:  * \retval OC_IMPL   Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
michael@0: 
michael@0: /**Gets the maximum speed level.
michael@0:  * Higher speed levels favor quicker encoding over better quality per bit.
michael@0:  * Depending on the encoding mode, and the internal algorithms used, quality
michael@0:  *  may actually improve, but in this case bitrate will also likely increase.
michael@0:  * In any case, overall rate/distortion performance will probably decrease.
michael@0:  * The maximum value, and the meaning of each value, may change depending on
michael@0:  *  the current encoding mode (VBR vs. CQI, etc.).
michael@0:  *
michael@0:  * \param[out] buf int: The maximum encoding speed level.
michael@0:  * \retval OC_FAULT  \a theora_state or \a buf is <tt>NULL</tt>.
michael@0:  * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
michael@0:  * \retval OC_IMPL   Not supported by this implementation in the current
michael@0:  *                    encoding mode.*/
michael@0: #define TH_ENCCTL_GET_SPLEVEL_MAX (12)
michael@0: 
michael@0: /**Sets the speed level.
michael@0:  * By default a speed value of 1 is used.
michael@0:  *
michael@0:  * \param[in] buf int: The new encoding speed level.
michael@0:  *                      0 is slowest, larger values use less CPU.
michael@0:  * \retval OC_FAULT  \a theora_state or \a buf is <tt>NULL</tt>.
michael@0:  * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>, or the
michael@0:  *                    encoding speed level is out of bounds.
michael@0:  *                   The maximum encoding speed level may be
michael@0:  *                    implementation- and encoding mode-specific, and can be
michael@0:  *                    obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
michael@0:  * \retval OC_IMPL   Not supported by this implementation in the current
michael@0:  *                    encoding mode.*/
michael@0: #define TH_ENCCTL_SET_SPLEVEL (14)
michael@0: 
michael@0: /*@}*/
michael@0: 
michael@0: #define OC_FAULT       -1       /**< General failure */
michael@0: #define OC_EINVAL      -10      /**< Library encountered invalid internal data */
michael@0: #define OC_DISABLED    -11      /**< Requested action is disabled */
michael@0: #define OC_BADHEADER   -20      /**< Header packet was corrupt/invalid */
michael@0: #define OC_NOTFORMAT   -21      /**< Packet is not a theora packet */
michael@0: #define OC_VERSION     -22      /**< Bitstream version is not handled */
michael@0: #define OC_IMPL        -23      /**< Feature or action not implemented */
michael@0: #define OC_BADPACKET   -24      /**< Packet is corrupt */
michael@0: #define OC_NEWPACKET   -25      /**< Packet is an (ignorable) unhandled extension */
michael@0: #define OC_DUPFRAME    1        /**< Packet is a dropped frame */
michael@0: 
michael@0: /** 
michael@0:  * Retrieve a human-readable string to identify the encoder vendor and version.
michael@0:  * \returns A version string.
michael@0:  */
michael@0: extern const char *theora_version_string(void);
michael@0: 
michael@0: /**
michael@0:  * Retrieve a 32-bit version number.
michael@0:  * This number is composed of a 16-bit major version, 8-bit minor version
michael@0:  * and 8 bit sub-version, composed as follows:
michael@0: <pre>
michael@0:    (VERSION_MAJOR<<16) + (VERSION_MINOR<<8) + (VERSION_SUB)
michael@0: </pre>
michael@0: * \returns The version number.
michael@0: */
michael@0: extern ogg_uint32_t theora_version_number(void);
michael@0: 
michael@0: /**
michael@0:  * Initialize the theora encoder.
michael@0:  * \param th The theora_state handle to initialize for encoding.
michael@0:  * \param ti A theora_info struct filled with the desired encoding parameters.
michael@0:  * \retval 0 Success
michael@0:  */
michael@0: extern int theora_encode_init(theora_state *th, theora_info *ti);
michael@0: 
michael@0: /**
michael@0:  * Submit a YUV buffer to the theora encoder.
michael@0:  * \param t A theora_state handle previously initialized for encoding.
michael@0:  * \param yuv A buffer of YUV data to encode.  Note that both the yuv_buffer
michael@0:  *            struct and the luma/chroma buffers within should be allocated by
michael@0:  *            the user.
michael@0:  * \retval OC_EINVAL Encoder is not ready, or is finished.
michael@0:  * \retval -1 The size of the given frame differs from those previously input
michael@0:  * \retval 0 Success
michael@0:  */
michael@0: extern int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv);
michael@0: 
michael@0: /**
michael@0:  * Request the next packet of encoded video. 
michael@0:  * The encoded data is placed in a user-provided ogg_packet structure.
michael@0:  * \param t A theora_state handle previously initialized for encoding.
michael@0:  * \param last_p whether this is the last packet the encoder should produce.
michael@0:  * \param op An ogg_packet structure to fill. libtheora will set all
michael@0:  *           elements of this structure, including a pointer to encoded
michael@0:  *           data. The memory for the encoded data is owned by libtheora.
michael@0:  * \retval 0 No internal storage exists OR no packet is ready
michael@0:  * \retval -1 The encoding process has completed
michael@0:  * \retval 1 Success
michael@0:  */
michael@0: extern int theora_encode_packetout( theora_state *t, int last_p,
michael@0:                                     ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Request a packet containing the initial header.
michael@0:  * A pointer to the header data is placed in a user-provided ogg_packet
michael@0:  * structure.
michael@0:  * \param t A theora_state handle previously initialized for encoding.
michael@0:  * \param op An ogg_packet structure to fill. libtheora will set all
michael@0:  *           elements of this structure, including a pointer to the header
michael@0:  *           data. The memory for the header data is owned by libtheora.
michael@0:  * \retval 0 Success
michael@0:  */
michael@0: extern int theora_encode_header(theora_state *t, ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Request a comment header packet from provided metadata.
michael@0:  * A pointer to the comment data is placed in a user-provided ogg_packet
michael@0:  * structure.
michael@0:  * \param tc A theora_comment structure filled with the desired metadata
michael@0:  * \param op An ogg_packet structure to fill. libtheora will set all
michael@0:  *           elements of this structure, including a pointer to the encoded
michael@0:  *           comment data. The memory for the comment data is owned by
michael@0:  *           libtheora.
michael@0:  * \retval 0 Success
michael@0:  */
michael@0: extern int theora_encode_comment(theora_comment *tc, ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Request a packet containing the codebook tables for the stream.
michael@0:  * A pointer to the codebook data is placed in a user-provided ogg_packet
michael@0:  * structure.
michael@0:  * \param t A theora_state handle previously initialized for encoding.
michael@0:  * \param op An ogg_packet structure to fill. libtheora will set all
michael@0:  *           elements of this structure, including a pointer to the codebook
michael@0:  *           data. The memory for the header data is owned by libtheora.
michael@0:  * \retval 0 Success
michael@0:  */
michael@0: extern int theora_encode_tables(theora_state *t, ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Decode an Ogg packet, with the expectation that the packet contains
michael@0:  * an initial header, comment data or codebook tables.
michael@0:  *
michael@0:  * \param ci A theora_info structure to fill. This must have been previously
michael@0:  *           initialized with theora_info_init(). If \a op contains an initial
michael@0:  *           header, theora_decode_header() will fill \a ci with the
michael@0:  *           parsed header values. If \a op contains codebook tables,
michael@0:  *           theora_decode_header() will parse these and attach an internal
michael@0:  *           representation to \a ci->codec_setup.
michael@0:  * \param cc A theora_comment structure to fill. If \a op contains comment
michael@0:  *           data, theora_decode_header() will fill \a cc with the parsed
michael@0:  *           comments.
michael@0:  * \param op An ogg_packet structure which you expect contains an initial
michael@0:  *           header, comment data or codebook tables.
michael@0:  *
michael@0:  * \retval OC_BADHEADER \a op is NULL; OR the first byte of \a op->packet
michael@0:  *                      has the signature of an initial packet, but op is
michael@0:  *                      not a b_o_s packet; OR this packet has the signature
michael@0:  *                      of an initial header packet, but an initial header
michael@0:  *                      packet has already been seen; OR this packet has the
michael@0:  *                      signature of a comment packet, but the initial header
michael@0:  *                      has not yet been seen; OR this packet has the signature
michael@0:  *                      of a comment packet, but contains invalid data; OR
michael@0:  *                      this packet has the signature of codebook tables,
michael@0:  *                      but the initial header or comments have not yet
michael@0:  *                      been seen; OR this packet has the signature of codebook
michael@0:  *                      tables, but contains invalid data;
michael@0:  *                      OR the stream being decoded has a compatible version
michael@0:  *                      but this packet does not have the signature of a
michael@0:  *                      theora initial header, comments, or codebook packet
michael@0:  * \retval OC_VERSION   The packet data of \a op is an initial header with
michael@0:  *                      a version which is incompatible with this version of
michael@0:  *                      libtheora.
michael@0:  * \retval OC_NEWPACKET the stream being decoded has an incompatible (future)
michael@0:  *                      version and contains an unknown signature.
michael@0:  * \retval 0            Success
michael@0:  *
michael@0:  * \note The normal usage is that theora_decode_header() be called on the
michael@0:  *       first three packets of a theora logical bitstream in succession.
michael@0:  */
michael@0: extern int theora_decode_header(theora_info *ci, theora_comment *cc,
michael@0:                                 ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Initialize a theora_state handle for decoding.
michael@0:  * \param th The theora_state handle to initialize.
michael@0:  * \param c  A theora_info struct filled with the desired decoding parameters.
michael@0:  *           This is of course usually obtained from a previous call to
michael@0:  *           theora_decode_header().
michael@0:  * \retval 0 Success
michael@0:  */
michael@0: extern int theora_decode_init(theora_state *th, theora_info *c);
michael@0: 
michael@0: /**
michael@0:  * Input a packet containing encoded data into the theora decoder.
michael@0:  * \param th A theora_state handle previously initialized for decoding.
michael@0:  * \param op An ogg_packet containing encoded theora data.
michael@0:  * \retval 0 Success
michael@0:  * \retval OC_BADPACKET \a op does not contain encoded video data
michael@0:  */
michael@0: extern int theora_decode_packetin(theora_state *th,ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Output the next available frame of decoded YUV data.
michael@0:  * \param th A theora_state handle previously initialized for decoding.
michael@0:  * \param yuv A yuv_buffer in which libtheora should place the decoded data.
michael@0:  *            Note that the buffer struct itself is allocated by the user, but
michael@0:  *            that the luma and chroma pointers will be filled in by the 
michael@0:  *            library.  Also note that these luma and chroma regions should be 
michael@0:  *            considered read-only by the user.
michael@0:  * \retval 0 Success
michael@0:  */
michael@0: extern int theora_decode_YUVout(theora_state *th,yuv_buffer *yuv);
michael@0: 
michael@0: /**
michael@0:  * Report whether a theora packet is a header or not
michael@0:  * This function does no verification beyond checking the header
michael@0:  * flag bit so it should not be used for bitstream identification;
michael@0:  * use theora_decode_header() for that.
michael@0:  *
michael@0:  * \param op An ogg_packet containing encoded theora data.
michael@0:  * \retval 1 The packet is a header packet
michael@0:  * \retval 0 The packet is not a header packet (and so contains frame data)
michael@0:  *
michael@0:  * Thus function was added in the 1.0alpha4 release.
michael@0:  */
michael@0: extern int theora_packet_isheader(ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Report whether a theora packet is a keyframe or not
michael@0:  *
michael@0:  * \param op An ogg_packet containing encoded theora data.
michael@0:  * \retval 1 The packet contains a keyframe image
michael@0:  * \retval 0 The packet is contains an interframe delta
michael@0:  * \retval -1 The packet is not an image data packet at all
michael@0:  *
michael@0:  * Thus function was added in the 1.0alpha4 release.
michael@0:  */
michael@0: extern int theora_packet_iskeyframe(ogg_packet *op);
michael@0: 
michael@0: /**
michael@0:  * Report the granulepos shift radix
michael@0:  *
michael@0:  * When embedded in Ogg, Theora uses a two-part granulepos, 
michael@0:  * splitting the 64-bit field into two pieces. The more-significant
michael@0:  * section represents the frame count at the last keyframe,
michael@0:  * and the less-significant section represents the count of
michael@0:  * frames since the last keyframe. In this way the overall
michael@0:  * field is still non-decreasing with time, but usefully encodes
michael@0:  * a pointer to the last keyframe, which is necessary for
michael@0:  * correctly restarting decode after a seek. 
michael@0:  *
michael@0:  * This function reports the number of bits used to represent
michael@0:  * the distance to the last keyframe, and thus how the granulepos
michael@0:  * field must be shifted or masked to obtain the two parts.
michael@0:  * 
michael@0:  * Since libtheora returns compressed data in an ogg_packet
michael@0:  * structure, this may be generally useful even if the Theora
michael@0:  * packets are not being used in an Ogg container. 
michael@0:  *
michael@0:  * \param ti A previously initialized theora_info struct
michael@0:  * \returns The bit shift dividing the two granulepos fields
michael@0:  *
michael@0:  * This function was added in the 1.0alpha5 release.
michael@0:  */
michael@0: int theora_granule_shift(theora_info *ti);
michael@0: 
michael@0: /**
michael@0:  * Convert a granulepos to an absolute frame index, starting at 0.
michael@0:  * The granulepos is interpreted in the context of a given theora_state handle.
michael@0:  * 
michael@0:  * Note that while the granulepos encodes the frame count (i.e. starting
michael@0:  * from 1) this call returns the frame index, starting from zero. Thus
michael@0:  * One can calculate the presentation time by multiplying the index by
michael@0:  * the rate.
michael@0:  *
michael@0:  * \param th A previously initialized theora_state handle (encode or decode)
michael@0:  * \param granulepos The granulepos to convert.
michael@0:  * \returns The frame index corresponding to \a granulepos.
michael@0:  * \retval -1 The given granulepos is undefined (i.e. negative)
michael@0:  *
michael@0:  * Thus function was added in the 1.0alpha4 release.
michael@0:  */
michael@0: extern ogg_int64_t theora_granule_frame(theora_state *th,ogg_int64_t granulepos);
michael@0: 
michael@0: /**
michael@0:  * Convert a granulepos to absolute time in seconds. The granulepos is
michael@0:  * interpreted in the context of a given theora_state handle, and gives
michael@0:  * the end time of a frame's presentation as used in Ogg mux ordering.
michael@0:  *
michael@0:  * \param th A previously initialized theora_state handle (encode or decode)
michael@0:  * \param granulepos The granulepos to convert.
michael@0:  * \returns The absolute time in seconds corresponding to \a granulepos.
michael@0:  *          This is the "end time" for the frame, or the latest time it should
michael@0:  *           be displayed.
michael@0:  *          It is not the presentation time.
michael@0:  * \retval -1. The given granulepos is undefined (i.e. negative), or
michael@0:  * \retval -1. The function has been disabled because floating 
michael@0:  *              point support is not available.
michael@0:  */
michael@0: extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos);
michael@0: 
michael@0: /**
michael@0:  * Initialize a theora_info structure. All values within the given theora_info
michael@0:  * structure are initialized, and space is allocated within libtheora for
michael@0:  * internal codec setup data.
michael@0:  * \param c A theora_info struct to initialize.
michael@0:  */
michael@0: extern void theora_info_init(theora_info *c);
michael@0: 
michael@0: /**
michael@0:  * Clear a theora_info structure. All values within the given theora_info
michael@0:  * structure are cleared, and associated internal codec setup data is freed.
michael@0:  * \param c A theora_info struct to initialize.
michael@0:  */
michael@0: extern void theora_info_clear(theora_info *c);
michael@0: 
michael@0: /**
michael@0:  * Free all internal data associated with a theora_state handle.
michael@0:  * \param t A theora_state handle.
michael@0:  */
michael@0: extern void theora_clear(theora_state *t);
michael@0: 
michael@0: /**
michael@0:  * Initialize an allocated theora_comment structure
michael@0:  * \param tc An allocated theora_comment structure 
michael@0:  **/
michael@0: extern void theora_comment_init(theora_comment *tc);
michael@0: 
michael@0: /**
michael@0:  * Add a comment to an initialized theora_comment structure
michael@0:  * \param tc A previously initialized theora comment structure
michael@0:  * \param comment A null-terminated string encoding the comment in the form
michael@0:  *                "TAG=the value"
michael@0:  *
michael@0:  * Neither theora_comment_add() nor theora_comment_add_tag() support
michael@0:  * comments containing null values, although the bitstream format
michael@0:  * supports this. To add such comments you will need to manipulate
michael@0:  * the theora_comment structure directly.
michael@0:  **/
michael@0: 
michael@0: extern void theora_comment_add(theora_comment *tc, char *comment);
michael@0: 
michael@0: /**
michael@0:  * Add a comment to an initialized theora_comment structure.
michael@0:  * \param tc A previously initialized theora comment structure
michael@0:  * \param tag A null-terminated string containing the tag 
michael@0:  *            associated with the comment.
michael@0:  * \param value The corresponding value as a null-terminated string
michael@0:  *
michael@0:  * Neither theora_comment_add() nor theora_comment_add_tag() support
michael@0:  * comments containing null values, although the bitstream format
michael@0:  * supports this. To add such comments you will need to manipulate
michael@0:  * the theora_comment structure directly.
michael@0:  **/
michael@0: extern void theora_comment_add_tag(theora_comment *tc,
michael@0:                                        char *tag, char *value);
michael@0: 
michael@0: /**
michael@0:  * Look up a comment value by tag.
michael@0:  * \param tc Tn initialized theora_comment structure
michael@0:  * \param tag The tag to look up
michael@0:  * \param count The instance of the tag. The same tag can appear multiple
michael@0:  *              times, each with a distinct and ordered value, so an index
michael@0:  *              is required to retrieve them all.
michael@0:  * \returns A pointer to the queried tag's value
michael@0:  * \retval NULL No matching tag is found
michael@0:  *
michael@0:  * \note Use theora_comment_query_count() to get the legal range for the
michael@0:  * count parameter.
michael@0:  **/
michael@0: 
michael@0: extern char *theora_comment_query(theora_comment *tc, char *tag, int count);
michael@0: 
michael@0: /** Look up the number of instances of a tag.
michael@0:  *  \param tc An initialized theora_comment structure
michael@0:  *  \param tag The tag to look up
michael@0:  *  \returns The number on instances of a particular tag.
michael@0:  * 
michael@0:  *  Call this first when querying for a specific tag and then interate
michael@0:  *  over the number of instances with separate calls to 
michael@0:  *  theora_comment_query() to retrieve all instances in order.
michael@0:  **/
michael@0: extern int   theora_comment_query_count(theora_comment *tc, char *tag);
michael@0: 
michael@0: /**
michael@0:  * Clear an allocated theora_comment struct so that it can be freed.
michael@0:  * \param tc An allocated theora_comment structure.
michael@0:  **/
michael@0: extern void  theora_comment_clear(theora_comment *tc);
michael@0: 
michael@0: /**Encoder control function.
michael@0:  * This is used to provide advanced control the encoding process.
michael@0:  * \param th     A #theora_state handle.
michael@0:  * \param req    The control code to process.
michael@0:  *                See \ref encctlcodes_old "the list of available 
michael@0:  *			control codes" for details.
michael@0:  * \param buf    The parameters for this control code.
michael@0:  * \param buf_sz The size of the parameter buffer.*/
michael@0: extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz);
michael@0: 
michael@0: /* @} */ /* end oldfuncs doxygen group */
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif /* __cplusplus */
michael@0: 
michael@0: #endif /* _O_THEORA_H_ */