michael@0: /*
michael@0:  *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
michael@0:  *
michael@0:  *  Use of this source code is governed by a BSD-style license
michael@0:  *  that can be found in the LICENSE file in the root of the source
michael@0:  *  tree. An additional intellectual property rights grant can be found
michael@0:  *  in the file PATENTS.  All contributing project authors may
michael@0:  *  be found in the AUTHORS file in the root of the source tree.
michael@0:  */
michael@0: 
michael@0: 
michael@0: /*!\defgroup codec Common Algorithm Interface
michael@0:  * This abstraction allows applications to easily support multiple video
michael@0:  * formats with minimal code duplication. This section describes the interface
michael@0:  * common to all codecs (both encoders and decoders).
michael@0:  * @{
michael@0:  */
michael@0: 
michael@0: /*!\file
michael@0:  * \brief Describes the codec algorithm interface to applications.
michael@0:  *
michael@0:  * This file describes the interface between an application and a
michael@0:  * video codec algorithm.
michael@0:  *
michael@0:  * An application instantiates a specific codec instance by using
michael@0:  * vpx_codec_init() and a pointer to the algorithm's interface structure:
michael@0:  *     <pre>
michael@0:  *     my_app.c:
michael@0:  *       extern vpx_codec_iface_t my_codec;
michael@0:  *       {
michael@0:  *           vpx_codec_ctx_t algo;
michael@0:  *           res = vpx_codec_init(&algo, &my_codec);
michael@0:  *       }
michael@0:  *     </pre>
michael@0:  *
michael@0:  * Once initialized, the instance is manged using other functions from
michael@0:  * the vpx_codec_* family.
michael@0:  */
michael@0: #ifndef VPX_CODEC_H
michael@0: #define VPX_CODEC_H
michael@0: 
michael@0: #ifdef __cplusplus
michael@0: extern "C" {
michael@0: #endif
michael@0: 
michael@0: #include "vpx_integer.h"
michael@0: #include "vpx_image.h"
michael@0: 
michael@0:   /*!\brief Decorator indicating a function is deprecated */
michael@0: #ifndef DEPRECATED
michael@0: #if defined(__GNUC__) && __GNUC__
michael@0: #define DEPRECATED          __attribute__ ((deprecated))
michael@0: #elif defined(_MSC_VER)
michael@0: #define DEPRECATED
michael@0: #else
michael@0: #define DEPRECATED
michael@0: #endif
michael@0: #endif  /* DEPRECATED */
michael@0: 
michael@0: #ifndef DECLSPEC_DEPRECATED
michael@0: #if defined(__GNUC__) && __GNUC__
michael@0: #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
michael@0: #elif defined(_MSC_VER)
michael@0: #define DECLSPEC_DEPRECATED __declspec(deprecated) /**< \copydoc #DEPRECATED */
michael@0: #else
michael@0: #define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
michael@0: #endif
michael@0: #endif  /* DECLSPEC_DEPRECATED */
michael@0: 
michael@0:   /*!\brief Decorator indicating a function is potentially unused */
michael@0: #ifdef UNUSED
michael@0: #elif __GNUC__
michael@0: #define UNUSED __attribute__ ((unused))
michael@0: #else
michael@0: #define UNUSED
michael@0: #endif
michael@0: 
michael@0:   /*!\brief Current ABI version number
michael@0:    *
michael@0:    * \internal
michael@0:    * If this file is altered in any way that changes the ABI, this value
michael@0:    * must be bumped.  Examples include, but are not limited to, changing
michael@0:    * types, removing or reassigning enums, adding/removing/rearranging
michael@0:    * fields to structures
michael@0:    */
michael@0: #define VPX_CODEC_ABI_VERSION (2 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
michael@0: 
michael@0:   /*!\brief Algorithm return codes */
michael@0:   typedef enum {
michael@0:     /*!\brief Operation completed without error */
michael@0:     VPX_CODEC_OK,
michael@0: 
michael@0:     /*!\brief Unspecified error */
michael@0:     VPX_CODEC_ERROR,
michael@0: 
michael@0:     /*!\brief Memory operation failed */
michael@0:     VPX_CODEC_MEM_ERROR,
michael@0: 
michael@0:     /*!\brief ABI version mismatch */
michael@0:     VPX_CODEC_ABI_MISMATCH,
michael@0: 
michael@0:     /*!\brief Algorithm does not have required capability */
michael@0:     VPX_CODEC_INCAPABLE,
michael@0: 
michael@0:     /*!\brief The given bitstream is not supported.
michael@0:      *
michael@0:      * The bitstream was unable to be parsed at the highest level. The decoder
michael@0:      * is unable to proceed. This error \ref SHOULD be treated as fatal to the
michael@0:      * stream. */
michael@0:     VPX_CODEC_UNSUP_BITSTREAM,
michael@0: 
michael@0:     /*!\brief Encoded bitstream uses an unsupported feature
michael@0:      *
michael@0:      * The decoder does not implement a feature required by the encoder. This
michael@0:      * return code should only be used for features that prevent future
michael@0:      * pictures from being properly decoded. This error \ref MAY be treated as
michael@0:      * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
michael@0:      */
michael@0:     VPX_CODEC_UNSUP_FEATURE,
michael@0: 
michael@0:     /*!\brief The coded data for this stream is corrupt or incomplete
michael@0:      *
michael@0:      * There was a problem decoding the current frame.  This return code
michael@0:      * should only be used for failures that prevent future pictures from
michael@0:      * being properly decoded. This error \ref MAY be treated as fatal to the
michael@0:      * stream or \ref MAY be treated as fatal to the current GOP. If decoding
michael@0:      * is continued for the current GOP, artifacts may be present.
michael@0:      */
michael@0:     VPX_CODEC_CORRUPT_FRAME,
michael@0: 
michael@0:     /*!\brief An application-supplied parameter is not valid.
michael@0:      *
michael@0:      */
michael@0:     VPX_CODEC_INVALID_PARAM,
michael@0: 
michael@0:     /*!\brief An iterator reached the end of list.
michael@0:      *
michael@0:      */
michael@0:     VPX_CODEC_LIST_END
michael@0: 
michael@0:   }
michael@0:   vpx_codec_err_t;
michael@0: 
michael@0: 
michael@0:   /*! \brief Codec capabilities bitfield
michael@0:    *
michael@0:    *  Each codec advertises the capabilities it supports as part of its
michael@0:    *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
michael@0:    *  or functionality, and are not required to be supported.
michael@0:    *
michael@0:    *  The available flags are specified by VPX_CODEC_CAP_* defines.
michael@0:    */
michael@0:   typedef long vpx_codec_caps_t;
michael@0: #define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
michael@0: #define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
michael@0: #define VPX_CODEC_CAP_XMA     0x4 /**< Supports eXternal Memory Allocation */
michael@0: 
michael@0: 
michael@0:   /*! \brief Initialization-time Feature Enabling
michael@0:    *
michael@0:    *  Certain codec features must be known at initialization time, to allow for
michael@0:    *  proper memory allocation.
michael@0:    *
michael@0:    *  The available flags are specified by VPX_CODEC_USE_* defines.
michael@0:    */
michael@0:   typedef long vpx_codec_flags_t;
michael@0: #define VPX_CODEC_USE_XMA 0x00000001    /**< Use eXternal Memory Allocation mode */
michael@0: 
michael@0: 
michael@0:   /*!\brief Codec interface structure.
michael@0:    *
michael@0:    * Contains function pointers and other data private to the codec
michael@0:    * implementation. This structure is opaque to the application.
michael@0:    */
michael@0:   typedef const struct vpx_codec_iface vpx_codec_iface_t;
michael@0: 
michael@0: 
michael@0:   /*!\brief Codec private data structure.
michael@0:    *
michael@0:    * Contains data private to the codec implementation. This structure is opaque
michael@0:    * to the application.
michael@0:    */
michael@0:   typedef       struct vpx_codec_priv  vpx_codec_priv_t;
michael@0: 
michael@0: 
michael@0:   /*!\brief Iterator
michael@0:    *
michael@0:    * Opaque storage used for iterating over lists.
michael@0:    */
michael@0:   typedef const void *vpx_codec_iter_t;
michael@0: 
michael@0: 
michael@0:   /*!\brief Codec context structure
michael@0:    *
michael@0:    * All codecs \ref MUST support this context structure fully. In general,
michael@0:    * this data should be considered private to the codec algorithm, and
michael@0:    * not be manipulated or examined by the calling application. Applications
michael@0:    * may reference the 'name' member to get a printable description of the
michael@0:    * algorithm.
michael@0:    */
michael@0:   typedef struct vpx_codec_ctx {
michael@0:     const char              *name;        /**< Printable interface name */
michael@0:     vpx_codec_iface_t       *iface;       /**< Interface pointers */
michael@0:     vpx_codec_err_t          err;         /**< Last returned error */
michael@0:     const char              *err_detail;  /**< Detailed info, if available */
michael@0:     vpx_codec_flags_t        init_flags;  /**< Flags passed at init time */
michael@0:     union {
michael@0:       struct vpx_codec_dec_cfg  *dec;   /**< Decoder Configuration Pointer */
michael@0:       struct vpx_codec_enc_cfg  *enc;   /**< Encoder Configuration Pointer */
michael@0:       void                      *raw;
michael@0:     }                        config;      /**< Configuration pointer aliasing union */
michael@0:     vpx_codec_priv_t        *priv;        /**< Algorithm private storage */
michael@0:   } vpx_codec_ctx_t;
michael@0: 
michael@0: 
michael@0:   /*
michael@0:    * Library Version Number Interface
michael@0:    *
michael@0:    * For example, see the following sample return values:
michael@0:    *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
michael@0:    *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
michael@0:    *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
michael@0:    */
michael@0: 
michael@0:   /*!\brief Return the version information (as an integer)
michael@0:    *
michael@0:    * Returns a packed encoding of the library version number. This will only include
michael@0:    * the major.minor.patch component of the version number. Note that this encoded
michael@0:    * value should be accessed through the macros provided, as the encoding may change
michael@0:    * in the future.
michael@0:    *
michael@0:    */
michael@0:   int vpx_codec_version(void);
michael@0: #define VPX_VERSION_MAJOR(v) ((v>>16)&0xff) /**< extract major from packed version */
michael@0: #define VPX_VERSION_MINOR(v) ((v>>8)&0xff)  /**< extract minor from packed version */
michael@0: #define VPX_VERSION_PATCH(v) ((v>>0)&0xff)  /**< extract patch from packed version */
michael@0: 
michael@0:   /*!\brief Return the version major number */
michael@0: #define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff)
michael@0: 
michael@0:   /*!\brief Return the version minor number */
michael@0: #define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff)
michael@0: 
michael@0:   /*!\brief Return the version patch number */
michael@0: #define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff)
michael@0: 
michael@0: 
michael@0:   /*!\brief Return the version information (as a string)
michael@0:    *
michael@0:    * Returns a printable string containing the full library version number. This may
michael@0:    * contain additional text following the three digit version number, as to indicate
michael@0:    * release candidates, prerelease versions, etc.
michael@0:    *
michael@0:    */
michael@0:   const char *vpx_codec_version_str(void);
michael@0: 
michael@0: 
michael@0:   /*!\brief Return the version information (as a string)
michael@0:    *
michael@0:    * Returns a printable "extra string". This is the component of the string returned
michael@0:    * by vpx_codec_version_str() following the three digit version number.
michael@0:    *
michael@0:    */
michael@0:   const char *vpx_codec_version_extra_str(void);
michael@0: 
michael@0: 
michael@0:   /*!\brief Return the build configuration
michael@0:    *
michael@0:    * Returns a printable string containing an encoded version of the build
michael@0:    * configuration. This may be useful to vpx support.
michael@0:    *
michael@0:    */
michael@0:   const char *vpx_codec_build_config(void);
michael@0: 
michael@0: 
michael@0:   /*!\brief Return the name for a given interface
michael@0:    *
michael@0:    * Returns a human readable string for name of the given codec interface.
michael@0:    *
michael@0:    * \param[in]    iface     Interface pointer
michael@0:    *
michael@0:    */
michael@0:   const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
michael@0: 
michael@0: 
michael@0:   /*!\brief Convert error number to printable string
michael@0:    *
michael@0:    * Returns a human readable string for the last error returned by the
michael@0:    * algorithm. The returned error will be one line and will not contain
michael@0:    * any newline characters.
michael@0:    *
michael@0:    *
michael@0:    * \param[in]    err     Error number.
michael@0:    *
michael@0:    */
michael@0:   const char *vpx_codec_err_to_string(vpx_codec_err_t  err);
michael@0: 
michael@0: 
michael@0:   /*!\brief Retrieve error synopsis for codec context
michael@0:    *
michael@0:    * Returns a human readable string for the last error returned by the
michael@0:    * algorithm. The returned error will be one line and will not contain
michael@0:    * any newline characters.
michael@0:    *
michael@0:    *
michael@0:    * \param[in]    ctx     Pointer to this instance's context.
michael@0:    *
michael@0:    */
michael@0:   const char *vpx_codec_error(vpx_codec_ctx_t  *ctx);
michael@0: 
michael@0: 
michael@0:   /*!\brief Retrieve detailed error information for codec context
michael@0:    *
michael@0:    * Returns a human readable string providing detailed information about
michael@0:    * the last error.
michael@0:    *
michael@0:    * \param[in]    ctx     Pointer to this instance's context.
michael@0:    *
michael@0:    * \retval NULL
michael@0:    *     No detailed information is available.
michael@0:    */
michael@0:   const char *vpx_codec_error_detail(vpx_codec_ctx_t  *ctx);
michael@0: 
michael@0: 
michael@0:   /* REQUIRED FUNCTIONS
michael@0:    *
michael@0:    * The following functions are required to be implemented for all codecs.
michael@0:    * They represent the base case functionality expected of all codecs.
michael@0:    */
michael@0: 
michael@0:   /*!\brief Destroy a codec instance
michael@0:    *
michael@0:    * Destroys a codec context, freeing any associated memory buffers.
michael@0:    *
michael@0:    * \param[in] ctx   Pointer to this instance's context
michael@0:    *
michael@0:    * \retval #VPX_CODEC_OK
michael@0:    *     The codec algorithm initialized.
michael@0:    * \retval #VPX_CODEC_MEM_ERROR
michael@0:    *     Memory allocation failed.
michael@0:    */
michael@0:   vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
michael@0: 
michael@0: 
michael@0:   /*!\brief Get the capabilities of an algorithm.
michael@0:    *
michael@0:    * Retrieves the capabilities bitfield from the algorithm's interface.
michael@0:    *
michael@0:    * \param[in] iface   Pointer to the algorithm interface
michael@0:    *
michael@0:    */
michael@0:   vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
michael@0: 
michael@0: 
michael@0:   /*!\brief Control algorithm
michael@0:    *
michael@0:    * This function is used to exchange algorithm specific data with the codec
michael@0:    * instance. This can be used to implement features specific to a particular
michael@0:    * algorithm.
michael@0:    *
michael@0:    * This wrapper function dispatches the request to the helper function
michael@0:    * associated with the given ctrl_id. It tries to call this function
michael@0:    * transparently, but will return #VPX_CODEC_ERROR if the request could not
michael@0:    * be dispatched.
michael@0:    *
michael@0:    * Note that this function should not be used directly. Call the
michael@0:    * #vpx_codec_control wrapper macro instead.
michael@0:    *
michael@0:    * \param[in]     ctx              Pointer to this instance's context
michael@0:    * \param[in]     ctrl_id          Algorithm specific control identifier
michael@0:    *
michael@0:    * \retval #VPX_CODEC_OK
michael@0:    *     The control request was processed.
michael@0:    * \retval #VPX_CODEC_ERROR
michael@0:    *     The control request was not processed.
michael@0:    * \retval #VPX_CODEC_INVALID_PARAM
michael@0:    *     The data was not valid.
michael@0:    */
michael@0:   vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t  *ctx,
michael@0:                                      int               ctrl_id,
michael@0:                                      ...);
michael@0: #if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
michael@0: #    define vpx_codec_control(ctx,id,data) vpx_codec_control_(ctx,id,data)
michael@0: #    define VPX_CTRL_USE_TYPE(id, typ)
michael@0: #    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
michael@0: #    define VPX_CTRL_VOID(id, typ)
michael@0: 
michael@0: #else
michael@0:   /*!\brief vpx_codec_control wrapper macro
michael@0:    *
michael@0:    * This macro allows for type safe conversions across the variadic parameter
michael@0:    * to vpx_codec_control_().
michael@0:    *
michael@0:    * \internal
michael@0:    * It works by dispatching the call to the control function through a wrapper
michael@0:    * function named with the id parameter.
michael@0:    */
michael@0: #    define vpx_codec_control(ctx,id,data) vpx_codec_control_##id(ctx,id,data)\
michael@0:   /**<\hideinitializer*/
michael@0: 
michael@0: 
michael@0:   /*!\brief vpx_codec_control type definition macro
michael@0:    *
michael@0:    * This macro allows for type safe conversions across the variadic parameter
michael@0:    * to vpx_codec_control_(). It defines the type of the argument for a given
michael@0:    * control identifier.
michael@0:    *
michael@0:    * \internal
michael@0:    * It defines a static function with
michael@0:    * the correctly typed arguments as a wrapper to the type-unsafe internal
michael@0:    * function.
michael@0:    */
michael@0: #    define VPX_CTRL_USE_TYPE(id, typ) \
michael@0:   static vpx_codec_err_t \
michael@0:   vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) UNUSED;\
michael@0:   \
michael@0:   static vpx_codec_err_t \
michael@0:   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
michael@0:     return vpx_codec_control_(ctx, ctrl_id, data);\
michael@0:   } /**<\hideinitializer*/
michael@0: 
michael@0: 
michael@0:   /*!\brief vpx_codec_control deprecated type definition macro
michael@0:    *
michael@0:    * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
michael@0:    * deprecated and should not be used. Consult the documentation for your
michael@0:    * codec for more information.
michael@0:    *
michael@0:    * \internal
michael@0:    * It defines a static function with the correctly typed arguments as a
michael@0:    * wrapper to the type-unsafe internal function.
michael@0:    */
michael@0: #    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
michael@0:   DECLSPEC_DEPRECATED static vpx_codec_err_t \
michael@0:   vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) DEPRECATED UNUSED;\
michael@0:   \
michael@0:   DECLSPEC_DEPRECATED static vpx_codec_err_t \
michael@0:   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
michael@0:     return vpx_codec_control_(ctx, ctrl_id, data);\
michael@0:   } /**<\hideinitializer*/
michael@0: 
michael@0: 
michael@0:   /*!\brief vpx_codec_control void type definition macro
michael@0:    *
michael@0:    * This macro allows for type safe conversions across the variadic parameter
michael@0:    * to vpx_codec_control_(). It indicates that a given control identifier takes
michael@0:    * no argument.
michael@0:    *
michael@0:    * \internal
michael@0:    * It defines a static function without a data argument as a wrapper to the
michael@0:    * type-unsafe internal function.
michael@0:    */
michael@0: #    define VPX_CTRL_VOID(id) \
michael@0:   static vpx_codec_err_t \
michael@0:   vpx_codec_control_##id(vpx_codec_ctx_t*, int) UNUSED;\
michael@0:   \
michael@0:   static vpx_codec_err_t \
michael@0:   vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id) {\
michael@0:     return vpx_codec_control_(ctx, ctrl_id);\
michael@0:   } /**<\hideinitializer*/
michael@0: 
michael@0: 
michael@0: #endif
michael@0: 
michael@0: 
michael@0:   /*!\defgroup cap_xma External Memory Allocation Functions
michael@0:    *
michael@0:    * The following functions are required to be implemented for all codecs
michael@0:    * that advertise the VPX_CODEC_CAP_XMA capability. Calling these functions
michael@0:    * for codecs that don't advertise this capability will result in an error
michael@0:    * code being returned, usually VPX_CODEC_INCAPABLE
michael@0:    * @{
michael@0:    */
michael@0: 
michael@0: 
michael@0:   /*!\brief Memory Map Entry
michael@0:    *
michael@0:    * This structure is used to contain the properties of a memory segment. It
michael@0:    * is populated by the codec in the request phase, and by the calling
michael@0:    * application once the requested allocation has been performed.
michael@0:    */
michael@0:   typedef struct vpx_codec_mmap {
michael@0:     /*
michael@0:      * The following members are set by the codec when requesting a segment
michael@0:      */
michael@0:     unsigned int   id;     /**< identifier for the segment's contents */
michael@0:     unsigned long  sz;     /**< size of the segment, in bytes */
michael@0:     unsigned int   align;  /**< required alignment of the segment, in bytes */
michael@0:     unsigned int   flags;  /**< bitfield containing segment properties */
michael@0: #define VPX_CODEC_MEM_ZERO     0x1  /**< Segment must be zeroed by allocation */
michael@0: #define VPX_CODEC_MEM_WRONLY   0x2  /**< Segment need not be readable */
michael@0: #define VPX_CODEC_MEM_FAST     0x4  /**< Place in fast memory, if available */
michael@0: 
michael@0:     /* The following members are to be filled in by the allocation function */
michael@0:     void          *base;   /**< pointer to the allocated segment */
michael@0:     void (*dtor)(struct vpx_codec_mmap *map);         /**< destructor to call */
michael@0:     void          *priv;   /**< allocator private storage */
michael@0:   } vpx_codec_mmap_t; /**< alias for struct vpx_codec_mmap */
michael@0: 
michael@0: 
michael@0:   /*!\brief Iterate over the list of segments to allocate.
michael@0:    *
michael@0:    * Iterates over a list of the segments to allocate. The iterator storage
michael@0:    * should be initialized to NULL to start the iteration. Iteration is complete
michael@0:    * when this function returns VPX_CODEC_LIST_END. The amount of memory needed to
michael@0:    * allocate is dependent upon the size of the encoded stream. In cases where the
michael@0:    * stream is not available at allocation time, a fixed size must be requested.
michael@0:    * The codec will not be able to operate on streams larger than the size used at
michael@0:    * allocation time.
michael@0:    *
michael@0:    * \param[in]      ctx     Pointer to this instance's context.
michael@0:    * \param[out]     mmap    Pointer to the memory map entry to populate.
michael@0:    * \param[in,out]  iter    Iterator storage, initialized to NULL
michael@0:    *
michael@0:    * \retval #VPX_CODEC_OK
michael@0:    *     The memory map entry was populated.
michael@0:    * \retval #VPX_CODEC_ERROR
michael@0:    *     Codec does not support XMA mode.
michael@0:    * \retval #VPX_CODEC_MEM_ERROR
michael@0:    *     Unable to determine segment size from stream info.
michael@0:    */
michael@0:   vpx_codec_err_t vpx_codec_get_mem_map(vpx_codec_ctx_t                *ctx,
michael@0:                                         vpx_codec_mmap_t               *mmap,
michael@0:                                         vpx_codec_iter_t               *iter);
michael@0: 
michael@0: 
michael@0:   /*!\brief Identify allocated segments to codec instance
michael@0:    *
michael@0:    * Stores a list of allocated segments in the codec. Segments \ref MUST be
michael@0:    * passed in the order they are read from vpx_codec_get_mem_map(), but may be
michael@0:    * passed in groups of any size. Segments \ref MUST be set only once. The
michael@0:    * allocation function \ref MUST ensure that the vpx_codec_mmap_t::base member
michael@0:    * is non-NULL. If the segment requires cleanup handling (e.g., calling free()
michael@0:    * or close()) then the vpx_codec_mmap_t::dtor member \ref MUST be populated.
michael@0:    *
michael@0:    * \param[in]      ctx     Pointer to this instance's context.
michael@0:    * \param[in]      mmaps   Pointer to the first memory map entry in the list.
michael@0:    * \param[in]      num_maps  Number of entries being set at this time
michael@0:    *
michael@0:    * \retval #VPX_CODEC_OK
michael@0:    *     The segment was stored in the codec context.
michael@0:    * \retval #VPX_CODEC_INCAPABLE
michael@0:    *     Codec does not support XMA mode.
michael@0:    * \retval #VPX_CODEC_MEM_ERROR
michael@0:    *     Segment base address was not set, or segment was already stored.
michael@0: 
michael@0:    */
michael@0:   vpx_codec_err_t  vpx_codec_set_mem_map(vpx_codec_ctx_t   *ctx,
michael@0:                                          vpx_codec_mmap_t  *mmaps,
michael@0:                                          unsigned int       num_maps);
michael@0: 
michael@0:   /*!@} - end defgroup cap_xma*/
michael@0:   /*!@} - end defgroup codec*/
michael@0: #ifdef __cplusplus
michael@0: }
michael@0: #endif
michael@0: #endif
michael@0: