media/libvpx/vpx/vpx_codec.h

changeset 0
6474c204b198
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/media/libvpx/vpx/vpx_codec.h	Wed Dec 31 06:09:35 2014 +0100
     1.3 @@ -0,0 +1,558 @@
     1.4 +/*
     1.5 + *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
     1.6 + *
     1.7 + *  Use of this source code is governed by a BSD-style license
     1.8 + *  that can be found in the LICENSE file in the root of the source
     1.9 + *  tree. An additional intellectual property rights grant can be found
    1.10 + *  in the file PATENTS.  All contributing project authors may
    1.11 + *  be found in the AUTHORS file in the root of the source tree.
    1.12 + */
    1.13 +
    1.14 +
    1.15 +/*!\defgroup codec Common Algorithm Interface
    1.16 + * This abstraction allows applications to easily support multiple video
    1.17 + * formats with minimal code duplication. This section describes the interface
    1.18 + * common to all codecs (both encoders and decoders).
    1.19 + * @{
    1.20 + */
    1.21 +
    1.22 +/*!\file
    1.23 + * \brief Describes the codec algorithm interface to applications.
    1.24 + *
    1.25 + * This file describes the interface between an application and a
    1.26 + * video codec algorithm.
    1.27 + *
    1.28 + * An application instantiates a specific codec instance by using
    1.29 + * vpx_codec_init() and a pointer to the algorithm's interface structure:
    1.30 + *     <pre>
    1.31 + *     my_app.c:
    1.32 + *       extern vpx_codec_iface_t my_codec;
    1.33 + *       {
    1.34 + *           vpx_codec_ctx_t algo;
    1.35 + *           res = vpx_codec_init(&algo, &my_codec);
    1.36 + *       }
    1.37 + *     </pre>
    1.38 + *
    1.39 + * Once initialized, the instance is manged using other functions from
    1.40 + * the vpx_codec_* family.
    1.41 + */
    1.42 +#ifndef VPX_CODEC_H
    1.43 +#define VPX_CODEC_H
    1.44 +
    1.45 +#ifdef __cplusplus
    1.46 +extern "C" {
    1.47 +#endif
    1.48 +
    1.49 +#include "vpx_integer.h"
    1.50 +#include "vpx_image.h"
    1.51 +
    1.52 +  /*!\brief Decorator indicating a function is deprecated */
    1.53 +#ifndef DEPRECATED
    1.54 +#if defined(__GNUC__) && __GNUC__
    1.55 +#define DEPRECATED          __attribute__ ((deprecated))
    1.56 +#elif defined(_MSC_VER)
    1.57 +#define DEPRECATED
    1.58 +#else
    1.59 +#define DEPRECATED
    1.60 +#endif
    1.61 +#endif  /* DEPRECATED */
    1.62 +
    1.63 +#ifndef DECLSPEC_DEPRECATED
    1.64 +#if defined(__GNUC__) && __GNUC__
    1.65 +#define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
    1.66 +#elif defined(_MSC_VER)
    1.67 +#define DECLSPEC_DEPRECATED __declspec(deprecated) /**< \copydoc #DEPRECATED */
    1.68 +#else
    1.69 +#define DECLSPEC_DEPRECATED /**< \copydoc #DEPRECATED */
    1.70 +#endif
    1.71 +#endif  /* DECLSPEC_DEPRECATED */
    1.72 +
    1.73 +  /*!\brief Decorator indicating a function is potentially unused */
    1.74 +#ifdef UNUSED
    1.75 +#elif __GNUC__
    1.76 +#define UNUSED __attribute__ ((unused))
    1.77 +#else
    1.78 +#define UNUSED
    1.79 +#endif
    1.80 +
    1.81 +  /*!\brief Current ABI version number
    1.82 +   *
    1.83 +   * \internal
    1.84 +   * If this file is altered in any way that changes the ABI, this value
    1.85 +   * must be bumped.  Examples include, but are not limited to, changing
    1.86 +   * types, removing or reassigning enums, adding/removing/rearranging
    1.87 +   * fields to structures
    1.88 +   */
    1.89 +#define VPX_CODEC_ABI_VERSION (2 + VPX_IMAGE_ABI_VERSION) /**<\hideinitializer*/
    1.90 +
    1.91 +  /*!\brief Algorithm return codes */
    1.92 +  typedef enum {
    1.93 +    /*!\brief Operation completed without error */
    1.94 +    VPX_CODEC_OK,
    1.95 +
    1.96 +    /*!\brief Unspecified error */
    1.97 +    VPX_CODEC_ERROR,
    1.98 +
    1.99 +    /*!\brief Memory operation failed */
   1.100 +    VPX_CODEC_MEM_ERROR,
   1.101 +
   1.102 +    /*!\brief ABI version mismatch */
   1.103 +    VPX_CODEC_ABI_MISMATCH,
   1.104 +
   1.105 +    /*!\brief Algorithm does not have required capability */
   1.106 +    VPX_CODEC_INCAPABLE,
   1.107 +
   1.108 +    /*!\brief The given bitstream is not supported.
   1.109 +     *
   1.110 +     * The bitstream was unable to be parsed at the highest level. The decoder
   1.111 +     * is unable to proceed. This error \ref SHOULD be treated as fatal to the
   1.112 +     * stream. */
   1.113 +    VPX_CODEC_UNSUP_BITSTREAM,
   1.114 +
   1.115 +    /*!\brief Encoded bitstream uses an unsupported feature
   1.116 +     *
   1.117 +     * The decoder does not implement a feature required by the encoder. This
   1.118 +     * return code should only be used for features that prevent future
   1.119 +     * pictures from being properly decoded. This error \ref MAY be treated as
   1.120 +     * fatal to the stream or \ref MAY be treated as fatal to the current GOP.
   1.121 +     */
   1.122 +    VPX_CODEC_UNSUP_FEATURE,
   1.123 +
   1.124 +    /*!\brief The coded data for this stream is corrupt or incomplete
   1.125 +     *
   1.126 +     * There was a problem decoding the current frame.  This return code
   1.127 +     * should only be used for failures that prevent future pictures from
   1.128 +     * being properly decoded. This error \ref MAY be treated as fatal to the
   1.129 +     * stream or \ref MAY be treated as fatal to the current GOP. If decoding
   1.130 +     * is continued for the current GOP, artifacts may be present.
   1.131 +     */
   1.132 +    VPX_CODEC_CORRUPT_FRAME,
   1.133 +
   1.134 +    /*!\brief An application-supplied parameter is not valid.
   1.135 +     *
   1.136 +     */
   1.137 +    VPX_CODEC_INVALID_PARAM,
   1.138 +
   1.139 +    /*!\brief An iterator reached the end of list.
   1.140 +     *
   1.141 +     */
   1.142 +    VPX_CODEC_LIST_END
   1.143 +
   1.144 +  }
   1.145 +  vpx_codec_err_t;
   1.146 +
   1.147 +
   1.148 +  /*! \brief Codec capabilities bitfield
   1.149 +   *
   1.150 +   *  Each codec advertises the capabilities it supports as part of its
   1.151 +   *  ::vpx_codec_iface_t interface structure. Capabilities are extra interfaces
   1.152 +   *  or functionality, and are not required to be supported.
   1.153 +   *
   1.154 +   *  The available flags are specified by VPX_CODEC_CAP_* defines.
   1.155 +   */
   1.156 +  typedef long vpx_codec_caps_t;
   1.157 +#define VPX_CODEC_CAP_DECODER 0x1 /**< Is a decoder */
   1.158 +#define VPX_CODEC_CAP_ENCODER 0x2 /**< Is an encoder */
   1.159 +#define VPX_CODEC_CAP_XMA     0x4 /**< Supports eXternal Memory Allocation */
   1.160 +
   1.161 +
   1.162 +  /*! \brief Initialization-time Feature Enabling
   1.163 +   *
   1.164 +   *  Certain codec features must be known at initialization time, to allow for
   1.165 +   *  proper memory allocation.
   1.166 +   *
   1.167 +   *  The available flags are specified by VPX_CODEC_USE_* defines.
   1.168 +   */
   1.169 +  typedef long vpx_codec_flags_t;
   1.170 +#define VPX_CODEC_USE_XMA 0x00000001    /**< Use eXternal Memory Allocation mode */
   1.171 +
   1.172 +
   1.173 +  /*!\brief Codec interface structure.
   1.174 +   *
   1.175 +   * Contains function pointers and other data private to the codec
   1.176 +   * implementation. This structure is opaque to the application.
   1.177 +   */
   1.178 +  typedef const struct vpx_codec_iface vpx_codec_iface_t;
   1.179 +
   1.180 +
   1.181 +  /*!\brief Codec private data structure.
   1.182 +   *
   1.183 +   * Contains data private to the codec implementation. This structure is opaque
   1.184 +   * to the application.
   1.185 +   */
   1.186 +  typedef       struct vpx_codec_priv  vpx_codec_priv_t;
   1.187 +
   1.188 +
   1.189 +  /*!\brief Iterator
   1.190 +   *
   1.191 +   * Opaque storage used for iterating over lists.
   1.192 +   */
   1.193 +  typedef const void *vpx_codec_iter_t;
   1.194 +
   1.195 +
   1.196 +  /*!\brief Codec context structure
   1.197 +   *
   1.198 +   * All codecs \ref MUST support this context structure fully. In general,
   1.199 +   * this data should be considered private to the codec algorithm, and
   1.200 +   * not be manipulated or examined by the calling application. Applications
   1.201 +   * may reference the 'name' member to get a printable description of the
   1.202 +   * algorithm.
   1.203 +   */
   1.204 +  typedef struct vpx_codec_ctx {
   1.205 +    const char              *name;        /**< Printable interface name */
   1.206 +    vpx_codec_iface_t       *iface;       /**< Interface pointers */
   1.207 +    vpx_codec_err_t          err;         /**< Last returned error */
   1.208 +    const char              *err_detail;  /**< Detailed info, if available */
   1.209 +    vpx_codec_flags_t        init_flags;  /**< Flags passed at init time */
   1.210 +    union {
   1.211 +      struct vpx_codec_dec_cfg  *dec;   /**< Decoder Configuration Pointer */
   1.212 +      struct vpx_codec_enc_cfg  *enc;   /**< Encoder Configuration Pointer */
   1.213 +      void                      *raw;
   1.214 +    }                        config;      /**< Configuration pointer aliasing union */
   1.215 +    vpx_codec_priv_t        *priv;        /**< Algorithm private storage */
   1.216 +  } vpx_codec_ctx_t;
   1.217 +
   1.218 +
   1.219 +  /*
   1.220 +   * Library Version Number Interface
   1.221 +   *
   1.222 +   * For example, see the following sample return values:
   1.223 +   *     vpx_codec_version()           (1<<16 | 2<<8 | 3)
   1.224 +   *     vpx_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
   1.225 +   *     vpx_codec_version_extra_str() "rc1-16-gec6a1ba"
   1.226 +   */
   1.227 +
   1.228 +  /*!\brief Return the version information (as an integer)
   1.229 +   *
   1.230 +   * Returns a packed encoding of the library version number. This will only include
   1.231 +   * the major.minor.patch component of the version number. Note that this encoded
   1.232 +   * value should be accessed through the macros provided, as the encoding may change
   1.233 +   * in the future.
   1.234 +   *
   1.235 +   */
   1.236 +  int vpx_codec_version(void);
   1.237 +#define VPX_VERSION_MAJOR(v) ((v>>16)&0xff) /**< extract major from packed version */
   1.238 +#define VPX_VERSION_MINOR(v) ((v>>8)&0xff)  /**< extract minor from packed version */
   1.239 +#define VPX_VERSION_PATCH(v) ((v>>0)&0xff)  /**< extract patch from packed version */
   1.240 +
   1.241 +  /*!\brief Return the version major number */
   1.242 +#define vpx_codec_version_major() ((vpx_codec_version()>>16)&0xff)
   1.243 +
   1.244 +  /*!\brief Return the version minor number */
   1.245 +#define vpx_codec_version_minor() ((vpx_codec_version()>>8)&0xff)
   1.246 +
   1.247 +  /*!\brief Return the version patch number */
   1.248 +#define vpx_codec_version_patch() ((vpx_codec_version()>>0)&0xff)
   1.249 +
   1.250 +
   1.251 +  /*!\brief Return the version information (as a string)
   1.252 +   *
   1.253 +   * Returns a printable string containing the full library version number. This may
   1.254 +   * contain additional text following the three digit version number, as to indicate
   1.255 +   * release candidates, prerelease versions, etc.
   1.256 +   *
   1.257 +   */
   1.258 +  const char *vpx_codec_version_str(void);
   1.259 +
   1.260 +
   1.261 +  /*!\brief Return the version information (as a string)
   1.262 +   *
   1.263 +   * Returns a printable "extra string". This is the component of the string returned
   1.264 +   * by vpx_codec_version_str() following the three digit version number.
   1.265 +   *
   1.266 +   */
   1.267 +  const char *vpx_codec_version_extra_str(void);
   1.268 +
   1.269 +
   1.270 +  /*!\brief Return the build configuration
   1.271 +   *
   1.272 +   * Returns a printable string containing an encoded version of the build
   1.273 +   * configuration. This may be useful to vpx support.
   1.274 +   *
   1.275 +   */
   1.276 +  const char *vpx_codec_build_config(void);
   1.277 +
   1.278 +
   1.279 +  /*!\brief Return the name for a given interface
   1.280 +   *
   1.281 +   * Returns a human readable string for name of the given codec interface.
   1.282 +   *
   1.283 +   * \param[in]    iface     Interface pointer
   1.284 +   *
   1.285 +   */
   1.286 +  const char *vpx_codec_iface_name(vpx_codec_iface_t *iface);
   1.287 +
   1.288 +
   1.289 +  /*!\brief Convert error number to printable string
   1.290 +   *
   1.291 +   * Returns a human readable string for the last error returned by the
   1.292 +   * algorithm. The returned error will be one line and will not contain
   1.293 +   * any newline characters.
   1.294 +   *
   1.295 +   *
   1.296 +   * \param[in]    err     Error number.
   1.297 +   *
   1.298 +   */
   1.299 +  const char *vpx_codec_err_to_string(vpx_codec_err_t  err);
   1.300 +
   1.301 +
   1.302 +  /*!\brief Retrieve error synopsis for codec context
   1.303 +   *
   1.304 +   * Returns a human readable string for the last error returned by the
   1.305 +   * algorithm. The returned error will be one line and will not contain
   1.306 +   * any newline characters.
   1.307 +   *
   1.308 +   *
   1.309 +   * \param[in]    ctx     Pointer to this instance's context.
   1.310 +   *
   1.311 +   */
   1.312 +  const char *vpx_codec_error(vpx_codec_ctx_t  *ctx);
   1.313 +
   1.314 +
   1.315 +  /*!\brief Retrieve detailed error information for codec context
   1.316 +   *
   1.317 +   * Returns a human readable string providing detailed information about
   1.318 +   * the last error.
   1.319 +   *
   1.320 +   * \param[in]    ctx     Pointer to this instance's context.
   1.321 +   *
   1.322 +   * \retval NULL
   1.323 +   *     No detailed information is available.
   1.324 +   */
   1.325 +  const char *vpx_codec_error_detail(vpx_codec_ctx_t  *ctx);
   1.326 +
   1.327 +
   1.328 +  /* REQUIRED FUNCTIONS
   1.329 +   *
   1.330 +   * The following functions are required to be implemented for all codecs.
   1.331 +   * They represent the base case functionality expected of all codecs.
   1.332 +   */
   1.333 +
   1.334 +  /*!\brief Destroy a codec instance
   1.335 +   *
   1.336 +   * Destroys a codec context, freeing any associated memory buffers.
   1.337 +   *
   1.338 +   * \param[in] ctx   Pointer to this instance's context
   1.339 +   *
   1.340 +   * \retval #VPX_CODEC_OK
   1.341 +   *     The codec algorithm initialized.
   1.342 +   * \retval #VPX_CODEC_MEM_ERROR
   1.343 +   *     Memory allocation failed.
   1.344 +   */
   1.345 +  vpx_codec_err_t vpx_codec_destroy(vpx_codec_ctx_t *ctx);
   1.346 +
   1.347 +
   1.348 +  /*!\brief Get the capabilities of an algorithm.
   1.349 +   *
   1.350 +   * Retrieves the capabilities bitfield from the algorithm's interface.
   1.351 +   *
   1.352 +   * \param[in] iface   Pointer to the algorithm interface
   1.353 +   *
   1.354 +   */
   1.355 +  vpx_codec_caps_t vpx_codec_get_caps(vpx_codec_iface_t *iface);
   1.356 +
   1.357 +
   1.358 +  /*!\brief Control algorithm
   1.359 +   *
   1.360 +   * This function is used to exchange algorithm specific data with the codec
   1.361 +   * instance. This can be used to implement features specific to a particular
   1.362 +   * algorithm.
   1.363 +   *
   1.364 +   * This wrapper function dispatches the request to the helper function
   1.365 +   * associated with the given ctrl_id. It tries to call this function
   1.366 +   * transparently, but will return #VPX_CODEC_ERROR if the request could not
   1.367 +   * be dispatched.
   1.368 +   *
   1.369 +   * Note that this function should not be used directly. Call the
   1.370 +   * #vpx_codec_control wrapper macro instead.
   1.371 +   *
   1.372 +   * \param[in]     ctx              Pointer to this instance's context
   1.373 +   * \param[in]     ctrl_id          Algorithm specific control identifier
   1.374 +   *
   1.375 +   * \retval #VPX_CODEC_OK
   1.376 +   *     The control request was processed.
   1.377 +   * \retval #VPX_CODEC_ERROR
   1.378 +   *     The control request was not processed.
   1.379 +   * \retval #VPX_CODEC_INVALID_PARAM
   1.380 +   *     The data was not valid.
   1.381 +   */
   1.382 +  vpx_codec_err_t vpx_codec_control_(vpx_codec_ctx_t  *ctx,
   1.383 +                                     int               ctrl_id,
   1.384 +                                     ...);
   1.385 +#if defined(VPX_DISABLE_CTRL_TYPECHECKS) && VPX_DISABLE_CTRL_TYPECHECKS
   1.386 +#    define vpx_codec_control(ctx,id,data) vpx_codec_control_(ctx,id,data)
   1.387 +#    define VPX_CTRL_USE_TYPE(id, typ)
   1.388 +#    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ)
   1.389 +#    define VPX_CTRL_VOID(id, typ)
   1.390 +
   1.391 +#else
   1.392 +  /*!\brief vpx_codec_control wrapper macro
   1.393 +   *
   1.394 +   * This macro allows for type safe conversions across the variadic parameter
   1.395 +   * to vpx_codec_control_().
   1.396 +   *
   1.397 +   * \internal
   1.398 +   * It works by dispatching the call to the control function through a wrapper
   1.399 +   * function named with the id parameter.
   1.400 +   */
   1.401 +#    define vpx_codec_control(ctx,id,data) vpx_codec_control_##id(ctx,id,data)\
   1.402 +  /**<\hideinitializer*/
   1.403 +
   1.404 +
   1.405 +  /*!\brief vpx_codec_control type definition macro
   1.406 +   *
   1.407 +   * This macro allows for type safe conversions across the variadic parameter
   1.408 +   * to vpx_codec_control_(). It defines the type of the argument for a given
   1.409 +   * control identifier.
   1.410 +   *
   1.411 +   * \internal
   1.412 +   * It defines a static function with
   1.413 +   * the correctly typed arguments as a wrapper to the type-unsafe internal
   1.414 +   * function.
   1.415 +   */
   1.416 +#    define VPX_CTRL_USE_TYPE(id, typ) \
   1.417 +  static vpx_codec_err_t \
   1.418 +  vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) UNUSED;\
   1.419 +  \
   1.420 +  static vpx_codec_err_t \
   1.421 +  vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
   1.422 +    return vpx_codec_control_(ctx, ctrl_id, data);\
   1.423 +  } /**<\hideinitializer*/
   1.424 +
   1.425 +
   1.426 +  /*!\brief vpx_codec_control deprecated type definition macro
   1.427 +   *
   1.428 +   * Like #VPX_CTRL_USE_TYPE, but indicates that the specified control is
   1.429 +   * deprecated and should not be used. Consult the documentation for your
   1.430 +   * codec for more information.
   1.431 +   *
   1.432 +   * \internal
   1.433 +   * It defines a static function with the correctly typed arguments as a
   1.434 +   * wrapper to the type-unsafe internal function.
   1.435 +   */
   1.436 +#    define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \
   1.437 +  DECLSPEC_DEPRECATED static vpx_codec_err_t \
   1.438 +  vpx_codec_control_##id(vpx_codec_ctx_t*, int, typ) DEPRECATED UNUSED;\
   1.439 +  \
   1.440 +  DECLSPEC_DEPRECATED static vpx_codec_err_t \
   1.441 +  vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id, typ data) {\
   1.442 +    return vpx_codec_control_(ctx, ctrl_id, data);\
   1.443 +  } /**<\hideinitializer*/
   1.444 +
   1.445 +
   1.446 +  /*!\brief vpx_codec_control void type definition macro
   1.447 +   *
   1.448 +   * This macro allows for type safe conversions across the variadic parameter
   1.449 +   * to vpx_codec_control_(). It indicates that a given control identifier takes
   1.450 +   * no argument.
   1.451 +   *
   1.452 +   * \internal
   1.453 +   * It defines a static function without a data argument as a wrapper to the
   1.454 +   * type-unsafe internal function.
   1.455 +   */
   1.456 +#    define VPX_CTRL_VOID(id) \
   1.457 +  static vpx_codec_err_t \
   1.458 +  vpx_codec_control_##id(vpx_codec_ctx_t*, int) UNUSED;\
   1.459 +  \
   1.460 +  static vpx_codec_err_t \
   1.461 +  vpx_codec_control_##id(vpx_codec_ctx_t  *ctx, int ctrl_id) {\
   1.462 +    return vpx_codec_control_(ctx, ctrl_id);\
   1.463 +  } /**<\hideinitializer*/
   1.464 +
   1.465 +
   1.466 +#endif
   1.467 +
   1.468 +
   1.469 +  /*!\defgroup cap_xma External Memory Allocation Functions
   1.470 +   *
   1.471 +   * The following functions are required to be implemented for all codecs
   1.472 +   * that advertise the VPX_CODEC_CAP_XMA capability. Calling these functions
   1.473 +   * for codecs that don't advertise this capability will result in an error
   1.474 +   * code being returned, usually VPX_CODEC_INCAPABLE
   1.475 +   * @{
   1.476 +   */
   1.477 +
   1.478 +
   1.479 +  /*!\brief Memory Map Entry
   1.480 +   *
   1.481 +   * This structure is used to contain the properties of a memory segment. It
   1.482 +   * is populated by the codec in the request phase, and by the calling
   1.483 +   * application once the requested allocation has been performed.
   1.484 +   */
   1.485 +  typedef struct vpx_codec_mmap {
   1.486 +    /*
   1.487 +     * The following members are set by the codec when requesting a segment
   1.488 +     */
   1.489 +    unsigned int   id;     /**< identifier for the segment's contents */
   1.490 +    unsigned long  sz;     /**< size of the segment, in bytes */
   1.491 +    unsigned int   align;  /**< required alignment of the segment, in bytes */
   1.492 +    unsigned int   flags;  /**< bitfield containing segment properties */
   1.493 +#define VPX_CODEC_MEM_ZERO     0x1  /**< Segment must be zeroed by allocation */
   1.494 +#define VPX_CODEC_MEM_WRONLY   0x2  /**< Segment need not be readable */
   1.495 +#define VPX_CODEC_MEM_FAST     0x4  /**< Place in fast memory, if available */
   1.496 +
   1.497 +    /* The following members are to be filled in by the allocation function */
   1.498 +    void          *base;   /**< pointer to the allocated segment */
   1.499 +    void (*dtor)(struct vpx_codec_mmap *map);         /**< destructor to call */
   1.500 +    void          *priv;   /**< allocator private storage */
   1.501 +  } vpx_codec_mmap_t; /**< alias for struct vpx_codec_mmap */
   1.502 +
   1.503 +
   1.504 +  /*!\brief Iterate over the list of segments to allocate.
   1.505 +   *
   1.506 +   * Iterates over a list of the segments to allocate. The iterator storage
   1.507 +   * should be initialized to NULL to start the iteration. Iteration is complete
   1.508 +   * when this function returns VPX_CODEC_LIST_END. The amount of memory needed to
   1.509 +   * allocate is dependent upon the size of the encoded stream. In cases where the
   1.510 +   * stream is not available at allocation time, a fixed size must be requested.
   1.511 +   * The codec will not be able to operate on streams larger than the size used at
   1.512 +   * allocation time.
   1.513 +   *
   1.514 +   * \param[in]      ctx     Pointer to this instance's context.
   1.515 +   * \param[out]     mmap    Pointer to the memory map entry to populate.
   1.516 +   * \param[in,out]  iter    Iterator storage, initialized to NULL
   1.517 +   *
   1.518 +   * \retval #VPX_CODEC_OK
   1.519 +   *     The memory map entry was populated.
   1.520 +   * \retval #VPX_CODEC_ERROR
   1.521 +   *     Codec does not support XMA mode.
   1.522 +   * \retval #VPX_CODEC_MEM_ERROR
   1.523 +   *     Unable to determine segment size from stream info.
   1.524 +   */
   1.525 +  vpx_codec_err_t vpx_codec_get_mem_map(vpx_codec_ctx_t                *ctx,
   1.526 +                                        vpx_codec_mmap_t               *mmap,
   1.527 +                                        vpx_codec_iter_t               *iter);
   1.528 +
   1.529 +
   1.530 +  /*!\brief Identify allocated segments to codec instance
   1.531 +   *
   1.532 +   * Stores a list of allocated segments in the codec. Segments \ref MUST be
   1.533 +   * passed in the order they are read from vpx_codec_get_mem_map(), but may be
   1.534 +   * passed in groups of any size. Segments \ref MUST be set only once. The
   1.535 +   * allocation function \ref MUST ensure that the vpx_codec_mmap_t::base member
   1.536 +   * is non-NULL. If the segment requires cleanup handling (e.g., calling free()
   1.537 +   * or close()) then the vpx_codec_mmap_t::dtor member \ref MUST be populated.
   1.538 +   *
   1.539 +   * \param[in]      ctx     Pointer to this instance's context.
   1.540 +   * \param[in]      mmaps   Pointer to the first memory map entry in the list.
   1.541 +   * \param[in]      num_maps  Number of entries being set at this time
   1.542 +   *
   1.543 +   * \retval #VPX_CODEC_OK
   1.544 +   *     The segment was stored in the codec context.
   1.545 +   * \retval #VPX_CODEC_INCAPABLE
   1.546 +   *     Codec does not support XMA mode.
   1.547 +   * \retval #VPX_CODEC_MEM_ERROR
   1.548 +   *     Segment base address was not set, or segment was already stored.
   1.549 +
   1.550 +   */
   1.551 +  vpx_codec_err_t  vpx_codec_set_mem_map(vpx_codec_ctx_t   *ctx,
   1.552 +                                         vpx_codec_mmap_t  *mmaps,
   1.553 +                                         unsigned int       num_maps);
   1.554 +
   1.555 +  /*!@} - end defgroup cap_xma*/
   1.556 +  /*!@} - end defgroup codec*/
   1.557 +#ifdef __cplusplus
   1.558 +}
   1.559 +#endif
   1.560 +#endif
   1.561 +

mercurial