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 | /**\file |
19 | * The <tt>libtheoradec</tt> C decoding API.*/ |
20 | |
21 | #if !defined(_O_THEORA_THEORADEC_H_) |
22 | # define _O_THEORA_THEORADEC_H_ (1) |
23 | # include <stddef.h> |
24 | # include <ogg/ogg.h> |
25 | # include "codec.h" |
26 | |
27 | #if defined(__cplusplus) |
28 | extern "C" { |
29 | #endif |
30 | |
31 | |
32 | |
33 | /**\name th_decode_ctl() codes |
34 | * \anchor decctlcodes |
35 | * These are the available request codes for th_decode_ctl(). |
36 | * By convention, these are odd, to distinguish them from the |
37 | * \ref encctlcodes "encoder control codes". |
38 | * Keep any experimental or vendor-specific values above \c 0x8000.*/ |
39 | /*@{*/ |
40 | /**Gets the maximum post-processing level. |
41 | * The decoder supports a post-processing filter that can improve |
42 | * the appearance of the decoded images. This returns the highest |
43 | * level setting for this post-processor, corresponding to maximum |
44 | * improvement and computational expense. |
45 | * |
46 | * \param[out] _buf int: The maximum post-processing level. |
47 | * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>. |
48 | * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>. |
49 | * \retval TH_EIMPL Not supported by this implementation.*/ |
50 | #define TH_DECCTL_GET_PPLEVEL_MAX (1) |
51 | /**Sets the post-processing level. |
52 | * By default, post-processing is disabled. |
53 | * |
54 | * Sets the level of post-processing to use when decoding the |
55 | * compressed stream. This must be a value between zero (off) |
56 | * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX. |
57 | * |
58 | * \param[in] _buf int: The new post-processing level. |
59 | * 0 to disable; larger values use more CPU. |
60 | * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>. |
61 | * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the |
62 | * post-processing level is out of bounds. |
63 | * The maximum post-processing level may be |
64 | * implementation-specific, and can be obtained via |
65 | * #TH_DECCTL_GET_PPLEVEL_MAX. |
66 | * \retval TH_EIMPL Not supported by this implementation.*/ |
67 | #define TH_DECCTL_SET_PPLEVEL (3) |
68 | /**Sets the granule position. |
69 | * Call this after a seek, before decoding the first frame, to ensure that the |
70 | * proper granule position is returned for all subsequent frames. |
71 | * If you track timestamps yourself and do not use the granule position |
72 | * returned by the decoder, then you need not call this function. |
73 | * |
74 | * \param[in] _buf <tt>ogg_int64_t</tt>: The granule position of the next |
75 | * frame. |
76 | * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>. |
77 | * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(ogg_int64_t)</tt>, or the |
78 | * granule position is negative.*/ |
79 | #define TH_DECCTL_SET_GRANPOS (5) |
80 | /**Sets the striped decode callback function. |
81 | * If set, this function will be called as each piece of a frame is fully |
82 | * decoded in th_decode_packetin(). |
83 | * You can pass in a #th_stripe_callback with |
84 | * th_stripe_callback#stripe_decoded set to <tt>NULL</tt> to disable the |
85 | * callbacks at any point. |
86 | * Enabling striped decode does not prevent you from calling |
87 | * th_decode_ycbcr_out() after the frame is fully decoded. |
88 | * |
89 | * \param[in] _buf #th_stripe_callback: The callback parameters. |
90 | * \retval TH_EFAULT \a _dec_ctx or \a _buf is <tt>NULL</tt>. |
91 | * \retval TH_EINVAL \a _buf_sz is not |
92 | * <tt>sizeof(th_stripe_callback)</tt>.*/ |
93 | #define TH_DECCTL_SET_STRIPE_CB (7) |
94 | |
95 | /**Enables telemetry and sets the macroblock display mode */ |
96 | #define TH_DECCTL_SET_TELEMETRY_MBMODE (9) |
97 | /**Enables telemetry and sets the motion vector display mode */ |
98 | #define TH_DECCTL_SET_TELEMETRY_MV (11) |
99 | /**Enables telemetry and sets the adaptive quantization display mode */ |
100 | #define TH_DECCTL_SET_TELEMETRY_QI (13) |
101 | /**Enables telemetry and sets the bitstream breakdown visualization mode */ |
102 | #define TH_DECCTL_SET_TELEMETRY_BITS (15) |
103 | /*@}*/ |
104 | |
105 | |
106 | |
107 | /**A callback function for striped decode. |
108 | * This is a function pointer to an application-provided function that will be |
109 | * called each time a section of the image is fully decoded in |
110 | * th_decode_packetin(). |
111 | * This allows the application to process the section immediately, while it is |
112 | * still in cache. |
113 | * Note that the frame is decoded bottom to top, so \a _yfrag0 will steadily |
114 | * decrease with each call until it reaches 0, at which point the full frame |
115 | * is decoded. |
116 | * The number of fragment rows made available in each call depends on the pixel |
117 | * format and the number of post-processing filters enabled, and may not even |
118 | * be constant for the entire frame. |
119 | * If a non-<tt>NULL</tt> \a _granpos pointer is passed to |
120 | * th_decode_packetin(), the granule position for the frame will be stored |
121 | * in it before the first callback is made. |
122 | * If an entire frame is dropped (a 0-byte packet), then no callbacks will be |
123 | * made at all for that frame. |
124 | * \param _ctx An application-provided context pointer. |
125 | * \param _buf The image buffer for the decoded frame. |
126 | * \param _yfrag0 The Y coordinate of the first row of 8x8 fragments |
127 | * decoded. |
128 | * Multiply this by 8 to obtain the pixel row number in the |
129 | * luma plane. |
130 | * If the chroma planes are subsampled in the Y direction, |
131 | * this will always be divisible by two. |
132 | * \param _yfrag_end The Y coordinate of the first row of 8x8 fragments past |
133 | * the newly decoded section. |
134 | * If the chroma planes are subsampled in the Y direction, |
135 | * this will always be divisible by two. |
136 | * I.e., this section contains fragment rows |
137 | * <tt>\a _yfrag0 ...\a _yfrag_end -1</tt>.*/ |
138 | typedef void (*th_stripe_decoded_func)(void *_ctx,th_ycbcr_buffer _buf, |
139 | int _yfrag0,int _yfrag_end); |
140 | |
141 | /**The striped decode callback data to pass to #TH_DECCTL_SET_STRIPE_CB.*/ |
142 | typedef struct{ |
143 | /**An application-provided context pointer. |
144 | * This will be passed back verbatim to the application.*/ |
145 | void *ctx; |
146 | /**The callback function pointer.*/ |
147 | th_stripe_decoded_func stripe_decoded; |
148 | }th_stripe_callback; |
149 | |
150 | |
151 | |
152 | /**\name Decoder state |
153 | The following data structures are opaque, and their contents are not |
154 | publicly defined by this API. |
155 | Referring to their internals directly is unsupported, and may break without |
156 | warning.*/ |
157 | /*@{*/ |
158 | /**The decoder context.*/ |
159 | typedef struct th_dec_ctx th_dec_ctx; |
160 | /**Setup information. |
161 | This contains auxiliary information (Huffman tables and quantization |
162 | parameters) decoded from the setup header by th_decode_headerin() to be |
163 | passed to th_decode_alloc(). |
164 | It can be re-used to initialize any number of decoders, and can be freed |
165 | via th_setup_free() at any time.*/ |
166 | typedef struct th_setup_info th_setup_info; |
167 | /*@}*/ |
168 | |
169 | |
170 | |
171 | /**\defgroup decfuncs Functions for Decoding*/ |
172 | /*@{*/ |
173 | /**\name Functions for decoding |
174 | * You must link to <tt>libtheoradec</tt> if you use any of the |
175 | * functions in this section. |
176 | * |
177 | * The functions are listed in the order they are used in a typical decode. |
178 | * The basic steps are: |
179 | * - Parse the header packets by repeatedly calling th_decode_headerin(). |
180 | * - Allocate a #th_dec_ctx handle with th_decode_alloc(). |
181 | * - Call th_setup_free() to free any memory used for codec setup |
182 | * information. |
183 | * - Perform any additional decoder configuration with th_decode_ctl(). |
184 | * - For each video data packet: |
185 | * - Submit the packet to the decoder via th_decode_packetin(). |
186 | * - Retrieve the uncompressed video data via th_decode_ycbcr_out(). |
187 | * - Call th_decode_free() to release all decoder memory.*/ |
188 | /*@{*/ |
189 | /**Decodes the header packets of a Theora stream. |
190 | * This should be called on the initial packets of the stream, in succession, |
191 | * until it returns <tt>0</tt>, indicating that all headers have been |
192 | * processed, or an error is encountered. |
193 | * At least three header packets are required, and additional optional header |
194 | * packets may follow. |
195 | * This can be used on the first packet of any logical stream to determine if |
196 | * that stream is a Theora stream. |
197 | * \param _info A #th_info structure to fill in. |
198 | * This must have been previously initialized with |
199 | * th_info_init(). |
200 | * The application may immediately begin using the contents of |
201 | * this structure after the first header is decoded, though it |
202 | * must continue to be passed in on all subsequent calls. |
203 | * \param _tc A #th_comment structure to fill in. |
204 | * The application may immediately begin using the contents of |
205 | * this structure after the second header is decoded, though it |
206 | * must continue to be passed in on all subsequent calls. |
207 | * \param _setup Returns a pointer to additional, private setup information |
208 | * needed by the decoder. |
209 | * The contents of this pointer must be initialized to |
210 | * <tt>NULL</tt> on the first call, and the returned value must |
211 | * continue to be passed in on all subsequent calls. |
212 | * \param _op An <tt>ogg_packet</tt> structure which contains one of the |
213 | * initial packets of an Ogg logical stream. |
214 | * \return A positive value indicates that a Theora header was successfully |
215 | * processed. |
216 | * \retval 0 The first video data packet was encountered after all |
217 | * required header packets were parsed. |
218 | * The packet just passed in on this call should be saved |
219 | * and fed to th_decode_packetin() to begin decoding |
220 | * video data. |
221 | * \retval TH_EFAULT One of \a _info, \a _tc, or \a _setup was |
222 | * <tt>NULL</tt>. |
223 | * \retval TH_EBADHEADER \a _op was <tt>NULL</tt>, the packet was not the next |
224 | * header packet in the expected sequence, or the format |
225 | * of the header data was invalid. |
226 | * \retval TH_EVERSION The packet data was a Theora info header, but for a |
227 | * bitstream version not decodable with this version of |
228 | * <tt>libtheoradec</tt>. |
229 | * \retval TH_ENOTFORMAT The packet was not a Theora header. |
230 | */ |
231 | extern int (th_info *_info,th_comment *_tc, |
232 | th_setup_info **_setup,ogg_packet *_op); |
233 | /**Allocates a decoder instance. |
234 | * |
235 | * <b>Security Warning:</b> The Theora format supports very large frame sizes, |
236 | * potentially even larger than the address space of a 32-bit machine, and |
237 | * creating a decoder context allocates the space for several frames of data. |
238 | * If the allocation fails here, your program will crash, possibly at some |
239 | * future point because the OS kernel returned a valid memory range and will |
240 | * only fail when it tries to map the pages in it the first time they are |
241 | * used. |
242 | * Even if it succeeds, you may experience a denial of service if the frame |
243 | * size is large enough to cause excessive paging. |
244 | * If you are integrating libtheora in a larger application where such things |
245 | * are undesirable, it is highly recommended that you check the frame size in |
246 | * \a _info before calling this function and refuse to decode streams where it |
247 | * is larger than some reasonable maximum. |
248 | * libtheora will not check this for you, because there may be machines that |
249 | * can handle such streams and applications that wish to. |
250 | * \param _info A #th_info struct filled via th_decode_headerin(). |
251 | * \param _setup A #th_setup_info handle returned via |
252 | * th_decode_headerin(). |
253 | * \return The initialized #th_dec_ctx handle. |
254 | * \retval NULL If the decoding parameters were invalid.*/ |
255 | extern th_dec_ctx *th_decode_alloc(const th_info *_info, |
256 | const th_setup_info *_setup); |
257 | /**Releases all storage used for the decoder setup information. |
258 | * This should be called after you no longer want to create any decoders for |
259 | * a stream whose headers you have parsed with th_decode_headerin(). |
260 | * \param _setup The setup information to free. |
261 | * This can safely be <tt>NULL</tt>.*/ |
262 | extern void th_setup_free(th_setup_info *_setup); |
263 | /**Decoder control function. |
264 | * This is used to provide advanced control of the decoding process. |
265 | * \param _dec A #th_dec_ctx handle. |
266 | * \param _req The control code to process. |
267 | * See \ref decctlcodes "the list of available control codes" |
268 | * for details. |
269 | * \param _buf The parameters for this control code. |
270 | * \param _buf_sz The size of the parameter buffer.*/ |
271 | extern int th_decode_ctl(th_dec_ctx *_dec,int _req,void *_buf, |
272 | size_t _buf_sz); |
273 | /**Submits a packet containing encoded video data to the decoder. |
274 | * \param _dec A #th_dec_ctx handle. |
275 | * \param _op An <tt>ogg_packet</tt> containing encoded video data. |
276 | * \param _granpos Returns the granule position of the decoded packet. |
277 | * If non-<tt>NULL</tt>, the granule position for this specific |
278 | * packet is stored in this location. |
279 | * This is computed incrementally from previously decoded |
280 | * packets. |
281 | * After a seek, the correct granule position must be set via |
282 | * #TH_DECCTL_SET_GRANPOS for this to work properly. |
283 | * \retval 0 Success. |
284 | * A new decoded frame can be retrieved by calling |
285 | * th_decode_ycbcr_out(). |
286 | * \retval TH_DUPFRAME The packet represented a dropped (0-byte) frame. |
287 | * The player can skip the call to th_decode_ycbcr_out(), |
288 | * as the contents of the decoded frame buffer have not |
289 | * changed. |
290 | * \retval TH_EFAULT \a _dec or \a _op was <tt>NULL</tt>. |
291 | * \retval TH_EBADPACKET \a _op does not contain encoded video data. |
292 | * \retval TH_EIMPL The video data uses bitstream features which this |
293 | * library does not support.*/ |
294 | extern int th_decode_packetin(th_dec_ctx *_dec,const ogg_packet *_op, |
295 | ogg_int64_t *_granpos); |
296 | /**Outputs the next available frame of decoded Y'CbCr data. |
297 | * If a striped decode callback has been set with #TH_DECCTL_SET_STRIPE_CB, |
298 | * then the application does not need to call this function. |
299 | * \param _dec A #th_dec_ctx handle. |
300 | * \param _ycbcr A video buffer structure to fill in. |
301 | * <tt>libtheoradec</tt> will fill in all the members of this |
302 | * structure, including the pointers to the uncompressed video |
303 | * data. |
304 | * The memory for this video data is owned by |
305 | * <tt>libtheoradec</tt>. |
306 | * It may be freed or overwritten without notification when |
307 | * subsequent frames are decoded. |
308 | * \retval 0 Success |
309 | * \retval TH_EFAULT \a _dec or \a _ycbcr was <tt>NULL</tt>. |
310 | */ |
311 | extern int th_decode_ycbcr_out(th_dec_ctx *_dec, |
312 | th_ycbcr_buffer _ycbcr); |
313 | /**Frees an allocated decoder instance. |
314 | * \param _dec A #th_dec_ctx handle.*/ |
315 | extern void th_decode_free(th_dec_ctx *_dec); |
316 | /*@}*/ |
317 | /*@}*/ |
318 | |
319 | |
320 | |
321 | #if defined(__cplusplus) |
322 | } |
323 | #endif |
324 | |
325 | #endif |
326 | |