• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 vpx_codec.h
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 e_xternal 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 e_xternal 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 minr 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 capabliities bitfield from the algorithm's interface.
342      *
343      * \param[in] iface   Pointer to the alogrithm 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      * transparantly, 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 dependant 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 (eg, 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