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_CODEC_H_ 39 #define 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 DEPRECATED 50 #if defined(__GNUC__) && __GNUC__ 51 #define DEPRECATED __attribute__((deprecated)) 52 #elif defined(_MSC_VER) 53 #define DEPRECATED 54 #else 55 #define DEPRECATED 56 #endif 57 #endif /* DEPRECATED */ 58 59 #ifndef DECLSPEC_DEPRECATED 60 #if defined(__GNUC__) && __GNUC__ 61 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */ 62 #elif defined(_MSC_VER) 63 /*!\brief \copydoc #DEPRECATED */ 64 #define DECLSPEC_DEPRECATED __declspec(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 (4 + 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 } vpx_codec_err_t; 142 143 /*! \brief Codec capabilities bitfield 144 * 145 * Each codec advertises the capabilities it supports as part of its 146 * ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces 147 * or functionality, and are not required to be supported. 148 * 149 * The available flags are specified by VPX_CODEC_CAP_* defines. 150 */ 151 typedef long vpx_codec_caps_t; 152 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */ 153 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */ 154 155 /*! Can support images at greater than 8 bitdepth. 156 */ 157 #define VPX_CODEC_CAP_HIGHBITDEPTH 0x4 158 159 /*! \brief Initialization-time Feature Enabling 160 * 161 * Certain codec features must be known at initialization time, to allow for 162 * proper memory allocation. 163 * 164 * The available flags are specified by VPX_CODEC_USE_* defines. 165 */ 166 typedef long vpx_codec_flags_t; 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 /*!\brief Codec private data structure. 176 * 177 * Contains data private to the codec implementation. This structure is opaque 178 * to the application. 179 */ 180 typedef struct vpx_codec_priv vpx_codec_priv_t; 181 182 /*!\brief Iterator 183 * 184 * Opaque storage used for iterating over lists. 185 */ 186 typedef const void *vpx_codec_iter_t; 187 188 /*!\brief Codec context structure 189 * 190 * All codecs \ref MUST support this context structure fully. In general, 191 * this data should be considered private to the codec algorithm, and 192 * not be manipulated or examined by the calling application. Applications 193 * may reference the 'name' member to get a printable description of the 194 * algorithm. 195 */ 196 typedef struct vpx_codec_ctx { 197 const char *name; /**< Printable interface name */ 198 vpx_codec_iface_t *iface; /**< Interface pointers */ 199 vpx_codec_err_t err; /**< Last returned error */ 200 const char *err_detail; /**< Detailed info, if available */ 201 vpx_codec_flags_t init_flags; /**< Flags passed at init time */ 202 union { 203 /**< Decoder Configuration Pointer */ 204 const struct vpx_codec_dec_cfg *dec; 205 /**< Encoder Configuration Pointer */ 206 const struct vpx_codec_enc_cfg *enc; 207 const void *raw; 208 } config; /**< Configuration pointer aliasing union */ 209 vpx_codec_priv_t *priv; /**< Algorithm private storage */ 210 } vpx_codec_ctx_t; 211 212 /*!\brief Bit depth for codec 213 * * 214 * This enumeration determines the bit depth of the codec. 215 */ 216 typedef enum vpx_bit_depth { 217 VPX_BITS_8 = 8, /**< 8 bits */ 218 VPX_BITS_10 = 10, /**< 10 bits */ 219 VPX_BITS_12 = 12, /**< 12 bits */ 220 } vpx_bit_depth_t; 221 222 /* 223 * Library Version Number Interface 224 * 225 * For example, see the following sample return values: 226 * vpx_codec_version() (1<<16 | 2<<8 | 3) 227 * vpx_codec_version_str() "v1.2.3-rc1-16-gec6a1ba" 228 * vpx_codec_version_extra_str() "rc1-16-gec6a1ba" 229 */ 230 231 /*!\brief Return the version information (as an integer) 232 * 233 * Returns a packed encoding of the library version number. This will only 234 * include 235 * the major.minor.patch component of the version number. Note that this encoded 236 * value should be accessed through the macros provided, as the encoding may 237 * change 238 * in the future. 239 * 240 */ 241 int vpx_codec_version(void); 242 #define VPX_VERSION_MAJOR(v) \ 243 ((v >> 16) & 0xff) /**< extract major from packed version */ 244 #define VPX_VERSION_MINOR(v) \ 245 ((v >> 8) & 0xff) /**< extract minor from packed version */ 246 #define VPX_VERSION_PATCH(v) \ 247 ((v >> 0) & 0xff) /**< extract patch from packed version */ 248 249 /*!\brief Return the version major number */ 250 #define vpx_codec_version_major() ((vpx_codec_version() >> 16) & 0xff) 251 252 /*!\brief Return the version minor number */ 253 #define vpx_codec_version_minor() ((vpx_codec_version() >> 8) & 0xff) 254 255 /*!\brief Return the version patch number */ 256 #define vpx_codec_version_patch() ((vpx_codec_version() >> 0) & 0xff) 257 258 /*!\brief Return the version information (as a string) 259 * 260 * Returns a printable string containing the full library version number. This 261 * may 262 * contain additional text following the three digit version number, as to 263 * indicate 264 * release candidates, prerelease versions, etc. 265 * 266 */ 267 const char *vpx_codec_version_str(void); 268 269 /*!\brief Return the version information (as a string) 270 * 271 * Returns a printable "extra string". This is the component of the string 272 * returned 273 * by vpx_codec_version_str() following the three digit version number. 274 * 275 */ 276 const char *vpx_codec_version_extra_str(void); 277 278 /*!\brief Return the build configuration 279 * 280 * Returns a printable string containing an encoded version of the build 281 * configuration. This may be useful to vpx support. 282 * 283 */ 284 const char *vpx_codec_build_config(void); 285 286 /*!\brief Return the name for a given interface 287 * 288 * Returns a human readable string for name of the given codec interface. 289 * 290 * \param[in] iface Interface pointer 291 * 292 */ 293 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface); 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 /*!\brief Retrieve error synopsis for codec context 308 * 309 * Returns a human readable string for the last error returned by the 310 * algorithm. The returned error will be one line and will not contain 311 * any newline characters. 312 * 313 * 314 * \param[in] ctx Pointer to this instance's context. 315 * 316 */ 317 const char *vpx_codec_error(vpx_codec_ctx_t *ctx); 318 319 /*!\brief Retrieve detailed error information for codec context 320 * 321 * Returns a human readable string providing detailed information about 322 * the last error. 323 * 324 * \param[in] ctx Pointer to this instance's context. 325 * 326 * \retval NULL 327 * No detailed information is available. 328 */ 329 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx); 330 331 /* REQUIRED FUNCTIONS 332 * 333 * The following functions are required to be implemented for all codecs. 334 * They represent the base case functionality expected of all codecs. 335 */ 336 337 /*!\brief Destroy a codec instance 338 * 339 * Destroys a codec context, freeing any associated memory buffers. 340 * 341 * \param[in] ctx Pointer to this instance's context 342 * 343 * \retval #VPX_CODEC_OK 344 * The codec algorithm initialized. 345 * \retval #VPX_CODEC_MEM_ERROR 346 * Memory allocation failed. 347 */ 348 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx); 349 350 /*!\brief Get the capabilities of an algorithm. 351 * 352 * Retrieves the capabilities bitfield from the algorithm's interface. 353 * 354 * \param[in] iface Pointer to the algorithm interface 355 * 356 */ 357 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface); 358 359 /*!\brief Control algorithm 360 * 361 * This function is used to exchange algorithm specific data with the codec 362 * instance. This can be used to implement features specific to a particular 363 * algorithm. 364 * 365 * This wrapper function dispatches the request to the helper function 366 * associated with the given ctrl_id. It tries to call this function 367 * transparently, but will return #VPX_CODEC_ERROR if the request could not 368 * be dispatched. 369 * 370 * Note that this function should not be used directly. Call the 371 * #vpx_codec_control wrapper macro instead. 372 * 373 * \param[in] ctx Pointer to this instance's context 374 * \param[in] ctrl_id Algorithm specific control identifier 375 * 376 * \retval #VPX_CODEC_OK 377 * The control request was processed. 378 * \retval #VPX_CODEC_ERROR 379 * The control request was not processed. 380 * \retval #VPX_CODEC_INVALID_PARAM 381 * The data was not valid. 382 */ 383 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, int ctrl_id, ...); 384 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS 385 #define vpx_codec_control(ctx, id, data) vpx_codec_control_(ctx, id, data) 386 #define VPX_CTRL_USE_TYPE(id, typ) 387 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) 388 #define VPX_CTRL_VOID(id, typ) 389 390 #else 391 /*!\brief vpx_codec_control wrapper macro 392 * 393 * This macro allows for type safe conversions across the variadic parameter 394 * to vpx_codec_control_(). 395 * 396 * \internal 397 * It works by dispatching the call to the control function through a wrapper 398 * function named with the id parameter. 399 */ 400 #define vpx_codec_control(ctx, id, data) \ 401 vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/ 402 403 /*!\brief vpx_codec_control type definition macro 404 * 405 * This macro allows for type safe conversions across the variadic parameter 406 * to vpx_codec_control_(). It defines the type of the argument for a given 407 * control identifier. 408 * 409 * \internal 410 * It defines a static function with 411 * the correctly typed arguments as a wrapper to the type-unsafe internal 412 * function. 413 */ 414 #define VPX_CTRL_USE_TYPE(id, typ) \ 415 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \ 416 UNUSED; \ 417 \ 418 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \ 419 int ctrl_id, typ data) { \ 420 return vpx_codec_control_(ctx, ctrl_id, data); \ 421 } /**<\hideinitializer*/ 422 423 /*!\brief vpx_codec_control deprecated type definition macro 424 * 425 * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is 426 * deprecated and should not be used. Consult the documentation for your 427 * codec for more information. 428 * 429 * \internal 430 * It defines a static function with the correctly typed arguments as a 431 * wrapper to the type-unsafe internal function. 432 */ 433 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 434 DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \ 435 vpx_codec_ctx_t *, int, typ) DEPRECATED UNUSED; \ 436 \ 437 DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \ 438 vpx_codec_ctx_t *ctx, int ctrl_id, typ data) { \ 439 return vpx_codec_control_(ctx, ctrl_id, data); \ 440 } /**<\hideinitializer*/ 441 442 /*!\brief vpx_codec_control void type definition macro 443 * 444 * This macro allows for type safe conversions across the variadic parameter 445 * to vpx_codec_control_(). It indicates that a given control identifier takes 446 * no argument. 447 * 448 * \internal 449 * It defines a static function without a data argument as a wrapper to the 450 * type-unsafe internal function. 451 */ 452 #define VPX_CTRL_VOID(id) \ 453 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \ 454 UNUSED; \ 455 \ 456 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \ 457 int ctrl_id) { \ 458 return vpx_codec_control_(ctx, ctrl_id); \ 459 } /**<\hideinitializer*/ 460 461 #endif 462 463 /*!@} - end defgroup codec*/ 464 #ifdef __cplusplus 465 } 466 #endif 467 #endif // VPX_VPX_CODEC_H_ 468