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