• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2016, Alliance for Open Media. All rights reserved
3  *
4  * This source code is subject to the terms of the BSD 2 Clause License and
5  * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
6  * was not distributed with this source code in the LICENSE file, you can
7  * obtain it at www.aomedia.org/license/software. If the Alliance for Open
8  * Media Patent License 1.0 was not distributed with this source code in the
9  * PATENTS file, you can obtain it at www.aomedia.org/license/patent.
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  * aom_codec_init() and a pointer to the algorithm's interface structure:
27  *     <pre>
28  *     my_app.c:
29  *       extern aom_codec_iface_t my_codec;
30  *       {
31  *           aom_codec_ctx_t algo;
32  *           res = aom_codec_init(&algo, &my_codec);
33  *       }
34  *     </pre>
35  *
36  * Once initialized, the instance is managed using other functions from
37  * the aom_codec_* family.
38  */
39 #ifndef AOM_AOM_AOM_CODEC_H_
40 #define AOM_AOM_AOM_CODEC_H_
41 
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
45 
46 #include "aom/aom_image.h"
47 #include "aom/aom_integer.h"
48 
49 /*!\brief Decorator indicating a function is deprecated */
50 #ifndef AOM_DEPRECATED
51 #if defined(__GNUC__) && __GNUC__
52 #define AOM_DEPRECATED __attribute__((deprecated))
53 #elif defined(_MSC_VER)
54 #define AOM_DEPRECATED
55 #else
56 #define AOM_DEPRECATED
57 #endif
58 #endif /* AOM_DEPRECATED */
59 
60 #ifndef AOM_DECLSPEC_DEPRECATED
61 #if defined(__GNUC__) && __GNUC__
62 #define AOM_DECLSPEC_DEPRECATED /**< \copydoc #AOM_DEPRECATED */
63 #elif defined(_MSC_VER)
64 /*!\brief \copydoc #AOM_DEPRECATED */
65 #define AOM_DECLSPEC_DEPRECATED __declspec(deprecated)
66 #else
67 #define AOM_DECLSPEC_DEPRECATED /**< \copydoc #AOM_DEPRECATED */
68 #endif
69 #endif /* AOM_DECLSPEC_DEPRECATED */
70 
71 /*!\brief Decorator indicating a function is potentially unused */
72 #ifdef AOM_UNUSED
73 #elif defined(__GNUC__) || defined(__clang__)
74 #define AOM_UNUSED __attribute__((unused))
75 #else
76 #define AOM_UNUSED
77 #endif
78 
79 /*!\brief Decorator indicating that given struct/union/enum is packed */
80 #ifndef ATTRIBUTE_PACKED
81 #if defined(__GNUC__) && __GNUC__
82 #define ATTRIBUTE_PACKED __attribute__((packed))
83 #elif defined(_MSC_VER)
84 #define ATTRIBUTE_PACKED
85 #else
86 #define ATTRIBUTE_PACKED
87 #endif
88 #endif /* ATTRIBUTE_PACKED */
89 
90 /*!\brief Current ABI version number
91  *
92  * \internal
93  * If this file is altered in any way that changes the ABI, this value
94  * must be bumped.  Examples include, but are not limited to, changing
95  * types, removing or reassigning enums, adding/removing/rearranging
96  * fields to structures
97  */
98 #define AOM_CODEC_ABI_VERSION (3 + AOM_IMAGE_ABI_VERSION) /**<\hideinitializer*/
99 
100 /*!\brief Algorithm return codes */
101 typedef enum {
102   /*!\brief Operation completed without error */
103   AOM_CODEC_OK,
104 
105   /*!\brief Unspecified error */
106   AOM_CODEC_ERROR,
107 
108   /*!\brief Memory operation failed */
109   AOM_CODEC_MEM_ERROR,
110 
111   /*!\brief ABI version mismatch */
112   AOM_CODEC_ABI_MISMATCH,
113 
114   /*!\brief Algorithm does not have required capability */
115   AOM_CODEC_INCAPABLE,
116 
117   /*!\brief The given bitstream is not supported.
118    *
119    * The bitstream was unable to be parsed at the highest level. The decoder
120    * is unable to proceed. This error \ref SHOULD be treated as fatal to the
121    * stream. */
122   AOM_CODEC_UNSUP_BITSTREAM,
123 
124   /*!\brief Encoded bitstream uses an unsupported feature
125    *
126    * The decoder does not implement a feature required by the encoder. This
127    * return code should only be used for features that prevent future
128    * pictures from being properly decoded. This error \ref MAY be treated as
129    * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
130    */
131   AOM_CODEC_UNSUP_FEATURE,
132 
133   /*!\brief The coded data for this stream is corrupt or incomplete
134    *
135    * There was a problem decoding the current frame.  This return code
136    * should only be used for failures that prevent future pictures from
137    * being properly decoded. This error \ref MAY be treated as fatal to the
138    * stream or \ref MAY be treated as fatal to the current GOP. If decoding
139    * is continued for the current GOP, artifacts may be present.
140    */
141   AOM_CODEC_CORRUPT_FRAME,
142 
143   /*!\brief An application-supplied parameter is not valid.
144    *
145    */
146   AOM_CODEC_INVALID_PARAM,
147 
148   /*!\brief An iterator reached the end of list.
149    *
150    */
151   AOM_CODEC_LIST_END
152 
153 } aom_codec_err_t;
154 
155 /*! \brief Codec capabilities bitfield
156  *
157  *  Each codec advertises the capabilities it supports as part of its
158  *  ::aom_codec_iface_t interface structure. Capabilities are extra interfaces
159  *  or functionality, and are not required to be supported.
160  *
161  *  The available flags are specified by AOM_CODEC_CAP_* defines.
162  */
163 typedef long aom_codec_caps_t;
164 #define AOM_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
165 #define AOM_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
166 
167 /*! \brief Initialization-time Feature Enabling
168  *
169  *  Certain codec features must be known at initialization time, to allow for
170  *  proper memory allocation.
171  *
172  *  The available flags are specified by AOM_CODEC_USE_* defines.
173  */
174 typedef long aom_codec_flags_t;
175 
176 /*!\brief Codec interface structure.
177  *
178  * Contains function pointers and other data private to the codec
179  * implementation. This structure is opaque to the application.
180  */
181 typedef const struct aom_codec_iface aom_codec_iface_t;
182 
183 /*!\brief Codec private data structure.
184  *
185  * Contains data private to the codec implementation. This structure is opaque
186  * to the application.
187  */
188 typedef struct aom_codec_priv aom_codec_priv_t;
189 
190 /*!\brief Iterator
191  *
192  * Opaque storage used for iterating over lists.
193  */
194 typedef const void *aom_codec_iter_t;
195 
196 /*!\brief Codec context structure
197  *
198  * All codecs \ref MUST support this context structure fully. In general,
199  * this data should be considered private to the codec algorithm, and
200  * not be manipulated or examined by the calling application. Applications
201  * may reference the 'name' member to get a printable description of the
202  * algorithm.
203  */
204 typedef struct aom_codec_ctx {
205   const char *name;             /**< Printable interface name */
206   aom_codec_iface_t *iface;     /**< Interface pointers */
207   aom_codec_err_t err;          /**< Last returned error */
208   const char *err_detail;       /**< Detailed info, if available */
209   aom_codec_flags_t init_flags; /**< Flags passed at init time */
210   union {
211     /**< Decoder Configuration Pointer */
212     const struct aom_codec_dec_cfg *dec;
213     /**< Encoder Configuration Pointer */
214     const struct aom_codec_enc_cfg *enc;
215     const void *raw;
216   } config;               /**< Configuration pointer aliasing union */
217   aom_codec_priv_t *priv; /**< Algorithm private storage */
218 } aom_codec_ctx_t;
219 
220 /*!\brief Bit depth for codec
221  * *
222  * This enumeration determines the bit depth of the codec.
223  */
224 typedef enum aom_bit_depth {
225   AOM_BITS_8 = 8,   /**<  8 bits */
226   AOM_BITS_10 = 10, /**< 10 bits */
227   AOM_BITS_12 = 12, /**< 12 bits */
228 } aom_bit_depth_t;
229 
230 /*!\brief Superblock size selection.
231  *
232  * Defines the superblock size used for encoding. The superblock size can
233  * either be fixed at 64x64 or 128x128 pixels, or it can be dynamically
234  * selected by the encoder for each frame.
235  */
236 typedef enum aom_superblock_size {
237   AOM_SUPERBLOCK_SIZE_64X64,   /**< Always use 64x64 superblocks. */
238   AOM_SUPERBLOCK_SIZE_128X128, /**< Always use 128x128 superblocks. */
239   AOM_SUPERBLOCK_SIZE_DYNAMIC  /**< Select superblock size dynamically. */
240 } aom_superblock_size_t;
241 
242 /*
243  * Library Version Number Interface
244  *
245  * For example, see the following sample return values:
246  *     aom_codec_version()           (1<<16 | 2<<8 | 3)
247  *     aom_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
248  *     aom_codec_version_extra_str() "rc1-16-gec6a1ba"
249  */
250 
251 /*!\brief Return the version information (as an integer)
252  *
253  * Returns a packed encoding of the library version number. This will only
254  * include
255  * the major.minor.patch component of the version number. Note that this encoded
256  * value should be accessed through the macros provided, as the encoding may
257  * change
258  * in the future.
259  *
260  */
261 int aom_codec_version(void);
262 
263 /*!\brief Return the version major number */
264 #define aom_codec_version_major() ((aom_codec_version() >> 16) & 0xff)
265 
266 /*!\brief Return the version minor number */
267 #define aom_codec_version_minor() ((aom_codec_version() >> 8) & 0xff)
268 
269 /*!\brief Return the version patch number */
270 #define aom_codec_version_patch() ((aom_codec_version() >> 0) & 0xff)
271 
272 /*!\brief Return the version information (as a string)
273  *
274  * Returns a printable string containing the full library version number. This
275  * may
276  * contain additional text following the three digit version number, as to
277  * indicate
278  * release candidates, prerelease versions, etc.
279  *
280  */
281 const char *aom_codec_version_str(void);
282 
283 /*!\brief Return the version information (as a string)
284  *
285  * Returns a printable "extra string". This is the component of the string
286  * returned
287  * by aom_codec_version_str() following the three digit version number.
288  *
289  */
290 const char *aom_codec_version_extra_str(void);
291 
292 /*!\brief Return the build configuration
293  *
294  * Returns a printable string containing an encoded version of the build
295  * configuration. This may be useful to aom support.
296  *
297  */
298 const char *aom_codec_build_config(void);
299 
300 /*!\brief Return the name for a given interface
301  *
302  * Returns a human readable string for name of the given codec interface.
303  *
304  * \param[in]    iface     Interface pointer
305  *
306  */
307 const char *aom_codec_iface_name(aom_codec_iface_t *iface);
308 
309 /*!\brief Convert error number to printable string
310  *
311  * Returns a human readable string for the last error returned by the
312  * algorithm. The returned error will be one line and will not contain
313  * any newline characters.
314  *
315  *
316  * \param[in]    err     Error number.
317  *
318  */
319 const char *aom_codec_err_to_string(aom_codec_err_t err);
320 
321 /*!\brief Retrieve error synopsis for codec context
322  *
323  * Returns a human readable string for the last error returned by the
324  * algorithm. The returned error will be one line and will not contain
325  * any newline characters.
326  *
327  *
328  * \param[in]    ctx     Pointer to this instance's context.
329  *
330  */
331 const char *aom_codec_error(aom_codec_ctx_t *ctx);
332 
333 /*!\brief Retrieve detailed error information for codec context
334  *
335  * Returns a human readable string providing detailed information about
336  * the last error.
337  *
338  * \param[in]    ctx     Pointer to this instance's context.
339  *
340  * \retval NULL
341  *     No detailed information is available.
342  */
343 const char *aom_codec_error_detail(aom_codec_ctx_t *ctx);
344 
345 /* REQUIRED FUNCTIONS
346  *
347  * The following functions are required to be implemented for all codecs.
348  * They represent the base case functionality expected of all codecs.
349  */
350 
351 /*!\brief Destroy a codec instance
352  *
353  * Destroys a codec context, freeing any associated memory buffers.
354  *
355  * \param[in] ctx   Pointer to this instance's context
356  *
357  * \retval #AOM_CODEC_OK
358  *     The codec algorithm initialized.
359  * \retval #AOM_CODEC_MEM_ERROR
360  *     Memory allocation failed.
361  */
362 aom_codec_err_t aom_codec_destroy(aom_codec_ctx_t *ctx);
363 
364 /*!\brief Get the capabilities of an algorithm.
365  *
366  * Retrieves the capabilities bitfield from the algorithm's interface.
367  *
368  * \param[in] iface   Pointer to the algorithm interface
369  *
370  */
371 aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface);
372 
373 /*!\brief Control algorithm
374  *
375  * This function is used to exchange algorithm specific data with the codec
376  * instance. This can be used to implement features specific to a particular
377  * algorithm.
378  *
379  * This wrapper function dispatches the request to the helper function
380  * associated with the given ctrl_id. It tries to call this function
381  * transparently, but will return #AOM_CODEC_ERROR if the request could not
382  * be dispatched.
383  *
384  * Note that this function should not be used directly. Call the
385  * #aom_codec_control wrapper macro instead.
386  *
387  * \param[in]     ctx              Pointer to this instance's context
388  * \param[in]     ctrl_id          Algorithm specific control identifier
389  *
390  * \retval #AOM_CODEC_OK
391  *     The control request was processed.
392  * \retval #AOM_CODEC_ERROR
393  *     The control request was not processed.
394  * \retval #AOM_CODEC_INVALID_PARAM
395  *     The data was not valid.
396  */
397 aom_codec_err_t aom_codec_control_(aom_codec_ctx_t *ctx, int ctrl_id, ...);
398 #if defined(AOM_DISABLE_CTRL_TYPECHECKS) && AOM_DISABLE_CTRL_TYPECHECKS
399 #define aom_codec_control(ctx, id, data) aom_codec_control_(ctx, id, data)
400 #define AOM_CTRL_USE_TYPE(id, typ)
401 #define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ)
402 #define AOM_CTRL_VOID(id, typ)
403 
404 #else
405 /*!\brief aom_codec_control wrapper macro
406  *
407  * This macro allows for type safe conversions across the variadic parameter
408  * to aom_codec_control_().
409  *
410  * \internal
411  * It works by dispatching the call to the control function through a wrapper
412  * function named with the id parameter.
413  */
414 #define aom_codec_control(ctx, id, data) \
415   aom_codec_control_##id(ctx, id, data) /**<\hideinitializer*/
416 
417 /*!\brief aom_codec_control type definition macro
418  *
419  * This macro allows for type safe conversions across the variadic parameter
420  * to aom_codec_control_(). It defines the type of the argument for a given
421  * control identifier.
422  *
423  * \internal
424  * It defines a static function with
425  * the correctly typed arguments as a wrapper to the type-unsafe internal
426  * function.
427  */
428 #define AOM_CTRL_USE_TYPE(id, typ)                                           \
429   static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *, int, typ) \
430       AOM_UNUSED;                                                            \
431                                                                              \
432   static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *ctx,        \
433                                                 int ctrl_id, typ data) {     \
434     return aom_codec_control_(ctx, ctrl_id, data);                           \
435   } /**<\hideinitializer*/
436 
437 /*!\brief aom_codec_control deprecated type definition macro
438  *
439  * Like #AOM_CTRL_USE_TYPE, but indicates that the specified control is
440  * deprecated and should not be used. Consult the documentation for your
441  * codec for more information.
442  *
443  * \internal
444  * It defines a static function with the correctly typed arguments as a
445  * wrapper to the type-unsafe internal function.
446  */
447 #define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ)                            \
448   AOM_DECLSPEC_DEPRECATED static aom_codec_err_t aom_codec_control_##id( \
449       aom_codec_ctx_t *, int, typ) AOM_DEPRECATED AOM_UNUSED;            \
450                                                                          \
451   AOM_DECLSPEC_DEPRECATED static aom_codec_err_t aom_codec_control_##id( \
452       aom_codec_ctx_t *ctx, int ctrl_id, typ data) {                     \
453     return aom_codec_control_(ctx, ctrl_id, data);                       \
454   } /**<\hideinitializer*/
455 
456 /*!\brief aom_codec_control void type definition macro
457  *
458  * This macro allows for type safe conversions across the variadic parameter
459  * to aom_codec_control_(). It indicates that a given control identifier takes
460  * no argument.
461  *
462  * \internal
463  * It defines a static function without a data argument as a wrapper to the
464  * type-unsafe internal function.
465  */
466 #define AOM_CTRL_VOID(id)                                               \
467   static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *, int) \
468       AOM_UNUSED;                                                       \
469                                                                         \
470   static aom_codec_err_t aom_codec_control_##id(aom_codec_ctx_t *ctx,   \
471                                                 int ctrl_id) {          \
472     return aom_codec_control_(ctx, ctrl_id);                            \
473   } /**<\hideinitializer*/
474 
475 #endif
476 
477 /*!\brief OBU types. */
478 typedef enum ATTRIBUTE_PACKED {
479   OBU_SEQUENCE_HEADER = 1,
480   OBU_TEMPORAL_DELIMITER = 2,
481   OBU_FRAME_HEADER = 3,
482   OBU_TILE_GROUP = 4,
483   OBU_METADATA = 5,
484   OBU_FRAME = 6,
485   OBU_REDUNDANT_FRAME_HEADER = 7,
486   OBU_TILE_LIST = 8,
487   OBU_PADDING = 15,
488 } OBU_TYPE;
489 
490 /*!\brief OBU metadata types. */
491 typedef enum {
492   OBU_METADATA_TYPE_AOM_RESERVED_0 = 0,
493   OBU_METADATA_TYPE_HDR_CLL = 1,
494   OBU_METADATA_TYPE_HDR_MDCV = 2,
495   OBU_METADATA_TYPE_SCALABILITY = 3,
496   OBU_METADATA_TYPE_ITUT_T35 = 4,
497   OBU_METADATA_TYPE_TIMECODE = 5,
498 } OBU_METADATA_TYPE;
499 
500 /*!\brief Returns string representation of OBU_TYPE.
501  *
502  * \param[in]     type            The OBU_TYPE to convert to string.
503  */
504 const char *aom_obu_type_to_string(OBU_TYPE type);
505 
506 /*!\brief Config Options
507  *
508  * This type allows to enumerate and control options defined for control
509  * via config file at runtime.
510  */
511 typedef struct cfg_options {
512   /*!\brief Reflects if ext_partition should be enabled
513    *
514    * If this value is non-zero it enabled the feature
515    */
516   unsigned int ext_partition;
517 } cfg_options_t;
518 
519 /*!@} - end defgroup codec*/
520 #ifdef __cplusplus
521 }
522 #endif
523 #endif  // AOM_AOM_AOM_CODEC_H_
524