tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 6386

 
 
 

VP8 Data Format and Decoding Guide

Part 11 of 11, p. 291 to 304
Prev RFC Part

 


prevText      Top      Up      ToC       Page 291 
20.23.  vpx_image.h

   ---- Begin code block --------------------------------------

   /*
    * Copyright (c) 2010, 2011, Google Inc.  All rights reserved.
    *
    * Use of this source code is governed by a BSD-style license
    * that can be found in the LICENSE file in the root of the source
    * tree.  An additional intellectual property rights grant can be
    * found in the file PATENTS.  All contributing project authors may
    * be found in the AUTHORS file in the root of the source tree.
    */

   /*!\file
    * \brief Describes the vpx image descriptor and associated
    * operations
    *
    */

Top      Up      ToC       Page 292 
   #ifdef __cplusplus
   extern "C" {
   #endif

   #ifndef VPX_IMAGE_H
   #define VPX_IMAGE_H

       /*!\brief Current ABI version number
        *
        * \internal
        * If this file is altered in any way that changes the ABI, this
        * value must be bumped.  Examples include, but are not limited
        * to, changing types, removing or reassigning enums,
        * adding/removing/rearranging fields to structures
        */
   #define VPX_IMAGE_ABI_VERSION (1) /**<\hideinitializer*/


   #define VPX_IMG_FMT_PLANAR     0x100  /**< Image is a planar
                                              format */
   #define VPX_IMG_FMT_UV_FLIP    0x200  /**< V plane precedes U plane
                                              in memory */
   #define VPX_IMG_FMT_HAS_ALPHA  0x400  /**< Image has an alpha channel
                                              component */


       /*!\brief List of supported image formats */
       typedef enum vpx_img_fmt {
           VPX_IMG_FMT_NONE,
           VPX_IMG_FMT_RGB24,      /**< 24 bit per pixel packed RGB */
           VPX_IMG_FMT_RGB32,      /**< 32 bit per pixel packed 0RGB */
           VPX_IMG_FMT_RGB565,     /**< 16 bit per pixel, 565 */
           VPX_IMGFMT_RGB555,      /**< 16 bit per pixel, 555 */
           VPX_IMG_FMT_UYVY,       /**< UYVY packed YUV */
           VPX_IMG_FMT_YUY2,       /**< YUYV packed YUV */
           VPX_IMG_FMT_YVYU,       /**< YVYU packed YUV */
           VPX_IMG_FMT_BGR24,      /**< 24 bit per pixel packed BGR */
           VPX_IMG_FMT_RGB32_LE,   /**< 32 bit packed BGR0 */
           VPX_IMG_FMT_ARGB,       /**< 32 bit packed ARGB, alpha=255 */
           VPX_IMG_FMT_ARGB_LE,    /**< 32 bit packed BGRA, alpha=255 */
           VPX_IMG_FMT_RGB565_LE,  /**< 16 bit per pixel,
                                        gggbbbbb rrrrrggg */
           VPX_IMG_FMT_RGB555_LE,  /**< 16 bit per pixel,
                                        gggbbbbb 0rrrrrgg */
           VPX_IMG_FMT_YV12    = VPX_IMG_FMT_PLANAR |
             VPX_IMG_FMT_UV_FLIP | 1, /**< planar YVU */
           VPX_IMG_FMT_I420    = VPX_IMG_FMT_PLANAR | 2,

Top      Up      ToC       Page 293 
           VPX_IMG_FMT_VPXYV12 = VPX_IMG_FMT_PLANAR |
             VPX_IMG_FMT_UV_FLIP | 3, /** < planar 4:2:0 format with
                                            vpx color space */
           VPX_IMG_FMT_VPXI420 = VPX_IMG_FMT_PLANAR | 4   /** < planar
             4:2:0 format with vpx color space */
       }
       vpx_img_fmt_t; /**< alias for enum vpx_img_fmt */

   #if !defined(VPX_CODEC_DISABLE_COMPAT) || !VPX_CODEC_DISABLE_COMPAT
   /** \deprecated Use #VPX_IMG_FMT_PLANAR */
   #define IMG_FMT_PLANAR         VPX_IMG_FMT_PLANAR
   /** \deprecated Use #VPX_IMG_FMT_UV_FLIP */
   #define IMG_FMT_UV_FLIP        VPX_IMG_FMT_UV_FLIP
   /** \deprecated Use #VPX_IMG_FMT_HAS_ALPHA */
   #define IMG_FMT_HAS_ALPHA      VPX_IMG_FMT_HAS_ALPHA

       /*!\brief Deprecated list of supported image formats
        * \deprecated New code should use #vpx_img_fmt
        */
   #define img_fmt   vpx_img_fmt
       /*!\brief alias for enum img_fmt.
        * \deprecated New code should use #vpx_img_fmt_t
        */
   #define img_fmt_t vpx_img_fmt_t

   /** \deprecated Use #VPX_IMG_FMT_NONE */
   #define IMG_FMT_NONE       VPX_IMG_FMT_NONE
   /** \deprecated Use #VPX_IMG_FMT_RGB24 */
   #define IMG_FMT_RGB24      VPX_IMG_FMT_RGB24
   /** \deprecated Use #VPX_IMG_FMT_RGB32 */
   #define IMG_FMT_RGB32      VPX_IMG_FMT_RGB32
   /** \deprecated Use #VPX_IMG_FMT_RGB565 */
   #define IMG_FMT_RGB565     VPX_IMG_FMT_RGB565
   /** \deprecated Use #VPX_IMG_FMT_RGB555 */
   #define IMG_FMT_RGB555     VPX_IMG_FMT_RGB555
   /** \deprecated Use #VPX_IMG_FMT_UYVY */
   #define IMG_FMT_UYVY       VPX_IMG_FMT_UYVY
   /** \deprecated Use #VPX_IMG_FMT_YUY2 */
   #define IMG_FMT_YUY2       VPX_IMG_FMT_YUY2
   /** \deprecated Use #VPX_IMG_FMT_YVYU */
   #define IMG_FMT_YVYU       VPX_IMG_FMT_YVYU
   /** \deprecated Use #VPX_IMG_FMT_BGR24 */
   #define IMG_FMT_BGR24      VPX_IMG_FMT_BGR24
   /**< \deprecated Use #VPX_IMG_FMT_RGB32_LE */
   #define IMG_FMT_RGB32_LE   VPX_IMG_FMT_RGB32_LE
   /** \deprecated Use #VPX_IMG_FMT_ARGB */
   #define IMG_FMT_ARGB       VPX_IMG_FMT_ARGB

Top      Up      ToC       Page 294 
   /** \deprecated Use #VPX_IMG_FMT_ARGB_LE */
   #define IMG_FMT_ARGB_LE    VPX_IMG_FMT_ARGB_LE
   /** \deprecated Use #VPX_IMG_FMT_RGB565_LE */
   #define IMG_FMT_RGB565_LE  VPX_IMG_FMT_RGB565_LE
   /** \deprecated Use #VPX_IMG_FMT_RGB555_LE */
   #define IMG_FMT_RGB555_LE  VPX_IMG_FMT_RGB555_LE
   /** \deprecated Use #VPX_IMG_FMT_YV12 */
   #define IMG_FMT_YV12       VPX_IMG_FMT_YV12
   /** \deprecated Use #VPX_IMG_FMT_I420 */
   #define IMG_FMT_I420       VPX_IMG_FMT_I420
   /** \deprecated Use #VPX_IMG_FMT_VPXYV12 */
   #define IMG_FMT_VPXYV12    VPX_IMG_FMT_VPXYV12
   /** \deprecated Use #VPX_IMG_FMT_VPXI420 */
   #define IMG_FMT_VPXI420    VPX_IMG_FMT_VPXI420
   #endif /* VPX_CODEC_DISABLE_COMPAT */

       /**\brief Image Descriptor */
       typedef struct vpx_image
       {
           vpx_img_fmt_t fmt; /**< Image Format */

           /* Image storage dimensions */
           unsigned int  w;   /**< Stored image width */
           unsigned int  h;   /**< Stored image height */

           /* Image display dimensions */
           unsigned int  d_w;   /**< Displayed image width */
           unsigned int  d_h;   /**< Displayed image height */

           /* Chroma subsampling info */
           unsigned int  x_chroma_shift;   /**< subsampling order, X */
           unsigned int  y_chroma_shift;   /**< subsampling order, Y */

           /* Image data pointers. */
   #define VPX_PLANE_PACKED 0  /**< To be used for all packed formats */
   #define VPX_PLANE_Y      0  /**< Y (Luminance) plane */
   #define VPX_PLANE_U      1  /**< U (Chroma) plane */
   #define VPX_PLANE_V      2  /**< V (Chroma) plane */
   #define VPX_PLANE_ALPHA  3  /**< A (Transparency) plane */
   #if !defined(VPX_CODEC_DISABLE_COMPAT) || !VPX_CODEC_DISABLE_COMPAT
   #define PLANE_PACKED     VPX_PLANE_PACKED
   #define PLANE_Y          VPX_PLANE_Y
   #define PLANE_U          VPX_PLANE_U
   #define PLANE_V          VPX_PLANE_V
   #define PLANE_ALPHA      VPX_PLANE_ALPHA
   #endif

Top      Up      ToC       Page 295 
           unsigned char *planes[4];  /**< pointer to the top-left pixel
           q                               for each plane */
           int    stride[4];  /**< stride between rows for each plane */

           int    bps; /**< bits per sample (for packed formats) */

           /* The following member may be set by the application to
            * associate data with this image.
            */
           void   *user_priv; /**< may be set by the application to
                                    associate data with this image. */

           /* The following members should be treated as private. */
           unsigned char *img_data;       /**< private */
           int      img_data_owner; /**< private */
           int      self_allocd;    /**< private */
       } vpx_image_t; /**< alias for struct vpx_image */

       /**\brief Representation of a rectangle on a surface */
       typedef struct vpx_image_rect
       {
           unsigned int x; /**< leftmost column */
           unsigned int y; /**< topmost row */
           unsigned int w; /**< width */
           unsigned int h; /**< height */
       } vpx_image_rect_t; /**< alias for struct vpx_image_rect */

       /*!\brief Open a descriptor, allocating storage for the
        * underlying image
        *
        * Returns a descriptor for storing an image of the given format.
        * The storage for the descriptor is allocated on the heap.
        *
        * \param[in]    img       Pointer to storage for descriptor.
        *                         If this parameter is NULL, the storage
        *                         for the descriptor will be allocated
        *                         on the heap.
        * \param[in]    fmt       Format for the image
        * \param[in]    d_w       Width of the image
        * \param[in]    d_h       Height of the image
        * \param[in]    align     Alignment, in bytes, of each row in
        *                         the image.
        *
        * \return Returns a pointer to the initialized image descriptor.
        *         If the img parameter is non-null, the value of the img
        *         parameter will be returned.
        */

Top      Up      ToC       Page 296 
       vpx_image_t *vpx_img_alloc(vpx_image_t  *img,
                                  vpx_img_fmt_t fmt,
                                  unsigned int d_w,
                                  unsigned int d_h,
                                  unsigned int align);

       /*!\brief Open a descriptor, using existing storage for the
        * underlying image
        *
        * Returns a descriptor for storing an image of the given format.
        * The storage for descriptor has been allocated elsewhere, and a
        * descriptor is desired to "wrap" that storage.
        *
        * \param[in]    img       Pointer to storage for descriptor.
        *                         If this parameter is NULL, the storage
        *                         for the descriptor will be
        *                         allocated on the heap.
        * \param[in]    fmt       Format for the image
        * \param[in]    d_w       Width of the image
        * \param[in]    d_h       Height of the image
        * \param[in]    align     Alignment, in bytes, of each row in
        *                         the image.
        * \param[in]    img_data  Storage to use for the image
        *
        * \return Returns a pointer to the initialized image descriptor.
        *         If the img parameter is non-null, the value of the img
        *         parameter will be returned.
        */
       vpx_image_t *vpx_img_wrap(vpx_image_t  *img,
                                 vpx_img_fmt_t fmt,
                                 unsigned int d_w,
                                 unsigned int d_h,
                                 unsigned int align,
                                 unsigned char      *img_data);


       /*!\brief Set the rectangle identifying the displayed portion of
        * the image
        *
        * Updates the displayed rectangle (aka viewport) on the image
        * surface to match the specified coordinates and size.
        *
        * \param[in]    img       Image descriptor
        * \param[in]    x         leftmost column
        * \param[in]    y         topmost row
        * \param[in]    w         width
        * \param[in]    h         height
        *

Top      Up      ToC       Page 297 
        * \return 0 if the requested rectangle is valid, non-zero
        * otherwise.
        */
       int vpx_img_set_rect(vpx_image_t  *img,
                            unsigned int  x,
                            unsigned int  y,
                            unsigned int  w,
                            unsigned int  h);


       /*!\brief Flip the image vertically (top for bottom)
        *
        * Adjusts the image descriptor's pointers and strides to make
        * the image be referenced upside-down.
        *
        * \param[in]    img       Image descriptor
        */
       void vpx_img_flip(vpx_image_t *img);

       /*!\brief Close an image descriptor
        *
        * Frees all allocated storage associated with an image
        * descriptor.
        *
        * \param[in]    img       Image descriptor
        */
       void vpx_img_free(vpx_image_t *img);

   #endif
   #ifdef __cplusplus
   }
   #endif

   ---- End code block ----------------------------------------

Top      Up      ToC       Page 298 
20.24.  vpx_integer.h

   ---- Begin code block --------------------------------------

   /*
    *  Copyright (c) 2010, 2011, Google Inc.  All rights reserved.
    *
    *  Use of this source code is governed by a BSD-style license
    *  that can be found in the LICENSE file in the root of the source
    *  tree.  An additional intellectual property rights grant can be
    *  found in the file PATENTS.  All contributing project authors may
    *  be found in the AUTHORS file in the root of the source tree.
    */

   #ifndef VPX_INTEGER_H
   #define VPX_INTEGER_H

   /* get ptrdiff_t, size_t, wchar_t, NULL */
   #include <stddef.h>

   #if defined(_MSC_VER) || defined(VPX_EMULATE_INTTYPES)
   typedef signed char  int8_t;
   typedef signed short int16_t;
   typedef signed int   int32_t;
   typedef unsigned char  uint8_t;
   typedef unsigned short uint16_t;
   typedef unsigned int   uint32_t;

   #if defined(_MSC_VER)
   typedef signed __int64   int64_t;
   typedef unsigned __int64 uint64_t;
   #define PRId64 "I64d"
   #endif

   #ifdef HAVE_ARMV6
   typedef unsigned int int_fast16_t;
   #else
   typedef signed short int_fast16_t;
   #endif
   typedef signed char int_fast8_t;
   typedef unsigned char uint_fast8_t;

   #ifndef _UINTPTR_T_DEFINED
   typedef unsigned int   uintptr_t;
   #endif

Top      Up      ToC       Page 299 
   #else

   /* Most platforms have the C99 standard integer types. */

   #if defined(__cplusplus) && !defined(__STDC_FORMAT_MACROS)
   #define __STDC_FORMAT_MACROS
   #endif
   #include <stdint.h>
   #include <inttypes.h>

   #endif

   #endif

   ---- End code block ----------------------------------------

20.25.  AUTHORS File

   Aaron Watry <awatry@gmail.com>

   Adrian Grange <agrange@google.com>

   Alex Converse <alex.converse@gmail.com>

   Andoni Morales Alastruey <ylatuya@gmail.com>

   Andres Mejia <mcitadel@gmail.com>

   Attila Nagy <attilanagy@google.com>

   Fabio Pedretti <fabio.ped@libero.it>

   Frank Galligan <fgalligan@google.com>

   Fredrik Soederquist <fs@opera.com>

   Fritz Koenig <frkoenig@google.com>

   Gaute Strokkenes <gaute.strokkenes@broadcom.com>

   Giuseppe Scrivano <gscrivano@gnu.org>

   Guillermo Ballester Valor <gbvalor@gmail.com>

   Henrik Lundin <hlundin@google.com>

   James Berry <jamesberry@google.com>

Top      Up      ToC       Page 300 
   James Zern <jzern@google.com>

   Jan Kratochvil <jan.kratochvil@redhat.com>

   Jeff Muizelaar <jmuizelaar@mozilla.com>

   Jim Bankoski <jimbankoski@google.com>

   Johann Koenig <johannkoenig@google.com>

   John Koleszar <jkoleszar@google.com>

   Justin Clift <justin@salasaga.org>

   Justin Lebar <justin.lebar@gmail.com>

   Luca Barbato <lu_zero@gentoo.org>

   Makoto Kato <makoto.kt@gmail.com>

   Martin Ettl <ettl.martin78@googlemail.com>

   Michael Kohler <michaelkohler@live.com>

   Mikhal Shemer <mikhal@google.com>

   Pascal Massimino <pascal.massimino@gmail.com>

   Patrik Westin <patrik.westin@gmail.com>

   Paul Wilkins <paulwilkins@google.com>

   Pavol Rusnak <stick@gk2.sk>

   Philip Jaegenstedt <philipj@opera.com>

   Scott LaVarnway <slavarnway@google.com>

   Tero Rintaluoma <teror@google.com>

   Timothy B. Terriberry <tterribe@xiph.org>

   Tom Finegan <tomfinegan@google.com>

   Yaowu Xu <yaowu@google.com>

   Yunqing Wang <yunqingwang@google.com>

Top      Up      ToC       Page 301 
   Google Inc.

   The Mozilla Foundation

   The Xiph.Org Foundation

20.26.  LICENSE

   Copyright (c) 2010, 2011, Google Inc.  All rights reserved.

   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:

   o  Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.

   o  Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in
      the documentation and/or other materials provided with the
      distribution.

   o  Neither the name of Google nor the names of its contributors may
      be used to endorse or promote products derived from this software
      without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
   HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
   OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
   AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
   WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   POSSIBILITY OF SUCH DAMAGE.

Top      Up      ToC       Page 302 
20.27.  PATENTS

   Additional IP Rights Grant (Patents)

   "This implementation" means the copyrightable works distributed by
   Google as part of the WebM Project.

   Google hereby grants to you a perpetual, worldwide, non-exclusive,
   no-charge, royalty-free, irrevocable (except as stated in this
   section) patent license to make, have made, use, offer to sell, sell,
   import, transfer, and otherwise run, modify and propagate the
   contents of this implementation of VP8, where such license applies
   only to those patent claims, both currently owned by Google and
   acquired in the future, licensable by Google that are necessarily
   infringed by this implementation of VP8.  This grant does not include
   claims that would be infringed only as a consequence of further
   modification of this implementation.  If you or your agent or
   exclusive licensee institute or order or agree to the institution of
   patent litigation against any entity (including a cross-claim or
   counterclaim in a lawsuit) alleging that this implementation of VP8
   or any code incorporated within this implementation of VP8
   constitutes direct or contributory patent infringement, or inducement
   of patent infringement, then any patent rights granted to you under
   this License for this implementation of VP8 shall terminate as of the
   date such litigation is filed.

21.  Security Considerations

   A VP8 decoder should take appropriate security considerations into
   account, as outlined in [RFC4732] and [RFC3552].  It is extremely
   important that a decoder be robust against malicious payloads.
   Malicious payloads must not cause the decoder to overrun its
   allocated memory or to consume inordinate resources.  Although
   encoder issues are typically rarer, the same applies to an encoder.
   Malicious stream data must not cause the encoder to misbehave, as
   this might allow an attacker access to transcoding gateways.

Top      Up      ToC       Page 303 
22.  References

22.1.  Normative Reference

   [RFC2119]   Bradner, S., "Key words for use in RFCs to Indicate
               Requirement Levels", BCP 14, RFC 2119, March 1997.

22.2.  Informative References

   [Bell]      Bell, T., Cleary, J., and I. Witten, "Text Compression",
               1990.

   [ISO-C99]   International Organization for Standardization,
               "Information technology --  Programming languages -- C",
               ISO/IEC 9899:1999, 1999.

   [ITU-R_BT.601]
               International Telecommunication Union, "ITU BT.601-7:
               Studio encoding parameters of digital television for
               standard 4:3 and wide screen 16:9 aspect ratios",
               March 2011.

   [Kernighan] Kernighan, B. and D. Ritchie, "The C Programming Language
               (2nd edition)", April 1988.

   [Loeffler]  Loeffler, C., Ligtenberg , A., and G. Moschytz,
               "Practical Fast 1-D DCT Algorithms with 11
               Multiplications", May 1989.

   [RFC3552]   Rescorla, E. and B. Korver, "Guidelines for Writing RFC
               Text on Security Considerations", BCP 72, RFC 3552,
               July 2003.

   [RFC4732]   Handley, M., Ed., Rescorla, E., Ed., and IAB, "Internet
               Denial-of-Service Considerations", RFC 4732,
               December 2006.

   [Shannon]   Shannon, C., "A Mathematical Theory of Communication",
               Bell System Technical Journal Vol. 27, pp. 379-423 and
               623-656, July and October 1948.

Top      Up      ToC       Page 304 
Authors' Addresses

   James Bankoski
   Google Inc.

   EMail: jimbankoski@google.com


   John Koleszar
   Google Inc.

   EMail: jkoleszar@google.com


   Lou Quillio
   Google Inc.

   EMail: louquillio@google.com


   Janne Salonen
   Google Inc.

   EMail: jsalonen@google.com


   Paul Wilkins
   Google Inc.

   EMail: paulwilkins@google.com


   Yaowu Xu
   Google Inc.

   EMail: yaowu@google.com