1 /*
2  *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
3  *
4  *  Use of this source code is governed by a BSD-style license
5  *  that can be found in the LICENSE file in the root of the source
6  *  tree. An additional intellectual property rights grant can be found
7  *  in the file PATENTS.  All contributing project authors may
8  *  be found in the AUTHORS file in the root of the source tree.
9  */
10 
11 
12 /*!\defgroup codec Common Algorithm Interface
13  * This abstraction allows applications to easily support multiple video
14  * formats with minimal code duplication. This section describes the interface
15  * common to all codecs (both encoders and decoders).
16  * @{
17  */
18 
19 /*!\file
20  * \brief Describes the codec algorithm interface to applications.
21  *
22  * This file describes the interface between an application and a
23  * video codec algorithm.
24  *
25  * An application instantiates a specific codec instance by using
26  * vpx_codec_init() and a pointer to the algorithm's interface structure:
27  *     <pre>
28  *     my_app.c:
29  *       extern vpx_codec_iface_t my_codec;
30  *       {
31  *           vpx_codec_ctx_t algo;
32  *           res = vpx_codec_init(&algo, &my_codec);
33  *       }
34  *     </pre>
35  *
36  * Once initialized, the instance is manged using other functions from
37  * the vpx_codec_* family.
38  */
39 #ifndef VPX_VPX_CODEC_H_
40 #define VPX_VPX_CODEC_H_
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 #include "./vpx_integer.h"
47 #include "./vpx_image.h"
48 
49   /*!\brief Decorator indicating a function is deprecated */
50 #ifndef DEPRECATED
51 #if defined(__GNUC__) && __GNUC__
52 #define DEPRECATED          __attribute__ ((deprecated))
53 #elif defined(_MSC_VER)
54 #define DEPRECATED
55 #else
56 #define DEPRECATED
57 #endif
58 #endif  /* DEPRECATED */
59 
60 #ifndef DECLSPEC_DEPRECATED
61 #if defined(__GNUC__) && __GNUC__
62 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
63 #elif defined(_MSC_VER)
64 #define DECLSPEC_DEPRECATED __declspec(deprecated) /**< \copydoc #DEPRECATED */
65 #else
66 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
67 #endif
68 #endif  /* DECLSPEC_DEPRECATED */
69 
70   /*!\brief Decorator indicating a function is potentially unused */
71 #ifdef UNUSED
72 #elif defined(__GNUC__) || defined(__clang__)
73 #define UNUSED __attribute__ ((unused))
74 #else
75 #define UNUSED
76 #endif
77 
78   /*!\brief Current ABI version number
79    *
80    * \internal
81    * If this file is altered in any way that changes the ABI, this value
82    * must be bumped.  Examples include, but are not limited to, changing
83    * types, removing or reassigning enums, adding/removing/rearranging
84    * fields to structures
85    */
86 #define VPX_CODEC_ABI_VERSION (3 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
87 
88   /*!\brief Algorithm return codes */
89   typedef enum {
90     /*!\brief Operation completed without error */
91     VPX_CODEC_OK,
92 
93     /*!\brief Unspecified error */
94     VPX_CODEC_ERROR,
95 
96     /*!\brief Memory operation failed */
97     VPX_CODEC_MEM_ERROR,
98 
99     /*!\brief ABI version mismatch */
100     VPX_CODEC_ABI_MISMATCH,
101 
102     /*!\brief Algorithm does not have required capability */
103     VPX_CODEC_INCAPABLE,
104 
105     /*!\brief The given bitstream is not supported.
106      *
107      * The bitstream was unable to be parsed at the highest level. The decoder
108      * is unable to proceed. This error \ref SHOULD be treated as fatal to the
109      * stream. */
110     VPX_CODEC_UNSUP_BITSTREAM,
111 
112     /*!\brief Encoded bitstream uses an unsupported feature
113      *
114      * The decoder does not implement a feature required by the encoder. This
115      * return code should only be used for features that prevent future
116      * pictures from being properly decoded. This error \ref MAY be treated as
117      * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
118      */
119     VPX_CODEC_UNSUP_FEATURE,
120 
121     /*!\brief The coded data for this stream is corrupt or incomplete
122      *
123      * There was a problem decoding the current frame.  This return code
124      * should only be used for failures that prevent future pictures from
125      * being properly decoded. This error \ref MAY be treated as fatal to the
126      * stream or \ref MAY be treated as fatal to the current GOP. If decoding
127      * is continued for the current GOP, artifacts may be present.
128      */
129     VPX_CODEC_CORRUPT_FRAME,
130 
131     /*!\brief An application-supplied parameter is not valid.
132      *
133      */
134     VPX_CODEC_INVALID_PARAM,
135 
136     /*!\brief An iterator reached the end of list.
137      *
138      */
139     VPX_CODEC_LIST_END
140 
141   }
142   vpx_codec_err_t;
143 
144 
145   /*! \brief Codec capabilities bitfield
146    *
147    *  Each codec advertises the capabilities it supports as part of its
148    *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
149    *  or functionality, and are not required to be supported.
150    *
151    *  The available flags are specified by VPX_CODEC_CAP_* defines.
152    */
153   typedef long vpx_codec_caps_t;
154 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
155 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
156 
157 
158   /*! \brief Initialization-time Feature Enabling
159    *
160    *  Certain codec features must be known at initialization time, to allow for
161    *  proper memory allocation.
162    *
163    *  The available flags are specified by VPX_CODEC_USE_* defines.
164    */
165   typedef long vpx_codec_flags_t;
166 
167 
168   /*!\brief Codec interface structure.
169    *
170    * Contains function pointers and other data private to the codec
171    * implementation. This structure is opaque to the application.
172    */
173   typedef const struct vpx_codec_iface vpx_codec_iface_t;
174 
175 
176   /*!\brief Codec private data structure.
177    *
178    * Contains data private to the codec implementation. This structure is opaque
179    * to the application.
180    */
181   typedef       struct vpx_codec_priv  vpx_codec_priv_t;
182 
183 
184   /*!\brief Iterator
185    *
186    * Opaque storage used for iterating over lists.
187    */
188   typedef const void *vpx_codec_iter_t;
189 
190 
191   /*!\brief Codec context structure
192    *
193    * All codecs \ref MUST support this context structure fully. In general,
194    * this data should be considered private to the codec algorithm, and
195    * not be manipulated or examined by the calling application. Applications
196    * may reference the 'name' member to get a printable description of the
197    * algorithm.
198    */
199   typedef struct vpx_codec_ctx {
200     const char              *name;        /**< Printable interface name */
201     vpx_codec_iface_t       *iface;       /**< Interface pointers */
202     vpx_codec_err_t          err;         /**< Last returned error */
203     const char              *err_detail;  /**< Detailed info, if available */
204     vpx_codec_flags_t        init_flags;  /**< Flags passed at init time */
205     union {
206       /**< Decoder Configuration Pointer */
207       const struct vpx_codec_dec_cfg *dec;
208       /**< Encoder Configuration Pointer */
209       const struct vpx_codec_enc_cfg *enc;
210       const void                     *raw;
211     }                        config;      /**< Configuration pointer aliasing union */
212     vpx_codec_priv_t        *priv;        /**< Algorithm private storage */
213   } vpx_codec_ctx_t;
214 
215   /*!\brief Bit depth for codec
216    * *
217    * This enumeration determines the bit depth of the codec.
218    */
219   typedef enum vpx_bit_depth {
220     VPX_BITS_8  =  8,  /**<  8 bits */
221     VPX_BITS_10 = 10,  /**< 10 bits */
222     VPX_BITS_12 = 12,  /**< 12 bits */
223   } vpx_bit_depth_t;
224 
225   /*
226    * Library Version Number Interface
227    *
228    * For example, see the following sample return values:
229    *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
230    *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
231    *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
232    */
233 
234   /*!\brief Return the version information (as an integer)
235    *
236    * Returns a packed encoding of the library version number. This will only include
237    * the major.minor.patch component of the version number. Note that this encoded
238    * value should be accessed through the macros provided, as the encoding may change
239    * in the future.
240    *
241    */
242   int vpx_codec_version(void);
243 #define VPX_VERSION_MAJOR(v) ((v>>16)&0xff) /**< extract major from packed version */
244 #define VPX_VERSION_MINOR(v) ((v>>8)&0xff)  /**< extract minor from packed version */
245 #define VPX_VERSION_PATCH(v) ((v>>0)&0xff)  /**< extract patch from packed version */
246 
247   /*!\brief Return the version major number */
248 #define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff)
249 
250   /*!\brief Return the version minor number */
251 #define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff)
252 
253   /*!\brief Return the version patch number */
254 #define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff)
255 
256 
257   /*!\brief Return the version information (as a string)
258    *
259    * Returns a printable string containing the full library version number. This may
260    * contain additional text following the three digit version number, as to indicate
261    * release candidates, prerelease versions, etc.
262    *
263    */
264   const char *vpx_codec_version_str(void);
265 
266 
267   /*!\brief Return the version information (as a string)
268    *
269    * Returns a printable "extra string". This is the component of the string returned
270    * by vpx_codec_version_str() following the three digit version number.
271    *
272    */
273   const char *vpx_codec_version_extra_str(void);
274 
275 
276   /*!\brief Return the build configuration
277    *
278    * Returns a printable string containing an encoded version of the build
279    * configuration. This may be useful to vpx support.
280    *
281    */
282   const char *vpx_codec_build_config(void);
283 
284 
285   /*!\brief Return the name for a given interface
286    *
287    * Returns a human readable string for name of the given codec interface.
288    *
289    * \param[in]    iface     Interface pointer
290    *
291    */
292   const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
293 
294 
295   /*!\brief Convert error number to printable string
296    *
297    * Returns a human readable string for the last error returned by the
298    * algorithm. The returned error will be one line and will not contain
299    * any newline characters.
300    *
301    *
302    * \param[in]    err     Error number.
303    *
304    */
305   const char *vpx_codec_err_to_string(vpx_codec_err_t  err);
306 
307 
308   /*!\brief Retrieve error synopsis for codec context
309    *
310    * Returns a human readable string for the last error returned by the
311    * algorithm. The returned error will be one line and will not contain
312    * any newline characters.
313    *
314    *
315    * \param[in]    ctx     Pointer to this instance's context.
316    *
317    */
318   const char *vpx_codec_error(vpx_codec_ctx_t  *ctx);
319 
320 
321   /*!\brief Retrieve detailed error information for codec context
322    *
323    * Returns a human readable string providing detailed information about
324    * the last error.
325    *
326    * \param[in]    ctx     Pointer to this instance's context.
327    *
328    * \retval NULL
329    *     No detailed information is available.
330    */
331   const char *vpx_codec_error_detail(vpx_codec_ctx_t  *ctx);
332 
333 
334   /* REQUIRED FUNCTIONS
335    *
336    * The following functions are required to be implemented for all codecs.
337    * They represent the base case functionality expected of all codecs.
338    */
339 
340   /*!\brief Destroy a codec instance
341    *
342    * Destroys a codec context, freeing any associated memory buffers.
343    *
344    * \param[in] ctx   Pointer to this instance's context
345    *
346    * \retval #VPX_CODEC_OK
347    *     The codec algorithm initialized.
348    * \retval #VPX_CODEC_MEM_ERROR
349    *     Memory allocation failed.
350    */
351   vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
352 
353 
354   /*!\brief Get the capabilities of an algorithm.
355    *
356    * Retrieves the capabilities bitfield from the algorithm's interface.
357    *
358    * \param[in] iface   Pointer to the algorithm interface
359    *
360    */
361   vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
362 
363 
364   /*!\brief Control algorithm
365    *
366    * This function is used to exchange algorithm specific data with the codec
367    * instance. This can be used to implement features specific to a particular
368    * algorithm.
369    *
370    * This wrapper function dispatches the request to the helper function
371    * associated with the given ctrl_id. It tries to call this function
372    * transparently, but will return #VPX_CODEC_ERROR if the request could not
373    * be dispatched.
374    *
375    * Note that this function should not be used directly. Call the
376    * #vpx_codec_control wrapper macro instead.
377    *
378    * \param[in]     ctx              Pointer to this instance's context
379    * \param[in]     ctrl_id          Algorithm specific control identifier
380    *
381    * \retval #VPX_CODEC_OK
382    *     The control request was processed.
383    * \retval #VPX_CODEC_ERROR
384    *     The control request was not processed.
385    * \retval #VPX_CODEC_INVALID_PARAM
386    *     The data was not valid.
387    */
388   vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t  *ctx,
389                                      int               ctrl_id,
390                                      ...);
391 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
392 #    define vpx_codec_control(ctx,id,data) vpx_codec_control_(ctx,id,data)
393 #    define VPX_CTRL_USE_TYPE(id, typ)
394 #    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
395 #    define VPX_CTRL_VOID(id, typ)
396 
397 #else
398   /*!\brief vpx_codec_control wrapper macro
399    *
400    * This macro allows for type safe conversions across the variadic parameter
401    * to vpx_codec_control_().
402    *
403    * \internal
404    * It works by dispatching the call to the control function through a wrapper
405    * function named with the id parameter.
406    */
407 #    define vpx_codec_control(ctx,id,data) vpx_codec_control_##id(ctx,id,data)\
408   /**<\hideinitializer*/
409 
410 
411   /*!\brief vpx_codec_control type definition macro
412    *
413    * This macro allows for type safe conversions across the variadic parameter
414    * to vpx_codec_control_(). It defines the type of the argument for a given
415    * control identifier.
416    *
417    * \internal
418    * It defines a static function with
419    * the correctly typed arguments as a wrapper to the type-unsafe internal
420    * function.
421    */
422 #    define VPX_CTRL_USE_TYPE(id, typ) \
423   static vpx_codec_err_t \
424   vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) UNUSED;\
425   \
426   static vpx_codec_err_t \
427   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
428     return vpx_codec_control_(ctx, ctrl_id, data);\
429   } /**<\hideinitializer*/
430 
431 
432   /*!\brief vpx_codec_control deprecated type definition macro
433    *
434    * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
435    * deprecated and should not be used. Consult the documentation for your
436    * codec for more information.
437    *
438    * \internal
439    * It defines a static function with the correctly typed arguments as a
440    * wrapper to the type-unsafe internal function.
441    */
442 #    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
443   DECLSPEC_DEPRECATED static vpx_codec_err_t \
444   vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) DEPRECATED UNUSED;\
445   \
446   DECLSPEC_DEPRECATED static vpx_codec_err_t \
447   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
448     return vpx_codec_control_(ctx, ctrl_id, data);\
449   } /**<\hideinitializer*/
450 
451 
452   /*!\brief vpx_codec_control void type definition macro
453    *
454    * This macro allows for type safe conversions across the variadic parameter
455    * to vpx_codec_control_(). It indicates that a given control identifier takes
456    * no argument.
457    *
458    * \internal
459    * It defines a static function without a data argument as a wrapper to the
460    * type-unsafe internal function.
461    */
462 #    define VPX_CTRL_VOID(id) \
463   static vpx_codec_err_t \
464   vpx_codec_control_##id(vpx_codec_ctx_t*, int) UNUSED;\
465   \
466   static vpx_codec_err_t \
467   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id) {\
468     return vpx_codec_control_(ctx, ctrl_id);\
469   } /**<\hideinitializer*/
470 
471 
472 #endif
473 
474   /*!@} - end defgroup codec*/
475 #ifdef __cplusplus
476 }
477 #endif
478 #endif  // VPX_VPX_CODEC_H_
479 
480