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_dec_init() or vpx_codec_enc_init() and a pointer to the 26 * algorithm's interface structure: 27 * <pre> 28 * my_app.c: 29 * extern vpx_codec_iface_t my_codec; 30 * { 31 * vpx_codec_ctx_t algo; 32 * int threads = 4; 33 * vpx_codec_dec_cfg_t cfg = { threads, 0, 0 }; 34 * res = vpx_codec_dec_init(&algo, &my_codec, &cfg, 0); 35 * } 36 * </pre> 37 * 38 * Once initialized, the instance is manged using other functions from 39 * the vpx_codec_* family. 40 */ 41 #ifndef VPX_VPX_VPX_CODEC_H_ 42 #define VPX_VPX_VPX_CODEC_H_ 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 #include "./vpx_image.h" 49 #include "./vpx_integer.h" 50 51 /*!\brief Decorator indicating a function is deprecated */ 52 #ifndef VPX_DEPRECATED 53 #if defined(__GNUC__) 54 #define VPX_DEPRECATED __attribute__((deprecated)) 55 #elif defined(_MSC_VER) 56 #define VPX_DEPRECATED 57 #else 58 #define VPX_DEPRECATED 59 #endif 60 #endif /* VPX_DEPRECATED */ 61 62 #ifndef VPX_DECLSPEC_DEPRECATED 63 #if defined(__GNUC__) 64 #define VPX_DECLSPEC_DEPRECATED /**< \copydoc #VPX_DEPRECATED */ 65 #elif defined(_MSC_VER) 66 /*!\brief \copydoc #VPX_DEPRECATED */ 67 #define VPX_DECLSPEC_DEPRECATED __declspec(deprecated) 68 #else 69 #define VPX_DECLSPEC_DEPRECATED /**< \copydoc #VPX_DEPRECATED */ 70 #endif 71 #endif /* VPX_DECLSPEC_DEPRECATED */ 72 73 /*!\brief Decorator indicating a function is potentially unused */ 74 #ifndef VPX_UNUSED 75 #if defined(__GNUC__) || defined(__clang__) 76 #define VPX_UNUSED __attribute__((unused)) 77 #else 78 #define VPX_UNUSED 79 #endif 80 #endif /* VPX_UNUSED */ 81 82 /*!\brief Current ABI version number 83 * 84 * \internal 85 * If this file is altered in any way that changes the ABI, this value 86 * must be bumped. Examples include, but are not limited to, changing 87 * types, removing or reassigning enums, adding/removing/rearranging 88 * fields to structures 89 */ 90 #define VPX_CODEC_ABI_VERSION (4 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/ 91 92 /*!\brief Algorithm return codes */ 93 typedef enum { 94 /*!\brief Operation completed without error */ 95 VPX_CODEC_OK, 96 97 /*!\brief Unspecified error */ 98 VPX_CODEC_ERROR, 99 100 /*!\brief Memory operation failed */ 101 VPX_CODEC_MEM_ERROR, 102 103 /*!\brief ABI version mismatch */ 104 VPX_CODEC_ABI_MISMATCH, 105 106 /*!\brief Algorithm does not have required capability */ 107 VPX_CODEC_INCAPABLE, 108 109 /*!\brief The given bitstream is not supported. 110 * 111 * The bitstream was unable to be parsed at the highest level. The decoder 112 * is unable to proceed. This error \ref SHOULD be treated as fatal to the 113 * stream. */ 114 VPX_CODEC_UNSUP_BITSTREAM, 115 116 /*!\brief Encoded bitstream uses an unsupported feature 117 * 118 * The decoder does not implement a feature required by the encoder. This 119 * return code should only be used for features that prevent future 120 * pictures from being properly decoded. This error \ref MAY be treated as 121 * fatal to the stream or \ref MAY be treated as fatal to the current GOP. 122 */ 123 VPX_CODEC_UNSUP_FEATURE, 124 125 /*!\brief The coded data for this stream is corrupt or incomplete 126 * 127 * There was a problem decoding the current frame. This return code 128 * should only be used for failures that prevent future pictures from 129 * being properly decoded. This error \ref MAY be treated as fatal to the 130 * stream or \ref MAY be treated as fatal to the current GOP. If decoding 131 * is continued for the current GOP, artifacts may be present. 132 */ 133 VPX_CODEC_CORRUPT_FRAME, 134 135 /*!\brief An application-supplied parameter is not valid. 136 * 137 */ 138 VPX_CODEC_INVALID_PARAM, 139 140 /*!\brief An iterator reached the end of list. 141 * 142 */ 143 VPX_CODEC_LIST_END 144 145 } vpx_codec_err_t; 146 147 /*! \brief Codec capabilities bitfield 148 * 149 * Each codec advertises the capabilities it supports as part of its 150 * ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces 151 * or functionality, and are not required to be supported. 152 * 153 * The available flags are specified by VPX_CODEC_CAP_* defines. 154 */ 155 typedef long vpx_codec_caps_t; 156 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */ 157 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */ 158 159 /*! Can support images at greater than 8 bitdepth. 160 */ 161 #define VPX_CODEC_CAP_HIGHBITDEPTH 0x4 162 163 /*! \brief Initialization-time Feature Enabling 164 * 165 * Certain codec features must be known at initialization time, to allow for 166 * proper memory allocation. 167 * 168 * The available flags are specified by VPX_CODEC_USE_* defines. 169 */ 170 typedef long vpx_codec_flags_t; 171 172 /*!\brief Codec interface structure. 173 * 174 * Contains function pointers and other data private to the codec 175 * implementation. This structure is opaque to the application. 176 */ 177 typedef const struct vpx_codec_iface vpx_codec_iface_t; 178 179 /*!\brief Codec private data structure. 180 * 181 * Contains data private to the codec implementation. This structure is opaque 182 * to the application. 183 */ 184 typedef struct vpx_codec_priv vpx_codec_priv_t; 185 186 /*!\brief Iterator 187 * 188 * Opaque storage used for iterating over lists. 189 */ 190 typedef const void *vpx_codec_iter_t; 191 192 /*!\brief Codec context structure 193 * 194 * All codecs \ref MUST support this context structure fully. In general, 195 * this data should be considered private to the codec algorithm, and 196 * not be manipulated or examined by the calling application. Applications 197 * may reference the 'name' member to get a printable description of the 198 * algorithm. 199 */ 200 typedef struct vpx_codec_ctx { 201 const char *name; /**< Printable interface name */ 202 vpx_codec_iface_t *iface; /**< Interface pointers */ 203 vpx_codec_err_t err; /**< Last returned error */ 204 const char *err_detail; /**< Detailed info, if available */ 205 vpx_codec_flags_t init_flags; /**< Flags passed at init time */ 206 union { 207 /**< Decoder Configuration Pointer */ 208 const struct vpx_codec_dec_cfg *dec; 209 /**< Encoder Configuration Pointer */ 210 const struct vpx_codec_enc_cfg *enc; 211 const void *raw; 212 } config; /**< Configuration pointer aliasing union */ 213 vpx_codec_priv_t *priv; /**< Algorithm private storage */ 214 } vpx_codec_ctx_t; 215 216 /*!\brief Bit depth for codec 217 * * 218 * This enumeration determines the bit depth of the codec. 219 */ 220 typedef enum vpx_bit_depth { 221 VPX_BITS_8 = 8, /**< 8 bits */ 222 VPX_BITS_10 = 10, /**< 10 bits */ 223 VPX_BITS_12 = 12, /**< 12 bits */ 224 } vpx_bit_depth_t; 225 226 /* 227 * Library Version Number Interface 228 * 229 * For example, see the following sample return values: 230 * vpx_codec_version() (1<<16 | 2<<8 | 3) 231 * vpx_codec_version_str() "v1.2.3-rc1-16-gec6a1ba" 232 * vpx_codec_version_extra_str() "rc1-16-gec6a1ba" 233 */ 234 235 /*!\brief Return the version information (as an integer) 236 * 237 * Returns a packed encoding of the library version number. This will only 238 * include 239 * the major.minor.patch component of the version number. Note that this encoded 240 * value should be accessed through the macros provided, as the encoding may 241 * change 242 * in the future. 243 * 244 */ 245 int vpx_codec_version(void); 246 #define VPX_VERSION_MAJOR(v) \ 247 (((v) >> 16) & 0xff) /**< extract major from packed version */ 248 #define VPX_VERSION_MINOR(v) \ 249 (((v) >> 8) & 0xff) /**< extract minor from packed version */ 250 #define VPX_VERSION_PATCH(v) \ 251 (((v) >> 0) & 0xff) /**< extract patch from packed version */ 252 253 /*!\brief Return the version major number */ 254 #define vpx_codec_version_major() ((vpx_codec_version() >> 16) & 0xff) 255 256 /*!\brief Return the version minor number */ 257 #define vpx_codec_version_minor() ((vpx_codec_version() >> 8) & 0xff) 258 259 /*!\brief Return the version patch number */ 260 #define vpx_codec_version_patch() ((vpx_codec_version() >> 0) & 0xff) 261 262 /*!\brief Return the version information (as a string) 263 * 264 * Returns a printable string containing the full library version number. This 265 * may 266 * contain additional text following the three digit version number, as to 267 * indicate 268 * release candidates, prerelease versions, etc. 269 * 270 */ 271 const char *vpx_codec_version_str(void); 272 273 /*!\brief Return the version information (as a string) 274 * 275 * Returns a printable "extra string". This is the component of the string 276 * returned 277 * by vpx_codec_version_str() following the three digit version number. 278 * 279 */ 280 const char *vpx_codec_version_extra_str(void); 281 282 /*!\brief Return the build configuration 283 * 284 * Returns a printable string containing an encoded version of the build 285 * configuration. This may be useful to vpx support. 286 * 287 */ 288 const char *vpx_codec_build_config(void); 289 290 /*!\brief Return the name for a given interface 291 * 292 * Returns a human readable string for name of the given codec interface. 293 * 294 * \param[in] iface Interface pointer 295 * 296 */ 297 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface); 298 299 /*!\brief Convert error number to printable string 300 * 301 * Returns a human readable string for the last error returned by the 302 * algorithm. The returned error will be one line and will not contain 303 * any newline characters. 304 * 305 * 306 * \param[in] err Error number. 307 * 308 */ 309 const char *vpx_codec_err_to_string(vpx_codec_err_t err); 310 311 /*!\brief Retrieve error synopsis for codec context 312 * 313 * Returns a human readable string for the last error returned by the 314 * algorithm. The returned error will be one line and will not contain 315 * any newline characters. 316 * 317 * 318 * \param[in] ctx Pointer to this instance's context. 319 * 320 */ 321 const char *vpx_codec_error(const vpx_codec_ctx_t *ctx); 322 323 /*!\brief Retrieve detailed error information for codec context 324 * 325 * Returns a human readable string providing detailed information about 326 * the last error. The returned string is only valid until the next 327 * vpx_codec_* function call (except vpx_codec_error and 328 * vpx_codec_error_detail) on the codec context. 329 * 330 * \param[in] ctx Pointer to this instance's context. 331 * 332 * \retval NULL 333 * No detailed information is available. 334 */ 335 const char *vpx_codec_error_detail(const vpx_codec_ctx_t *ctx); 336 337 /* REQUIRED FUNCTIONS 338 * 339 * The following functions are required to be implemented for all codecs. 340 * They represent the base case functionality expected of all codecs. 341 */ 342 343 /*!\brief Destroy a codec instance 344 * 345 * Destroys a codec context, freeing any associated memory buffers. 346 * 347 * \param[in] ctx Pointer to this instance's context 348 * 349 * \retval #VPX_CODEC_OK 350 * The codec instance has been destroyed. 351 * \retval #VPX_CODEC_INVALID_PARAM 352 * ctx is a null pointer. 353 * \retval #VPX_CODEC_ERROR 354 * Codec context not initialized. 355 */ 356 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx); 357 358 /*!\brief Get the capabilities of an algorithm. 359 * 360 * Retrieves the capabilities bitfield from the algorithm's interface. 361 * 362 * \param[in] iface Pointer to the algorithm interface 363 * 364 */ 365 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface); 366 367 /*!\brief Control algorithm 368 * 369 * This function is used to exchange algorithm specific data with the codec 370 * instance. This can be used to implement features specific to a particular 371 * algorithm. 372 * 373 * This wrapper function dispatches the request to the helper function 374 * associated with the given ctrl_id. It tries to call this function 375 * transparently, but will return #VPX_CODEC_ERROR if the request could not 376 * be dispatched. 377 * 378 * Note that this function should not be used directly. Call the 379 * #vpx_codec_control wrapper macro instead. 380 * 381 * \param[in] ctx Pointer to this instance's context 382 * \param[in] ctrl_id Algorithm specific control identifier 383 * 384 * \retval #VPX_CODEC_OK 385 * The control request was processed. 386 * \retval #VPX_CODEC_ERROR 387 * The control request was not processed. 388 * \retval #VPX_CODEC_INVALID_PARAM 389 * The data was not valid. 390 */ 391 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, int ctrl_id, ...); 392 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS 393 #define vpx_codec_control(ctx, id, data) vpx_codec_control_(ctx, id, data) 394 #define VPX_CTRL_USE_TYPE(id, typ) 395 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) 396 #define VPX_CTRL_VOID(id, typ) 397 398 #else 399 /*!\brief vpx_codec_control wrapper macro 400 * 401 * This macro allows for type safe conversions across the variadic parameter 402 * to vpx_codec_control_(). 403 * 404 * \internal 405 * It works by dispatching the call to the control function through a wrapper 406 * function named with the id parameter. 407 */ 408 #define vpx_codec_control(ctx, id, data) \ 409 vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/ 410 411 /*!\brief vpx_codec_control type definition macro 412 * 413 * This macro allows for type safe conversions across the variadic parameter 414 * to vpx_codec_control_(). It defines the type of the argument for a given 415 * control identifier. 416 * 417 * \internal 418 * It defines a static function with 419 * the correctly typed arguments as a wrapper to the type-unsafe internal 420 * function. 421 */ 422 #define VPX_CTRL_USE_TYPE(id, typ) \ 423 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \ 424 VPX_UNUSED; \ 425 \ 426 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \ 427 int ctrl_id, typ data) { \ 428 return vpx_codec_control_(ctx, ctrl_id, data); \ 429 } /**<\hideinitializer*/ 430 431 /*!\brief vpx_codec_control deprecated type definition macro 432 * 433 * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is 434 * deprecated and should not be used. Consult the documentation for your 435 * codec for more information. 436 * 437 * \internal 438 * It defines a static function with the correctly typed arguments as a 439 * wrapper to the type-unsafe internal function. 440 */ 441 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 442 VPX_DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \ 443 vpx_codec_ctx_t *, int, typ) VPX_DEPRECATED VPX_UNUSED; \ 444 \ 445 VPX_DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \ 446 vpx_codec_ctx_t *ctx, int ctrl_id, typ data) { \ 447 return vpx_codec_control_(ctx, ctrl_id, data); \ 448 } /**<\hideinitializer*/ 449 450 /*!\brief vpx_codec_control void type definition macro 451 * 452 * This macro allows for type safe conversions across the variadic parameter 453 * to vpx_codec_control_(). It indicates that a given control identifier takes 454 * no argument. 455 * 456 * \internal 457 * It defines a static function without a data argument as a wrapper to the 458 * type-unsafe internal function. 459 */ 460 #define VPX_CTRL_VOID(id) \ 461 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \ 462 VPX_UNUSED; \ 463 \ 464 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \ 465 int ctrl_id) { \ 466 return vpx_codec_control_(ctx, ctrl_id); \ 467 } /**<\hideinitializer*/ 468 469 #endif 470 471 /*!@} - end defgroup codec*/ 472 #ifdef __cplusplus 473 } 474 #endif 475 #endif // VPX_VPX_VPX_CODEC_H_ 476