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__) && __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__) && __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(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. 327 * 328 * \param[in] ctx Pointer to this instance's context. 329 * 330 * \retval NULL 331 * No detailed information is available. 332 */ 333 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx); 334 335 /* REQUIRED FUNCTIONS 336 * 337 * The following functions are required to be implemented for all codecs. 338 * They represent the base case functionality expected of all codecs. 339 */ 340 341 /*!\brief Destroy a codec instance 342 * 343 * Destroys a codec context, freeing any associated memory buffers. 344 * 345 * \param[in] ctx Pointer to this instance's context 346 * 347 * \retval #VPX_CODEC_OK 348 * The codec algorithm initialized. 349 * \retval #VPX_CODEC_MEM_ERROR 350 * Memory allocation failed. 351 */ 352 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx); 353 354 /*!\brief Get the capabilities of an algorithm. 355 * 356 * Retrieves the capabilities bitfield from the algorithm's interface. 357 * 358 * \param[in] iface Pointer to the algorithm interface 359 * 360 */ 361 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface); 362 363 /*!\brief Control algorithm 364 * 365 * This function is used to exchange algorithm specific data with the codec 366 * instance. This can be used to implement features specific to a particular 367 * algorithm. 368 * 369 * This wrapper function dispatches the request to the helper function 370 * associated with the given ctrl_id. It tries to call this function 371 * transparently, but will return #VPX_CODEC_ERROR if the request could not 372 * be dispatched. 373 * 374 * Note that this function should not be used directly. Call the 375 * #vpx_codec_control wrapper macro instead. 376 * 377 * \param[in] ctx Pointer to this instance's context 378 * \param[in] ctrl_id Algorithm specific control identifier 379 * 380 * \retval #VPX_CODEC_OK 381 * The control request was processed. 382 * \retval #VPX_CODEC_ERROR 383 * The control request was not processed. 384 * \retval #VPX_CODEC_INVALID_PARAM 385 * The data was not valid. 386 */ 387 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, int ctrl_id, ...); 388 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS 389 #define vpx_codec_control(ctx, id, data) vpx_codec_control_(ctx, id, data) 390 #define VPX_CTRL_USE_TYPE(id, typ) 391 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) 392 #define VPX_CTRL_VOID(id, typ) 393 394 #else 395 /*!\brief vpx_codec_control wrapper macro 396 * 397 * This macro allows for type safe conversions across the variadic parameter 398 * to vpx_codec_control_(). 399 * 400 * \internal 401 * It works by dispatching the call to the control function through a wrapper 402 * function named with the id parameter. 403 */ 404 #define vpx_codec_control(ctx, id, data) \ 405 vpx_codec_control_##id(ctx, id, data) /**<\hideinitializer*/ 406 407 /*!\brief vpx_codec_control type definition macro 408 * 409 * This macro allows for type safe conversions across the variadic parameter 410 * to vpx_codec_control_(). It defines the type of the argument for a given 411 * control identifier. 412 * 413 * \internal 414 * It defines a static function with 415 * the correctly typed arguments as a wrapper to the type-unsafe internal 416 * function. 417 */ 418 #define VPX_CTRL_USE_TYPE(id, typ) \ 419 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int, typ) \ 420 VPX_UNUSED; \ 421 \ 422 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \ 423 int ctrl_id, typ data) { \ 424 return vpx_codec_control_(ctx, ctrl_id, data); \ 425 } /**<\hideinitializer*/ 426 427 /*!\brief vpx_codec_control deprecated type definition macro 428 * 429 * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is 430 * deprecated and should not be used. Consult the documentation for your 431 * codec for more information. 432 * 433 * \internal 434 * It defines a static function with the correctly typed arguments as a 435 * wrapper to the type-unsafe internal function. 436 */ 437 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 438 VPX_DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \ 439 vpx_codec_ctx_t *, int, typ) VPX_DEPRECATED VPX_UNUSED; \ 440 \ 441 VPX_DECLSPEC_DEPRECATED static vpx_codec_err_t vpx_codec_control_##id( \ 442 vpx_codec_ctx_t *ctx, int ctrl_id, typ data) { \ 443 return vpx_codec_control_(ctx, ctrl_id, data); \ 444 } /**<\hideinitializer*/ 445 446 /*!\brief vpx_codec_control void type definition macro 447 * 448 * This macro allows for type safe conversions across the variadic parameter 449 * to vpx_codec_control_(). It indicates that a given control identifier takes 450 * no argument. 451 * 452 * \internal 453 * It defines a static function without a data argument as a wrapper to the 454 * type-unsafe internal function. 455 */ 456 #define VPX_CTRL_VOID(id) \ 457 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *, int) \ 458 VPX_UNUSED; \ 459 \ 460 static vpx_codec_err_t vpx_codec_control_##id(vpx_codec_ctx_t *ctx, \ 461 int ctrl_id) { \ 462 return vpx_codec_control_(ctx, ctrl_id); \ 463 } /**<\hideinitializer*/ 464 465 #endif 466 467 /*!@} - end defgroup codec*/ 468 #ifdef __cplusplus 469 } 470 #endif 471 #endif // VPX_VPX_VPX_CODEC_H_ 472