1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libtheora/include/theora/theoradec.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,326 @@
1.4 +/********************************************************************
1.5 + * *
1.6 + * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
1.7 + * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
1.8 + * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
1.9 + * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
1.10 + * *
1.11 + * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
1.12 + * by the Xiph.Org Foundation http://www.xiph.org/ *
1.13 + * *
1.14 + ********************************************************************
1.15 +
1.16 + function:
1.17 + last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
1.18 +
1.19 + ********************************************************************/
1.20 +
1.21 +/**\file
1.22 + * The <tt>libtheoradec</tt> C decoding API.*/
1.23 +
1.24 +#if !defined(_O_THEORA_THEORADEC_H_)
1.25 +# define _O_THEORA_THEORADEC_H_ (1)
1.26 +# include <stddef.h>
1.27 +# include <ogg/ogg.h>
1.28 +# include "codec.h"
1.29 +
1.30 +#if defined(__cplusplus)
1.31 +extern "C" {
1.32 +#endif
1.33 +
1.34 +
1.35 +
1.36 +/**\name th_decode_ctl() codes
1.37 + * \anchor decctlcodes
1.38 + * These are the available request codes for th_decode_ctl().
1.39 + * By convention, these are odd, to distinguish them from the
1.40 + * \ref encctlcodes "encoder control codes".
1.41 + * Keep any experimental or vendor-specific values above \c 0x8000.*/
1.42 +/*@{*/
1.43 +/**Gets the maximum post-processing level.
1.44 + * The decoder supports a post-processing filter that can improve
1.45 + * the appearance of the decoded images. This returns the highest
1.46 + * level setting for this post-processor, corresponding to maximum
1.47 + * improvement and computational expense.
1.48 + *
1.49 + * \param[out] _buf int: The maximum post-processing level.
1.50 + * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
1.51 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
1.52 + * \retval TH_EIMPL Not supported by this implementation.*/
1.53 +#define TH_DECCTL_GET_PPLEVEL_MAX (1)
1.54 +/**Sets the post-processing level.
1.55 + * By default, post-processing is disabled.
1.56 + *
1.57 + * Sets the level of post-processing to use when decoding the
1.58 + * compressed stream. This must be a value between zero (off)
1.59 + * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
1.60 + *
1.61 + * \param[in] _buf int: The new post-processing level.
1.62 + * 0 to disable; larger values use more CPU.
1.63 + * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
1.64 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
1.65 + * post-processing level is out of bounds.
1.66 + * The maximum post-processing level may be
1.67 + * implementation-specific, and can be obtained via
1.68 + * #TH_DECCTL_GET_PPLEVEL_MAX.
1.69 + * \retval TH_EIMPL Not supported by this implementation.*/
1.70 +#define TH_DECCTL_SET_PPLEVEL (3)
1.71 +/**Sets the granule position.
1.72 + * Call this after a seek, before decoding the first frame, to ensure that the
1.73 + * proper granule position is returned for all subsequent frames.
1.74 + * If you track timestamps yourself and do not use the granule position
1.75 + * returned by the decoder, then you need not call this function.
1.76 + *
1.77 + * \param[in] _buf <tt>ogg_int64_t</tt>: The granule position of the next
1.78 + * frame.
1.79 + * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
1.80 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(ogg_int64_t)</tt>, or the
1.81 + * granule position is negative.*/
1.82 +#define TH_DECCTL_SET_GRANPOS (5)
1.83 +/**Sets the striped decode callback function.
1.84 + * If set, this function will be called as each piece of a frame is fully
1.85 + * decoded in th_decode_packetin().
1.86 + * You can pass in a #th_stripe_callback with
1.87 + * th_stripe_callback#stripe_decoded set to <tt>NULL</tt> to disable the
1.88 + * callbacks at any point.
1.89 + * Enabling striped decode does not prevent you from calling
1.90 + * th_decode_ycbcr_out() after the frame is fully decoded.
1.91 + *
1.92 + * \param[in] _buf #th_stripe_callback: The callback parameters.
1.93 + * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>.
1.94 + * \retval TH_EINVAL \a _buf_sz is not
1.95 + * <tt>sizeof(th_stripe_callback)</tt>.*/
1.96 +#define TH_DECCTL_SET_STRIPE_CB (7)
1.97 +
1.98 +/**Enables telemetry and sets the macroblock display mode */
1.99 +#define TH_DECCTL_SET_TELEMETRY_MBMODE (9)
1.100 +/**Enables telemetry and sets the motion vector display mode */
1.101 +#define TH_DECCTL_SET_TELEMETRY_MV (11)
1.102 +/**Enables telemetry and sets the adaptive quantization display mode */
1.103 +#define TH_DECCTL_SET_TELEMETRY_QI (13)
1.104 +/**Enables telemetry and sets the bitstream breakdown visualization mode */
1.105 +#define TH_DECCTL_SET_TELEMETRY_BITS (15)
1.106 +/*@}*/
1.107 +
1.108 +
1.109 +
1.110 +/**A callback function for striped decode.
1.111 + * This is a function pointer to an application-provided function that will be
1.112 + * called each time a section of the image is fully decoded in
1.113 + * th_decode_packetin().
1.114 + * This allows the application to process the section immediately, while it is
1.115 + * still in cache.
1.116 + * Note that the frame is decoded bottom to top, so \a _yfrag0 will steadily
1.117 + * decrease with each call until it reaches 0, at which point the full frame
1.118 + * is decoded.
1.119 + * The number of fragment rows made available in each call depends on the pixel
1.120 + * format and the number of post-processing filters enabled, and may not even
1.121 + * be constant for the entire frame.
1.122 + * If a non-<tt>NULL</tt> \a _granpos pointer is passed to
1.123 + * th_decode_packetin(), the granule position for the frame will be stored
1.124 + * in it before the first callback is made.
1.125 + * If an entire frame is dropped (a 0-byte packet), then no callbacks will be
1.126 + * made at all for that frame.
1.127 + * \param _ctx An application-provided context pointer.
1.128 + * \param _buf The image buffer for the decoded frame.
1.129 + * \param _yfrag0 The Y coordinate of the first row of 8x8 fragments
1.130 + * decoded.
1.131 + * Multiply this by 8 to obtain the pixel row number in the
1.132 + * luma plane.
1.133 + * If the chroma planes are subsampled in the Y direction,
1.134 + * this will always be divisible by two.
1.135 + * \param _yfrag_end The Y coordinate of the first row of 8x8 fragments past
1.136 + * the newly decoded section.
1.137 + * If the chroma planes are subsampled in the Y direction,
1.138 + * this will always be divisible by two.
1.139 + * I.e., this section contains fragment rows
1.140 + * <tt>\a _yfrag0 ...\a _yfrag_end -1</tt>.*/
1.141 +typedef void (*th_stripe_decoded_func)(void *_ctx,th_ycbcr_buffer _buf,
1.142 + int _yfrag0,int _yfrag_end);
1.143 +
1.144 +/**The striped decode callback data to pass to #TH_DECCTL_SET_STRIPE_CB.*/
1.145 +typedef struct{
1.146 + /**An application-provided context pointer.
1.147 + * This will be passed back verbatim to the application.*/
1.148 + void *ctx;
1.149 + /**The callback function pointer.*/
1.150 + th_stripe_decoded_func stripe_decoded;
1.151 +}th_stripe_callback;
1.152 +
1.153 +
1.154 +
1.155 +/**\name Decoder state
1.156 + The following data structures are opaque, and their contents are not
1.157 + publicly defined by this API.
1.158 + Referring to their internals directly is unsupported, and may break without
1.159 + warning.*/
1.160 +/*@{*/
1.161 +/**The decoder context.*/
1.162 +typedef struct th_dec_ctx th_dec_ctx;
1.163 +/**Setup information.
1.164 + This contains auxiliary information (Huffman tables and quantization
1.165 + parameters) decoded from the setup header by th_decode_headerin() to be
1.166 + passed to th_decode_alloc().
1.167 + It can be re-used to initialize any number of decoders, and can be freed
1.168 + via th_setup_free() at any time.*/
1.169 +typedef struct th_setup_info th_setup_info;
1.170 +/*@}*/
1.171 +
1.172 +
1.173 +
1.174 +/**\defgroup decfuncs Functions for Decoding*/
1.175 +/*@{*/
1.176 +/**\name Functions for decoding
1.177 + * You must link to <tt>libtheoradec</tt> if you use any of the
1.178 + * functions in this section.
1.179 + *
1.180 + * The functions are listed in the order they are used in a typical decode.
1.181 + * The basic steps are:
1.182 + * - Parse the header packets by repeatedly calling th_decode_headerin().
1.183 + * - Allocate a #th_dec_ctx handle with th_decode_alloc().
1.184 + * - Call th_setup_free() to free any memory used for codec setup
1.185 + * information.
1.186 + * - Perform any additional decoder configuration with th_decode_ctl().
1.187 + * - For each video data packet:
1.188 + * - Submit the packet to the decoder via th_decode_packetin().
1.189 + * - Retrieve the uncompressed video data via th_decode_ycbcr_out().
1.190 + * - Call th_decode_free() to release all decoder memory.*/
1.191 +/*@{*/
1.192 +/**Decodes the header packets of a Theora stream.
1.193 + * This should be called on the initial packets of the stream, in succession,
1.194 + * until it returns <tt>0</tt>, indicating that all headers have been
1.195 + * processed, or an error is encountered.
1.196 + * At least three header packets are required, and additional optional header
1.197 + * packets may follow.
1.198 + * This can be used on the first packet of any logical stream to determine if
1.199 + * that stream is a Theora stream.
1.200 + * \param _info A #th_info structure to fill in.
1.201 + * This must have been previously initialized with
1.202 + * th_info_init().
1.203 + * The application may immediately begin using the contents of
1.204 + * this structure after the first header is decoded, though it
1.205 + * must continue to be passed in on all subsequent calls.
1.206 + * \param _tc A #th_comment structure to fill in.
1.207 + * The application may immediately begin using the contents of
1.208 + * this structure after the second header is decoded, though it
1.209 + * must continue to be passed in on all subsequent calls.
1.210 + * \param _setup Returns a pointer to additional, private setup information
1.211 + * needed by the decoder.
1.212 + * The contents of this pointer must be initialized to
1.213 + * <tt>NULL</tt> on the first call, and the returned value must
1.214 + * continue to be passed in on all subsequent calls.
1.215 + * \param _op An <tt>ogg_packet</tt> structure which contains one of the
1.216 + * initial packets of an Ogg logical stream.
1.217 + * \return A positive value indicates that a Theora header was successfully
1.218 + * processed.
1.219 + * \retval 0 The first video data packet was encountered after all
1.220 + * required header packets were parsed.
1.221 + * The packet just passed in on this call should be saved
1.222 + * and fed to th_decode_packetin() to begin decoding
1.223 + * video data.
1.224 + * \retval TH_EFAULT One of \a _info, \a _tc, or \a _setup was
1.225 + * <tt>NULL</tt>.
1.226 + * \retval TH_EBADHEADER \a _op was <tt>NULL</tt>, the packet was not the next
1.227 + * header packet in the expected sequence, or the format
1.228 + * of the header data was invalid.
1.229 + * \retval TH_EVERSION The packet data was a Theora info header, but for a
1.230 + * bitstream version not decodable with this version of
1.231 + * <tt>libtheoradec</tt>.
1.232 + * \retval TH_ENOTFORMAT The packet was not a Theora header.
1.233 + */
1.234 +extern int th_decode_headerin(th_info *_info,th_comment *_tc,
1.235 + th_setup_info **_setup,ogg_packet *_op);
1.236 +/**Allocates a decoder instance.
1.237 + *
1.238 + * <b>Security Warning:</b> The Theora format supports very large frame sizes,
1.239 + * potentially even larger than the address space of a 32-bit machine, and
1.240 + * creating a decoder context allocates the space for several frames of data.
1.241 + * If the allocation fails here, your program will crash, possibly at some
1.242 + * future point because the OS kernel returned a valid memory range and will
1.243 + * only fail when it tries to map the pages in it the first time they are
1.244 + * used.
1.245 + * Even if it succeeds, you may experience a denial of service if the frame
1.246 + * size is large enough to cause excessive paging.
1.247 + * If you are integrating libtheora in a larger application where such things
1.248 + * are undesirable, it is highly recommended that you check the frame size in
1.249 + * \a _info before calling this function and refuse to decode streams where it
1.250 + * is larger than some reasonable maximum.
1.251 + * libtheora will not check this for you, because there may be machines that
1.252 + * can handle such streams and applications that wish to.
1.253 + * \param _info A #th_info struct filled via th_decode_headerin().
1.254 + * \param _setup A #th_setup_info handle returned via
1.255 + * th_decode_headerin().
1.256 + * \return The initialized #th_dec_ctx handle.
1.257 + * \retval NULL If the decoding parameters were invalid.*/
1.258 +extern th_dec_ctx *th_decode_alloc(const th_info *_info,
1.259 + const th_setup_info *_setup);
1.260 +/**Releases all storage used for the decoder setup information.
1.261 + * This should be called after you no longer want to create any decoders for
1.262 + * a stream whose headers you have parsed with th_decode_headerin().
1.263 + * \param _setup The setup information to free.
1.264 + * This can safely be <tt>NULL</tt>.*/
1.265 +extern void th_setup_free(th_setup_info *_setup);
1.266 +/**Decoder control function.
1.267 + * This is used to provide advanced control of the decoding process.
1.268 + * \param _dec A #th_dec_ctx handle.
1.269 + * \param _req The control code to process.
1.270 + * See \ref decctlcodes "the list of available control codes"
1.271 + * for details.
1.272 + * \param _buf The parameters for this control code.
1.273 + * \param _buf_sz The size of the parameter buffer.*/
1.274 +extern int th_decode_ctl(th_dec_ctx *_dec,int _req,void *_buf,
1.275 + size_t _buf_sz);
1.276 +/**Submits a packet containing encoded video data to the decoder.
1.277 + * \param _dec A #th_dec_ctx handle.
1.278 + * \param _op An <tt>ogg_packet</tt> containing encoded video data.
1.279 + * \param _granpos Returns the granule position of the decoded packet.
1.280 + * If non-<tt>NULL</tt>, the granule position for this specific
1.281 + * packet is stored in this location.
1.282 + * This is computed incrementally from previously decoded
1.283 + * packets.
1.284 + * After a seek, the correct granule position must be set via
1.285 + * #TH_DECCTL_SET_GRANPOS for this to work properly.
1.286 + * \retval 0 Success.
1.287 + * A new decoded frame can be retrieved by calling
1.288 + * th_decode_ycbcr_out().
1.289 + * \retval TH_DUPFRAME The packet represented a dropped frame (either a
1.290 + * 0-byte frame or an INTER frame with no coded blocks).
1.291 + * The player can skip the call to th_decode_ycbcr_out(),
1.292 + * as the contents of the decoded frame buffer have not
1.293 + * changed.
1.294 + * \retval TH_EFAULT \a _dec or \a _op was <tt>NULL</tt>.
1.295 + * \retval TH_EBADPACKET \a _op does not contain encoded video data.
1.296 + * \retval TH_EIMPL The video data uses bitstream features which this
1.297 + * library does not support.*/
1.298 +extern int th_decode_packetin(th_dec_ctx *_dec,const ogg_packet *_op,
1.299 + ogg_int64_t *_granpos);
1.300 +/**Outputs the next available frame of decoded Y'CbCr data.
1.301 + * If a striped decode callback has been set with #TH_DECCTL_SET_STRIPE_CB,
1.302 + * then the application does not need to call this function.
1.303 + * \param _dec A #th_dec_ctx handle.
1.304 + * \param _ycbcr A video buffer structure to fill in.
1.305 + * <tt>libtheoradec</tt> will fill in all the members of this
1.306 + * structure, including the pointers to the uncompressed video
1.307 + * data.
1.308 + * The memory for this video data is owned by
1.309 + * <tt>libtheoradec</tt>.
1.310 + * It may be freed or overwritten without notification when
1.311 + * subsequent frames are decoded.
1.312 + * \retval 0 Success
1.313 + * \retval TH_EFAULT \a _dec or \a _ycbcr was <tt>NULL</tt>.
1.314 + */
1.315 +extern int th_decode_ycbcr_out(th_dec_ctx *_dec,
1.316 + th_ycbcr_buffer _ycbcr);
1.317 +/**Frees an allocated decoder instance.
1.318 + * \param _dec A #th_dec_ctx handle.*/
1.319 +extern void th_decode_free(th_dec_ctx *_dec);
1.320 +/*@}*/
1.321 +/*@}*/
1.322 +
1.323 +
1.324 +
1.325 +#if defined(__cplusplus)
1.326 +}
1.327 +#endif
1.328 +
1.329 +#endif
