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
