ppapi/cpp/image_data.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_CPP_IMAGE_DATA_H_
   6 #define PPAPI_CPP_IMAGE_DATA_H_
   7
   8 #include "ppapi/c/ppb_image_data.h"
   9 #include "ppapi/cpp/point.h"
  10 #include "ppapi/cpp/size.h"
  11 #include "ppapi/cpp/resource.h"
  12
  13 /// @file
  14 /// This file defines the APIs for determining how a browser
  15 /// handles image data.
  16 namespace pp {
  17
  18 class InstanceHandle;
  19
  20 class ImageData : public Resource {
  21  public:
  22   /// Default constructor for creating an is_null() <code>ImageData</code>
  23   /// object.
  24   ImageData();
  25
  26   /// A constructor used when you have received a <code>PP_Resource</code> as a
  27   /// return value that has already been reference counted.
  28   ///
  29   /// @param[in] resource A PP_Resource corresponding to image data.
  30   ImageData(PassRef, PP_Resource resource);
  31
  32   /// The copy constructor for <code>ImageData</code>. This constructor
  33   /// produces an <code>ImageData</code> object that shares the underlying
  34   /// <code>Image</code> resource with <code>other</code>.
  35   ///
  36   /// @param[in] other A pointer to an image data.
  37   ImageData(const ImageData& other);
  38
  39   /// A constructor that allocates a new <code>ImageData</code> in the browser
  40   /// with the provided parameters. The resulting object will be is_null() if
  41   /// the allocation failed.
  42   ///
  43   /// @param[in] instance The instance with which this resource will be
  44   /// associated.
  45   ///
  46   /// @param[in] format A PP_ImageDataFormat containing desired image format.
  47   /// PP_ImageDataFormat is an enumeration of the different types of
  48   /// image data formats. Refer to
  49   /// <a href="../c/ppb__image__data_8h.html">
  50   /// <code>ppb_image_data.h</code></a> for further information.
  51   ///
  52   /// @param[in] size A pointer to a <code>Size</code> containing the image
  53   /// size.
  54   ///
  55   /// @param[in] init_to_zero A bool used to determine transparency at
  56   /// creation. Set the <code>init_to_zero</code> flag if you want the bitmap
  57   /// initialized to transparent during the creation process. If this flag is
  58   /// not set, the current contents of the bitmap will be undefined, and the
  59   /// module should be sure to set all the pixels.
  60   ImageData(const InstanceHandle& instance,
  61             PP_ImageDataFormat format,
  62             const Size& size,
  63             bool init_to_zero);
  64
  65   /// This function decrements the reference count of this
  66   /// <code>ImageData</code> and increments the reference count of the
  67   /// <code>other</code> <code>ImageData</code>. This <code>ImageData</code>
  68   /// shares the underlying image resource with <code>other</code>.
  69   ///
  70   /// @param[in] other An other image data.
  71   ///
  72   /// @return A new image data context.
  73   ImageData& operator=(const ImageData& other);
  74
  75   /// IsImageDataFormatSupported() returns <code>true</code> if the supplied
  76   /// format is supported by the browser. Note:
  77   /// <code>PP_IMAGEDATAFORMAT_BGRA_PREMUL</code> and
  78   /// <code>PP_IMAGEDATAFORMAT_RGBA_PREMUL</code> formats are always supported.
  79   /// Other image formats do not make this guarantee, and should be checked
  80   /// first with IsImageDataFormatSupported() before using.
  81   ///
  82   /// @param[in] format Image data format.
  83   ///
  84   /// @return <code>true</code> if the format is supported by the browser.
  85   static bool IsImageDataFormatSupported(PP_ImageDataFormat format);
  86
  87   /// GetNativeImageDataFormat() determines the browser's preferred format for
  88   /// images. Using this format guarantees no extra conversions will occur when
  89   /// painting.
  90   ///
  91   /// @return <code>PP_ImageDataFormat</code> containing the preferred format.
  92   static PP_ImageDataFormat GetNativeImageDataFormat();
  93
  94   /// A getter function for returning the current format for images.
  95   ///
  96   /// @return <code>PP_ImageDataFormat</code> containing the preferred format.
  97   PP_ImageDataFormat format() const { return desc_.format; }
  98
  99   /// A getter function for returning the image size.
 100   ///
 101   /// @return The image size in pixels.
 102   pp::Size size() const { return desc_.size; }
 103
 104   /// A getter function for returning the row width in bytes.
 105   ///
 106   /// @return The row width in bytes.
 107   int32_t stride() const { return desc_.stride; }
 108
 109   /// A getter function for returning a raw pointer to the image pixels.
 110   ///
 111   /// @return A raw pointer to the image pixels.
 112   void* data() const { return data_; }
 113
 114   /// This function is used retrieve the address of the given pixel for 32-bit
 115   /// pixel formats.
 116   ///
 117   /// @param[in] coord A <code>Point</code> representing the x and y
 118   /// coordinates for a specific pixel.
 119   ///
 120   /// @return The address for the pixel.
 121   const uint32_t* GetAddr32(const Point& coord) const;
 122
 123   /// This function is used retrieve the address of the given pixel for 32-bit
 124   /// pixel formats.
 125   ///
 126   /// @param[in] coord A <code>Point</code> representing the x and y
 127   /// coordinates for a specific pixel.
 128   ///
 129   /// @return The address for the pixel.
 130   uint32_t* GetAddr32(const Point& coord);
 131
 132  private:
 133   void InitData();
 134
 135   PP_ImageDataDesc desc_;
 136   void* data_;
 137 };
 138
 139 }  // namespace pp
 140
 141 #endif  // PPAPI_CPP_IMAGE_DATA_H_