media/libvpx/vpx/vpx_codec.h@b8a032363ba2
media/libvpx/vpx/vpx_codec.h
Thu, 22 Jan 2015 13:21:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 22 Jan 2015 13:21:57 +0100
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
- permissions
- -rw-r--r--
Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6
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 */
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 */
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_CODEC_H
40 #define VPX_CODEC_H
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
46 #include "vpx_integer.h"
47 #include "vpx_image.h"
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 */
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 */
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
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*/
88 /*!\brief Algorithm return codes */
89 typedef enum {
90 /*!\brief Operation completed without error */
91 VPX_CODEC_OK,
93 /*!\brief Unspecified error */
94 VPX_CODEC_ERROR,
96 /*!\brief Memory operation failed */
97 VPX_CODEC_MEM_ERROR,
99 /*!\brief ABI version mismatch */
100 VPX_CODEC_ABI_MISMATCH,
102 /*!\brief Algorithm does not have required capability */
103 VPX_CODEC_INCAPABLE,
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,
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,
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,
131 /*!\brief An application-supplied parameter is not valid.
132 *
133 */
134 VPX_CODEC_INVALID_PARAM,
136 /*!\brief An iterator reached the end of list.
137 *
138 */
139 VPX_CODEC_LIST_END
141 }
142 vpx_codec_err_t;
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 */
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 */
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;
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;
186 /*!\brief Iterator
187 *
188 * Opaque storage used for iterating over lists.
189 */
190 typedef const void *vpx_codec_iter_t;
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;
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 */
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 */
238 /*!\brief Return the version major number */
239 #define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff)
241 /*!\brief Return the version minor number */
242 #define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff)
244 /*!\brief Return the version patch number */
245 #define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff)
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);
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);
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);
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);
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);
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);
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);
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 */
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);
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);
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)
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*/
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*/
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*/
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*/
463 #endif
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 */
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 */
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 */
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);
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.
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);
552 /*!@} - end defgroup cap_xma*/
553 /*!@} - end defgroup codec*/
554 #ifdef __cplusplus
555 }
556 #endif
557 #endif
