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