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 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 * vpx_codec_init() and a pointer to the 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 * res = vpx_codec_init(&algo, &my_codec); 33 * } 34 * </pre> 35 * 36 * Once initialized, the instance is manged using other functions from 37 * the vpx_codec_* family. 38 */ 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 #ifndef VPX_CODEC_H 44 #define VPX_CODEC_H 45 #include "vpx_integer.h" 46 #include "vpx_image.h" 47 48 /*!\brief Decorator indicating a function is deprecated */ 49 #ifndef DEPRECATED 50 #if defined(__GNUC__) && __GNUC__ 51 #define DEPRECATED __attribute__ ((deprecated)) 52 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */ 53 #elif defined(_MSC_VER) 54 #define DEPRECATED 55 #define DECLSPEC_DEPRECATED __declspec(deprecated) /**< \copydoc #DEPRECATED */ 56 #else 57 #define DEPRECATED 58 #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */ 59 #endif 60 #endif 61 62 /*!\brief Decorator indicating a function is potentially unused */ 63 #ifdef UNUSED 64 #elif __GNUC__ 65 #define UNUSED __attribute__ ((unused)) 66 #else 67 #define UNUSED 68 #endif 69 70 /*!\brief Current ABI version number 71 * 72 * \internal 73 * If this file is altered in any way that changes the ABI, this value 74 * must be bumped. Examples include, but are not limited to, changing 75 * types, removing or reassigning enums, adding/removing/rearranging 76 * fields to structures 77 */ 78 #define VPX_CODEC_ABI_VERSION (2 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/ 79 80 /*!\brief Algorithm return codes */ 81 typedef enum { 82 /*!\brief Operation completed without error */ 83 VPX_CODEC_OK, 84 85 /*!\brief Unspecified error */ 86 VPX_CODEC_ERROR, 87 88 /*!\brief Memory operation failed */ 89 VPX_CODEC_MEM_ERROR, 90 91 /*!\brief ABI version mismatch */ 92 VPX_CODEC_ABI_MISMATCH, 93 94 /*!\brief Algorithm does not have required capability */ 95 VPX_CODEC_INCAPABLE, 96 97 /*!\brief The given bitstream is not supported. 98 * 99 * The bitstream was unable to be parsed at the highest level. The decoder 100 * is unable to proceed. This error \ref SHOULD be treated as fatal to the 101 * stream. */ 102 VPX_CODEC_UNSUP_BITSTREAM, 103 104 /*!\brief Encoded bitstream uses an unsupported feature 105 * 106 * The decoder does not implement a feature required by the encoder. This 107 * return code should only be used for features that prevent future 108 * pictures from being properly decoded. This error \ref MAY be treated as 109 * fatal to the stream or \ref MAY be treated as fatal to the current GOP. 110 */ 111 VPX_CODEC_UNSUP_FEATURE, 112 113 /*!\brief The coded data for this stream is corrupt or incomplete 114 * 115 * There was a problem decoding the current frame. This return code 116 * should only be used for failures that prevent future pictures from 117 * being properly decoded. This error \ref MAY be treated as fatal to the 118 * stream or \ref MAY be treated as fatal to the current GOP. If decoding 119 * is continued for the current GOP, artifacts may be present. 120 */ 121 VPX_CODEC_CORRUPT_FRAME, 122 123 /*!\brief An application-supplied parameter is not valid. 124 * 125 */ 126 VPX_CODEC_INVALID_PARAM, 127 128 /*!\brief An iterator reached the end of list. 129 * 130 */ 131 VPX_CODEC_LIST_END 132 133 } 134 vpx_codec_err_t; 135 136 137 /*! \brief Codec capabilities bitfield 138 * 139 * Each codec advertises the capabilities it supports as part of its 140 * ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces 141 * or functionality, and are not required to be supported. 142 * 143 * The available flags are specified by VPX_CODEC_CAP_* defines. 144 */ 145 typedef long vpx_codec_caps_t; 146 #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */ 147 #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */ 148 #define VPX_CODEC_CAP_XMA 0x4 /**< Supports eXternal Memory Allocation */ 149 150 151 /*! \brief Initialization-time Feature Enabling 152 * 153 * Certain codec features must be known at initialization time, to allow for 154 * proper memory allocation. 155 * 156 * The available flags are specified by VPX_CODEC_USE_* defines. 157 */ 158 typedef long vpx_codec_flags_t; 159 #define VPX_CODEC_USE_XMA 0x00000001 /**< Use eXternal Memory Allocation mode */ 160 161 162 /*!\brief Codec interface structure. 163 * 164 * Contains function pointers and other data private to the codec 165 * implementation. This structure is opaque to the application. 166 */ 167 typedef const struct vpx_codec_iface vpx_codec_iface_t; 168 169 170 /*!\brief Codec private data structure. 171 * 172 * Contains data private to the codec implementation. This structure is opaque 173 * to the application. 174 */ 175 typedef struct vpx_codec_priv vpx_codec_priv_t; 176 177 178 /*!\brief Iterator 179 * 180 * Opaque storage used for iterating over lists. 181 */ 182 typedef const void *vpx_codec_iter_t; 183 184 185 /*!\brief Codec context structure 186 * 187 * All codecs \ref MUST support this context structure fully. In general, 188 * this data should be considered private to the codec algorithm, and 189 * not be manipulated or examined by the calling application. Applications 190 * may reference the 'name' member to get a printable description of the 191 * algorithm. 192 */ 193 typedef struct vpx_codec_ctx 194 { 195 const char *name; /**< Printable interface name */ 196 vpx_codec_iface_t *iface; /**< Interface pointers */ 197 vpx_codec_err_t err; /**< Last returned error */ 198 const char *err_detail; /**< Detailed info, if available */ 199 vpx_codec_flags_t init_flags; /**< Flags passed at init time */ 200 union 201 { 202 struct vpx_codec_dec_cfg *dec; /**< Decoder Configuration Pointer */ 203 struct vpx_codec_enc_cfg *enc; /**< Encoder Configuration Pointer */ 204 void *raw; 205 } config; /**< Configuration pointer aliasing union */ 206 vpx_codec_priv_t *priv; /**< Algorithm private storage */ 207 } vpx_codec_ctx_t; 208 209 210 /* 211 * Library Version Number Interface 212 * 213 * For example, see the following sample return values: 214 * vpx_codec_version() (1<<16 | 2<<8 | 3) 215 * vpx_codec_version_str() "v1.2.3-rc1-16-gec6a1ba" 216 * vpx_codec_version_extra_str() "rc1-16-gec6a1ba" 217 */ 218 219 /*!\brief Return the version information (as an integer) 220 * 221 * Returns a packed encoding of the library version number. This will only include 222 * the major.minor.patch component of the version number. Note that this encoded 223 * value should be accessed through the macros provided, as the encoding may change 224 * in the future. 225 * 226 */ 227 int vpx_codec_version(void); 228 #define VPX_VERSION_MAJOR(v) ((v>>16)&0xff) /**< extract major from packed version */ 229 #define VPX_VERSION_MINOR(v) ((v>>8)&0xff) /**< extract minor from packed version */ 230 #define VPX_VERSION_PATCH(v) ((v>>0)&0xff) /**< extract patch from packed version */ 231 232 /*!\brief Return the version major number */ 233 #define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff) 234 235 /*!\brief Return the version minor number */ 236 #define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff) 237 238 /*!\brief Return the version patch number */ 239 #define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff) 240 241 242 /*!\brief Return the version information (as a string) 243 * 244 * Returns a printable string containing the full library version number. This may 245 * contain additional text following the three digit version number, as to indicate 246 * release candidates, prerelease versions, etc. 247 * 248 */ 249 const char *vpx_codec_version_str(void); 250 251 252 /*!\brief Return the version information (as a string) 253 * 254 * Returns a printable "extra string". This is the component of the string returned 255 * by vpx_codec_version_str() following the three digit version number. 256 * 257 */ 258 const char *vpx_codec_version_extra_str(void); 259 260 261 /*!\brief Return the build configuration 262 * 263 * Returns a printable string containing an encoded version of the build 264 * configuration. This may be useful to vpx support. 265 * 266 */ 267 const char *vpx_codec_build_config(void); 268 269 270 /*!\brief Return the name for a given interface 271 * 272 * Returns a human readable string for name of the given codec interface. 273 * 274 * \param[in] iface Interface pointer 275 * 276 */ 277 const char *vpx_codec_iface_name(vpx_codec_iface_t *iface); 278 279 280 /*!\brief Convert error number to printable string 281 * 282 * Returns a human readable string for the last error returned by the 283 * algorithm. The returned error will be one line and will not contain 284 * any newline characters. 285 * 286 * 287 * \param[in] err Error number. 288 * 289 */ 290 const char *vpx_codec_err_to_string(vpx_codec_err_t err); 291 292 293 /*!\brief Retrieve error synopsis for codec context 294 * 295 * Returns a human readable string for the last error returned by the 296 * algorithm. The returned error will be one line and will not contain 297 * any newline characters. 298 * 299 * 300 * \param[in] ctx Pointer to this instance's context. 301 * 302 */ 303 const char *vpx_codec_error(vpx_codec_ctx_t *ctx); 304 305 306 /*!\brief Retrieve detailed error information for codec context 307 * 308 * Returns a human readable string providing detailed information about 309 * the last error. 310 * 311 * \param[in] ctx Pointer to this instance's context. 312 * 313 * \retval NULL 314 * No detailed information is available. 315 */ 316 const char *vpx_codec_error_detail(vpx_codec_ctx_t *ctx); 317 318 319 /* REQUIRED FUNCTIONS 320 * 321 * The following functions are required to be implemented for all codecs. 322 * They represent the base case functionality expected of all codecs. 323 */ 324 325 /*!\brief Destroy a codec instance 326 * 327 * Destroys a codec context, freeing any associated memory buffers. 328 * 329 * \param[in] ctx Pointer to this instance's context 330 * 331 * \retval #VPX_CODEC_OK 332 * The codec algorithm initialized. 333 * \retval #VPX_CODEC_MEM_ERROR 334 * Memory allocation failed. 335 */ 336 vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx); 337 338 339 /*!\brief Get the capabilities of an algorithm. 340 * 341 * Retrieves the capabilities bitfield from the algorithm's interface. 342 * 343 * \param[in] iface Pointer to the algorithm interface 344 * 345 */ 346 vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface); 347 348 349 /*!\brief Control algorithm 350 * 351 * This function is used to exchange algorithm specific data with the codec 352 * instance. This can be used to implement features specific to a particular 353 * algorithm. 354 * 355 * This wrapper function dispatches the request to the helper function 356 * associated with the given ctrl_id. It tries to call this function 357 * transparently, but will return #VPX_CODEC_ERROR if the request could not 358 * be dispatched. 359 * 360 * Note that this function should not be used directly. Call the 361 * #vpx_codec_control wrapper macro instead. 362 * 363 * \param[in] ctx Pointer to this instance's context 364 * \param[in] ctrl_id Algorithm specific control identifier 365 * 366 * \retval #VPX_CODEC_OK 367 * The control request was processed. 368 * \retval #VPX_CODEC_ERROR 369 * The control request was not processed. 370 * \retval #VPX_CODEC_INVALID_PARAM 371 * The data was not valid. 372 */ 373 vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t *ctx, 374 int ctrl_id, 375 ...); 376 #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS 377 # define vpx_codec_control(ctx,id,data) vpx_codec_control_(ctx,id,data) 378 # define VPX_CTRL_USE_TYPE(id, typ) 379 # define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) 380 # define VPX_CTRL_VOID(id, typ) 381 382 #else 383 /*!\brief vpx_codec_control wrapper macro 384 * 385 * This macro allows for type safe conversions across the variadic parameter 386 * to vpx_codec_control_(). 387 * 388 * \internal 389 * It works by dispatching the call to the control function through a wrapper 390 * function named with the id parameter. 391 */ 392 # define vpx_codec_control(ctx,id,data) vpx_codec_control_##id(ctx,id,data)\ 393 /**<\hideinitializer*/ 394 395 396 /*!\brief vpx_codec_control type definition macro 397 * 398 * This macro allows for type safe conversions across the variadic parameter 399 * to vpx_codec_control_(). It defines the type of the argument for a given 400 * control identifier. 401 * 402 * \internal 403 * It defines a static function with 404 * the correctly typed arguments as a wrapper to the type-unsafe internal 405 * function. 406 */ 407 # define VPX_CTRL_USE_TYPE(id, typ) \ 408 static vpx_codec_err_t \ 409 vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) UNUSED;\ 410 \ 411 static vpx_codec_err_t \ 412 vpx_codec_control_##id(vpx_codec_ctx_t *ctx, int ctrl_id, typ data) {\ 413 return vpx_codec_control_(ctx, ctrl_id, data);\ 414 } /**<\hideinitializer*/ 415 416 417 /*!\brief vpx_codec_control deprecated type definition macro 418 * 419 * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is 420 * deprecated and should not be used. Consult the documentation for your 421 * codec for more information. 422 * 423 * \internal 424 * It defines a static function with the correctly typed arguments as a 425 * wrapper to the type-unsafe internal function. 426 */ 427 # define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 428 DECLSPEC_DEPRECATED static vpx_codec_err_t \ 429 vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) DEPRECATED UNUSED;\ 430 \ 431 DECLSPEC_DEPRECATED static vpx_codec_err_t \ 432 vpx_codec_control_##id(vpx_codec_ctx_t *ctx, int ctrl_id, typ data) {\ 433 return vpx_codec_control_(ctx, ctrl_id, data);\ 434 } /**<\hideinitializer*/ 435 436 437 /*!\brief vpx_codec_control void type definition macro 438 * 439 * This macro allows for type safe conversions across the variadic parameter 440 * to vpx_codec_control_(). It indicates that a given control identifier takes 441 * no argument. 442 * 443 * \internal 444 * It defines a static function without a data argument as a wrapper to the 445 * type-unsafe internal function. 446 */ 447 # define VPX_CTRL_VOID(id) \ 448 static vpx_codec_err_t \ 449 vpx_codec_control_##id(vpx_codec_ctx_t*, int) UNUSED;\ 450 \ 451 static vpx_codec_err_t \ 452 vpx_codec_control_##id(vpx_codec_ctx_t *ctx, int ctrl_id) {\ 453 return vpx_codec_control_(ctx, ctrl_id);\ 454 } /**<\hideinitializer*/ 455 456 457 #endif 458 459 460 /*!\defgroup cap_xma External Memory Allocation Functions 461 * 462 * The following functions are required to be implemented for all codecs 463 * that advertise the VPX_CODEC_CAP_XMA capability. Calling these functions 464 * for codecs that don't advertise this capability will result in an error 465 * code being returned, usually VPX_CODEC_INCAPABLE 466 * @{ 467 */ 468 469 470 /*!\brief Memory Map Entry 471 * 472 * This structure is used to contain the properties of a memory segment. It 473 * is populated by the codec in the request phase, and by the calling 474 * application once the requested allocation has been performed. 475 */ 476 typedef struct vpx_codec_mmap 477 { 478 /* 479 * The following members are set by the codec when requesting a segment 480 */ 481 unsigned int id; /**< identifier for the segment's contents */ 482 unsigned long sz; /**< size of the segment, in bytes */ 483 unsigned int align; /**< required alignment of the segment, in bytes */ 484 unsigned int flags; /**< bitfield containing segment properties */ 485 #define VPX_CODEC_MEM_ZERO 0x1 /**< Segment must be zeroed by allocation */ 486 #define VPX_CODEC_MEM_WRONLY 0x2 /**< Segment need not be readable */ 487 #define VPX_CODEC_MEM_FAST 0x4 /**< Place in fast memory, if available */ 488 489 /* The following members are to be filled in by the allocation function */ 490 void *base; /**< pointer to the allocated segment */ 491 void (*dtor)(struct vpx_codec_mmap *map); /**< destructor to call */ 492 void *priv; /**< allocator private storage */ 493 } vpx_codec_mmap_t; /**< alias for struct vpx_codec_mmap */ 494 495 496 /*!\brief Iterate over the list of segments to allocate. 497 * 498 * Iterates over a list of the segments to allocate. The iterator storage 499 * should be initialized to NULL to start the iteration. Iteration is complete 500 * when this function returns VPX_CODEC_LIST_END. The amount of memory needed to 501 * allocate is dependent upon the size of the encoded stream. In cases where the 502 * stream is not available at allocation time, a fixed size must be requested. 503 * The codec will not be able to operate on streams larger than the size used at 504 * allocation time. 505 * 506 * \param[in] ctx Pointer to this instance's context. 507 * \param[out] mmap Pointer to the memory map entry to populate. 508 * \param[in,out] iter Iterator storage, initialized to NULL 509 * 510 * \retval #VPX_CODEC_OK 511 * The memory map entry was populated. 512 * \retval #VPX_CODEC_ERROR 513 * Codec does not support XMA mode. 514 * \retval #VPX_CODEC_MEM_ERROR 515 * Unable to determine segment size from stream info. 516 */ 517 vpx_codec_err_t vpx_codec_get_mem_map(vpx_codec_ctx_t *ctx, 518 vpx_codec_mmap_t *mmap, 519 vpx_codec_iter_t *iter); 520 521 522 /*!\brief Identify allocated segments to codec instance 523 * 524 * Stores a list of allocated segments in the codec. Segments \ref MUST be 525 * passed in the order they are read from vpx_codec_get_mem_map(), but may be 526 * passed in groups of any size. Segments \ref MUST be set only once. The 527 * allocation function \ref MUST ensure that the vpx_codec_mmap_t::base member 528 * is non-NULL. If the segment requires cleanup handling (e.g., calling free() 529 * or close()) then the vpx_codec_mmap_t::dtor member \ref MUST be populated. 530 * 531 * \param[in] ctx Pointer to this instance's context. 532 * \param[in] mmaps Pointer to the first memory map entry in the list. 533 * \param[in] num_maps Number of entries being set at this time 534 * 535 * \retval #VPX_CODEC_OK 536 * The segment was stored in the codec context. 537 * \retval #VPX_CODEC_INCAPABLE 538 * Codec does not support XMA mode. 539 * \retval #VPX_CODEC_MEM_ERROR 540 * Segment base address was not set, or segment was already stored. 541 542 */ 543 vpx_codec_err_t vpx_codec_set_mem_map(vpx_codec_ctx_t *ctx, 544 vpx_codec_mmap_t *mmaps, 545 unsigned int num_maps); 546 547 /*!@} - end defgroup cap_xma*/ 548 /*!@} - end defgroup codec*/ 549 550 551 #endif 552 #ifdef __cplusplus 553 } 554 #endif 555
