190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber/*
2f71323e297a928af368937089d3ed71239786f86Andreas Huber *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *
4f71323e297a928af368937089d3ed71239786f86Andreas Huber *  Use of this source code is governed by a BSD-style license
5f71323e297a928af368937089d3ed71239786f86Andreas Huber *  that can be found in the LICENSE file in the root of the source
6f71323e297a928af368937089d3ed71239786f86Andreas Huber *  tree. An additional intellectual property rights grant can be found
7f71323e297a928af368937089d3ed71239786f86Andreas Huber *  in the file PATENTS.  All contributing project authors may
8f71323e297a928af368937089d3ed71239786f86Andreas Huber *  be found in the AUTHORS file in the root of the source tree.
990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber */
1090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
1190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
1290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber/*!\defgroup codec Common Algorithm Interface
1390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * This abstraction allows applications to easily support multiple video
1490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * formats with minimal code duplication. This section describes the interface
1590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * common to all codecs (both encoders and decoders).
1690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * @{
1790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber */
1890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
1979f15823c34ae1e423108295e416213200bb280fAndreas Huber/*!\file
2090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * \brief Describes the codec algorithm interface to applications.
2190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *
2290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * This file describes the interface between an application and a
2390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * video codec algorithm.
2490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *
2590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * An application instantiates a specific codec instance by using
2690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * vpx_codec_init() and a pointer to the algorithm's interface structure:
2790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *     <pre>
2890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *     my_app.c:
2990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *       extern vpx_codec_iface_t my_codec;
3090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *       {
3190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *           vpx_codec_ctx_t algo;
3290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *           res = vpx_codec_init(&algo, &my_codec);
3390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *       }
3490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *     </pre>
3590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber *
3690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * Once initialized, the instance is manged using other functions from
3790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber * the vpx_codec_* family.
3890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber */
3990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#ifdef __cplusplus
4090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huberextern "C" {
4190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#endif
4290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
4390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#ifndef VPX_CODEC_H
4490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_CODEC_H
45f71323e297a928af368937089d3ed71239786f86Andreas Huber#include "vpx_integer.h"
4690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#include "vpx_image.h"
4790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
4890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Decorator indicating a function is deprecated */
4990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#ifndef DEPRECATED
5090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#if defined(__GNUC__) && __GNUC__
5190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define DEPRECATED          __attribute__ ((deprecated))
5290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
5390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#elif defined(_MSC_VER)
5490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define DEPRECATED
5590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define DECLSPEC_DEPRECATED __declspec(deprecated) /**< \copydoc #DEPRECATED */
5690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#else
5790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define DEPRECATED
5890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
5990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#endif
6090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#endif
6190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
6290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Decorator indicating a function is potentially unused */
6390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#ifdef UNUSED
6490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#elif __GNUC__
65538f6170b788de7408b06efc6613dc98579aa6a6Andreas Huber#define UNUSED __attribute__ ((unused))
6690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#else
6790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define UNUSED
6890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#endif
6990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
7090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Current ABI version number
7190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
7290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \internal
7390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * If this file is altered in any way that changes the ABI, this value
7490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * must be bumped.  Examples include, but are not limited to, changing
7590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * types, removing or reassigning enums, adding/removing/rearranging
7690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * fields to structures
7790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
7890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_CODEC_ABI_VERSION (2 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
7990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
8090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Algorithm return codes */
8190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    typedef enum {
8290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief Operation completed without error */
8390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_OK,
8490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
8590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief Unspecified error */
8690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_ERROR,
8790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
8890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief Memory operation failed */
8990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_MEM_ERROR,
9090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
9190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief ABI version mismatch */
9290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_ABI_MISMATCH,
9390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
9490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief Algorithm does not have required capability */
9590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_INCAPABLE,
9690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
9790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief The given bitstream is not supported.
9890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         *
9990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * The bitstream was unable to be parsed at the highest level. The decoder
10090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * is unable to proceed. This error \ref SHOULD be treated as fatal to the
10190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * stream. */
10290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_UNSUP_BITSTREAM,
10390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
10490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief Encoded bitstream uses an unsupported feature
10590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         *
10690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * The decoder does not implement a feature required by the encoder. This
10790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * return code should only be used for features that prevent future
10890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * pictures from being properly decoded. This error \ref MAY be treated as
10990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
11090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         */
11190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_UNSUP_FEATURE,
11290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
11390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief The coded data for this stream is corrupt or incomplete
11490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         *
11590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * There was a problem decoding the current frame.  This return code
11690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * should only be used for failures that prevent future pictures from
11790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * being properly decoded. This error \ref MAY be treated as fatal to the
11890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * stream or \ref MAY be treated as fatal to the current GOP. If decoding
11990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * is continued for the current GOP, artifacts may be present.
12090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         */
12190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_CORRUPT_FRAME,
12290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
12390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief An application-supplied parameter is not valid.
12490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         *
12590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         */
12690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        VPX_CODEC_INVALID_PARAM,
12790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
12890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*!\brief An iterator reached the end of list.
12990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         *
13090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         */
131538f6170b788de7408b06efc6613dc98579aa6a6Andreas Huber        VPX_CODEC_LIST_END
13290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
13390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    }
13490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_err_t;
13590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
13690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
13790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*! \brief Codec capabilities bitfield
13890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
13990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *  Each codec advertises the capabilities it supports as part of its
14090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
14190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *  or functionality, and are not required to be supported.
14290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
14390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *  The available flags are specified by VPX_CODEC_CAP_* defines.
14490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
14590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    typedef long vpx_codec_caps_t;
14690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
14790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
14879f15823c34ae1e423108295e416213200bb280fAndreas Huber#define VPX_CODEC_CAP_XMA     0x4 /**< Supports eXternal Memory Allocation */
14990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
15090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
15190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*! \brief Initialization-time Feature Enabling
15290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
15390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *  Certain codec features must be known at initialization time, to allow for
15490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *  proper memory allocation.
15590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
15690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *  The available flags are specified by VPX_CODEC_USE_* defines.
15790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
15890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    typedef long vpx_codec_flags_t;
15979f15823c34ae1e423108295e416213200bb280fAndreas Huber#define VPX_CODEC_USE_XMA 0x00000001    /**< Use eXternal Memory Allocation mode */
16090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
16190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
16290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Codec interface structure.
16390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
16490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Contains function pointers and other data private to the codec
16590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * implementation. This structure is opaque to the application.
16690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
16790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    typedef const struct vpx_codec_iface vpx_codec_iface_t;
16890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
16990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
17090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Codec private data structure.
17190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
17290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Contains data private to the codec implementation. This structure is opaque
17390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * to the application.
17490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
17590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    typedef       struct vpx_codec_priv  vpx_codec_priv_t;
17690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
17790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
17890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Iterator
17990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
18090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Opaque storage used for iterating over lists.
18190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
18290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    typedef const void *vpx_codec_iter_t;
18390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
18490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
18590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Codec context structure
18690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
18790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * All codecs \ref MUST support this context structure fully. In general,
18890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * this data should be considered private to the codec algorithm, and
18990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * not be manipulated or examined by the calling application. Applications
19090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * may reference the 'name' member to get a printable description of the
19190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * algorithm.
19290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
193f71323e297a928af368937089d3ed71239786f86Andreas Huber    typedef struct vpx_codec_ctx
19490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    {
19590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        const char              *name;        /**< Printable interface name */
19690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        vpx_codec_iface_t       *iface;       /**< Interface pointers */
19790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        vpx_codec_err_t          err;         /**< Last returned error */
19890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        const char              *err_detail;  /**< Detailed info, if available */
19990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        vpx_codec_flags_t        init_flags;  /**< Flags passed at init time */
20090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        union
20190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        {
20290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber            struct vpx_codec_dec_cfg  *dec;   /**< Decoder Configuration Pointer */
20390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber            struct vpx_codec_enc_cfg  *enc;   /**< Encoder Configuration Pointer */
20490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber            void                      *raw;
20590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        }                        config;      /**< Configuration pointer aliasing union */
20690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        vpx_codec_priv_t        *priv;        /**< Algorithm private storage */
20790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    } vpx_codec_ctx_t;
20890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
20990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
21090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*
21190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Library Version Number Interface
21290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
21390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * For example, see the following sample return values:
21490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
21590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
21690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
21790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
21890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
21990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Return the version information (as an integer)
22090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
22190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a packed encoding of the library version number. This will only include
22290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * the major.minor.patch component of the version number. Note that this encoded
22390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * value should be accessed through the macros provided, as the encoding may change
22490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * in the future.
22590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
22690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
22790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    int vpx_codec_version(void);
22890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_VERSION_MAJOR(v) ((v>>16)&0xff) /**< extract major from packed version */
22990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_VERSION_MINOR(v) ((v>>8)&0xff)  /**< extract minor from packed version */
23090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_VERSION_PATCH(v) ((v>>0)&0xff)  /**< extract patch from packed version */
23190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
23290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Return the version major number */
23390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff)
23490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
23579f15823c34ae1e423108295e416213200bb280fAndreas Huber    /*!\brief Return the version minor number */
23690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff)
23790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
23890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Return the version patch number */
23990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff)
24090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
24190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
24290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Return the version information (as a string)
24390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
24490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a printable string containing the full library version number. This may
24590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * contain additional text following the three digit version number, as to indicate
24690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * release candidates, prerelease versions, etc.
24790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
24890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
24990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    const char *vpx_codec_version_str(void);
25090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
25190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
25290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Return the version information (as a string)
25390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
25490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a printable "extra string". This is the component of the string returned
25590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * by vpx_codec_version_str() following the three digit version number.
25690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
25790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
25890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    const char *vpx_codec_version_extra_str(void);
25990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
26090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
26190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Return the build configuration
26290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
26390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a printable string containing an encoded version of the build
26490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * configuration. This may be useful to vpx support.
26590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
26690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
26790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    const char *vpx_codec_build_config(void);
26890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
26990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
27090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Return the name for a given interface
27190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
27290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a human readable string for name of the given codec interface.
27390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
27490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]    iface     Interface pointer
27590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
27690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
27790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
27890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
27990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
28090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Convert error number to printable string
28190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
28290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a human readable string for the last error returned by the
28390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * algorithm. The returned error will be one line and will not contain
28490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * any newline characters.
28590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
28690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
28790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]    err     Error number.
28890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
28990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
29090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    const char *vpx_codec_err_to_string(vpx_codec_err_t  err);
29190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
29290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
29390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Retrieve error synopsis for codec context
29490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
29590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a human readable string for the last error returned by the
29690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * algorithm. The returned error will be one line and will not contain
29790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * any newline characters.
29890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
29990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
30090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]    ctx     Pointer to this instance's context.
30190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
30290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
30390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    const char *vpx_codec_error(vpx_codec_ctx_t  *ctx);
30490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
30590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
30690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Retrieve detailed error information for codec context
30790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
30890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Returns a human readable string providing detailed information about
30990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * the last error.
31090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
31190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]    ctx     Pointer to this instance's context.
31290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
31390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval NULL
31490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     No detailed information is available.
31590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
31690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    const char *vpx_codec_error_detail(vpx_codec_ctx_t  *ctx);
31790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
31890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
31990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /* REQUIRED FUNCTIONS
32090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
32190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * The following functions are required to be implemented for all codecs.
32290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * They represent the base case functionality expected of all codecs.
32390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
32490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
32590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Destroy a codec instance
32690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
32790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Destroys a codec context, freeing any associated memory buffers.
32890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
32990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in] ctx   Pointer to this instance's context
33090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
33190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_OK
33290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     The codec algorithm initialized.
33390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_MEM_ERROR
33490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     Memory allocation failed.
33590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
33690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
33790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
33890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
33990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Get the capabilities of an algorithm.
34090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
34179f15823c34ae1e423108295e416213200bb280fAndreas Huber     * Retrieves the capabilities bitfield from the algorithm's interface.
34290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
34379f15823c34ae1e423108295e416213200bb280fAndreas Huber     * \param[in] iface   Pointer to the algorithm interface
34490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
34590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
34690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
34790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
34890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
34990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Control algorithm
35090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
35190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * This function is used to exchange algorithm specific data with the codec
35290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * instance. This can be used to implement features specific to a particular
35390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * algorithm.
35490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
35590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * This wrapper function dispatches the request to the helper function
35690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * associated with the given ctrl_id. It tries to call this function
35779f15823c34ae1e423108295e416213200bb280fAndreas Huber     * transparently, but will return #VPX_CODEC_ERROR if the request could not
35890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * be dispatched.
35990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
36090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Note that this function should not be used directly. Call the
36190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * #vpx_codec_control wrapper macro instead.
36290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
36390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]     ctx              Pointer to this instance's context
36490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]     ctrl_id          Algorithm specific control identifier
36590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
36690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_OK
36790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     The control request was processed.
36890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_ERROR
36990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     The control request was not processed.
37090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_INVALID_PARAM
37190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     The data was not valid.
37290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
37390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t  *ctx,
37490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber                                       int               ctrl_id,
37590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber                                       ...);
37690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
37790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define vpx_codec_control(ctx,id,data) vpx_codec_control_(ctx,id,data)
37890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define VPX_CTRL_USE_TYPE(id, typ)
37990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
38090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define VPX_CTRL_VOID(id, typ)
38190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
38290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#else
38390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief vpx_codec_control wrapper macro
38490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
38590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * This macro allows for type safe conversions across the variadic parameter
38690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * to vpx_codec_control_().
38790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
38890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \internal
38990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * It works by dispatching the call to the control function through a wrapper
39090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * function named with the id parameter.
39190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
39290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define vpx_codec_control(ctx,id,data) vpx_codec_control_##id(ctx,id,data)\
39390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /**<\hideinitializer*/
39490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
39590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
39690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief vpx_codec_control type definition macro
39790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
39890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * This macro allows for type safe conversions across the variadic parameter
39990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * to vpx_codec_control_(). It defines the type of the argument for a given
40090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * control identifier.
40190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
40290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \internal
40390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * It defines a static function with
40490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * the correctly typed arguments as a wrapper to the type-unsafe internal
40590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * function.
40690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
40790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define VPX_CTRL_USE_TYPE(id, typ) \
40890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    static vpx_codec_err_t \
40990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) UNUSED;\
41090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    \
41190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    static vpx_codec_err_t \
41290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
41390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        return vpx_codec_control_(ctx, ctrl_id, data);\
41490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    } /**<\hideinitializer*/
41590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
41690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
41790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief vpx_codec_control deprecated type definition macro
41890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
41990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
42090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * deprecated and should not be used. Consult the documentation for your
42190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * codec for more information.
42290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
42390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \internal
42490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * It defines a static function with the correctly typed arguments as a
42590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * wrapper to the type-unsafe internal function.
42690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
42790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
42890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    DECLSPEC_DEPRECATED static vpx_codec_err_t \
42990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) DEPRECATED UNUSED;\
43090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    \
43190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    DECLSPEC_DEPRECATED static vpx_codec_err_t \
43290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
43390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        return vpx_codec_control_(ctx, ctrl_id, data);\
43490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    } /**<\hideinitializer*/
43590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
43690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
43790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief vpx_codec_control void type definition macro
43890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
43990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * This macro allows for type safe conversions across the variadic parameter
44090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * to vpx_codec_control_(). It indicates that a given control identifier takes
44190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * no argument.
44290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
44390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \internal
44490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * It defines a static function without a data argument as a wrapper to the
44590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * type-unsafe internal function.
44690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
44790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#    define VPX_CTRL_VOID(id) \
44890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    static vpx_codec_err_t \
44990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_control_##id(vpx_codec_ctx_t*, int) UNUSED;\
45090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    \
45190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    static vpx_codec_err_t \
45290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id) {\
45390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        return vpx_codec_control_(ctx, ctrl_id);\
45490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    } /**<\hideinitializer*/
45590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
45690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
45790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#endif
45890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
45990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
46090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\defgroup cap_xma External Memory Allocation Functions
46190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
46290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * The following functions are required to be implemented for all codecs
46390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * that advertise the VPX_CODEC_CAP_XMA capability. Calling these functions
46490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * for codecs that don't advertise this capability will result in an error
46590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * code being returned, usually VPX_CODEC_INCAPABLE
46690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * @{
46790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
46890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
46990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
47090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Memory Map Entry
47190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
47290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * This structure is used to contain the properties of a memory segment. It
47390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * is populated by the codec in the request phase, and by the calling
47490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * application once the requested allocation has been performed.
47590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
47690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    typedef struct vpx_codec_mmap
47790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    {
47890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /*
47990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         * The following members are set by the codec when requesting a segment
48090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber         */
48190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        unsigned int   id;     /**< identifier for the segment's contents */
48290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        unsigned long  sz;     /**< size of the segment, in bytes */
48390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        unsigned int   align;  /**< required alignment of the segment, in bytes */
48490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        unsigned int   flags;  /**< bitfield containing segment properties */
48590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_CODEC_MEM_ZERO     0x1  /**< Segment must be zeroed by allocation */
48690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_CODEC_MEM_WRONLY   0x2  /**< Segment need not be readable */
48790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#define VPX_CODEC_MEM_FAST     0x4  /**< Place in fast memory, if available */
48890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
48990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        /* The following members are to be filled in by the allocation function */
49090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        void          *base;   /**< pointer to the allocated segment */
49190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        void (*dtor)(struct vpx_codec_mmap *map);         /**< destructor to call */
49290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber        void          *priv;   /**< allocator private storage */
49390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    } vpx_codec_mmap_t; /**< alias for struct vpx_codec_mmap */
49490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
49590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
49690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Iterate over the list of segments to allocate.
49790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
49890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Iterates over a list of the segments to allocate. The iterator storage
49990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * should be initialized to NULL to start the iteration. Iteration is complete
50090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * when this function returns VPX_CODEC_LIST_END. The amount of memory needed to
50179f15823c34ae1e423108295e416213200bb280fAndreas Huber     * allocate is dependent upon the size of the encoded stream. In cases where the
50290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * stream is not available at allocation time, a fixed size must be requested.
50390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * The codec will not be able to operate on streams larger than the size used at
50490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * allocation time.
50590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
50690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]      ctx     Pointer to this instance's context.
50790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[out]     mmap    Pointer to the memory map entry to populate.
50890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in,out]  iter    Iterator storage, initialized to NULL
50990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
51090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_OK
51190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     The memory map entry was populated.
51290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_ERROR
51390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     Codec does not support XMA mode.
51490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_MEM_ERROR
51590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     Unable to determine segment size from stream info.
51690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
51790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_err_t vpx_codec_get_mem_map(vpx_codec_ctx_t                *ctx,
51890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber                                          vpx_codec_mmap_t               *mmap,
51990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber                                          vpx_codec_iter_t               *iter);
52090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
52190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
52290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!\brief Identify allocated segments to codec instance
52390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
52490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * Stores a list of allocated segments in the codec. Segments \ref MUST be
52590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * passed in the order they are read from vpx_codec_get_mem_map(), but may be
52690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * passed in groups of any size. Segments \ref MUST be set only once. The
52790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * allocation function \ref MUST ensure that the vpx_codec_mmap_t::base member
52879f15823c34ae1e423108295e416213200bb280fAndreas Huber     * is non-NULL. If the segment requires cleanup handling (e.g., calling free()
52990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * or close()) then the vpx_codec_mmap_t::dtor member \ref MUST be populated.
53090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
53190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]      ctx     Pointer to this instance's context.
53290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]      mmaps   Pointer to the first memory map entry in the list.
53390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \param[in]      num_maps  Number of entries being set at this time
53490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *
53590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_OK
53690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     The segment was stored in the codec context.
53790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_INCAPABLE
53890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     Codec does not support XMA mode.
53990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     * \retval #VPX_CODEC_MEM_ERROR
54090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     *     Segment base address was not set, or segment was already stored.
54190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
54290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber     */
54390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    vpx_codec_err_t  vpx_codec_set_mem_map(vpx_codec_ctx_t   *ctx,
54490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber                                           vpx_codec_mmap_t  *mmaps,
54590d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber                                           unsigned int       num_maps);
54690d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
54790d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!@} - end defgroup cap_xma*/
54890d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber    /*!@} - end defgroup codec*/
54990d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
55090d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber
55190d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#endif
55290d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#ifdef __cplusplus
55390d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber}
55490d3ed91ae9228e1c8bab561b6138d4cb8c1e4fdAndreas Huber#endif
555