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