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