aom_codec.h 17 KB

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