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
40extern "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