ui/gfx/image/image.h

   1 // Copyright (c) 2012 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 // An Image wraps an image any flavor, be it platform-native GdkBitmap/NSImage,
   6 // or a SkBitmap. This also provides easy conversion to other image types
   7 // through operator overloading. It will cache the converted representations
   8 // internally to prevent double-conversion.
   9 //
  10 // The lifetime of both the initial representation and any converted ones are
  11 // tied to the lifetime of the Image's internal storage. To allow Images to be
  12 // cheaply passed around by value, the actual image data is stored in a ref-
  13 // counted member. When all Images referencing this storage are deleted, the
  14 // actual representations are deleted, too.
  15 //
  16 // Images can be empty, in which case they have no backing representation.
  17 // Attempting to use an empty Image will result in a crash.
  18
  19 #ifndef UI_GFX_IMAGE_IMAGE_H_
  20 #define UI_GFX_IMAGE_IMAGE_H_
  21
  22 #include <vector>
  23
  24 #include "base/basictypes.h"
  25 #include "base/containers/scoped_ptr_map.h"
  26 #include "base/gtest_prod_util.h"
  27 #include "base/memory/ref_counted_memory.h"
  28 #include "base/memory/scoped_ptr.h"
  29 #include "ui/gfx/gfx_export.h"
  30 #include "ui/gfx/native_widget_types.h"
  31
  32 #if defined(OS_MACOSX) && !defined(OS_IOS)
  33 typedef struct CGColorSpace* CGColorSpaceRef;
  34 #endif
  35
  36 class SkBitmap;
  37
  38 namespace {
  39 class ImageTest;
  40 class ImageMacTest;
  41 }
  42
  43 namespace gfx {
  44 struct ImagePNGRep;
  45 class ImageSkia;
  46 class Size;
  47
  48 namespace internal {
  49 class ImageRep;
  50 class ImageStorage;
  51 }
  52
  53 class GFX_EXPORT Image {
  54  public:
  55   enum RepresentationType {
  56     kImageRepCocoa,
  57     kImageRepCocoaTouch,
  58     kImageRepSkia,
  59     kImageRepPNG,
  60   };
  61
  62   typedef base::ScopedPtrMap<RepresentationType, scoped_ptr<internal::ImageRep>>
  63       RepresentationMap;
  64
  65   // Creates an empty image with no representations.
  66   Image();
  67
  68   // Creates a new image by copying the raw PNG-encoded input for use as the
  69   // default representation.
  70   explicit Image(const std::vector<ImagePNGRep>& image_reps);
  71
  72   // Creates a new image by copying the ImageSkia for use as the default
  73   // representation.
  74   explicit Image(const ImageSkia& image);
  75
  76 #if defined(OS_IOS)
  77   // Does not retain |image|; expects to take ownership.
  78   explicit Image(UIImage* image);
  79 #elif defined(OS_MACOSX)
  80   // Does not retain |image|; expects to take ownership.
  81   // A single NSImage object can contain multiple bitmaps so there's no reason
  82   // to pass a vector of these.
  83   explicit Image(NSImage* image);
  84 #endif
  85
  86   // Initializes a new Image by AddRef()ing |other|'s internal storage.
  87   Image(const Image& other);
  88
  89   // Copies a reference to |other|'s storage.
  90   Image& operator=(const Image& other);
  91
  92   // Deletes the image and, if the only owner of the storage, all of its cached
  93   // representations.
  94   ~Image();
  95
  96   // Creates an image from the passed in 1x bitmap.
  97   // WARNING: The resulting image will be pixelated when painted on a high
  98   // density display.
  99   static Image CreateFrom1xBitmap(const SkBitmap& bitmap);
 100
 101   // Creates an image from the PNG encoded input.
 102   // For example (from an std::vector):
 103   // std::vector<unsigned char> png = ...;
 104   // gfx::Image image =
 105   //     Image::CreateFrom1xPNGBytes(&png.front(), png.size());
 106   static Image CreateFrom1xPNGBytes(const unsigned char* input,
 107                                     size_t input_size);
 108
 109   // Creates an image from the PNG encoded input.
 110   static Image CreateFrom1xPNGBytes(
 111       const scoped_refptr<base::RefCountedMemory>& input);
 112
 113   // Converts the Image to the desired representation and stores it internally.
 114   // The returned result is a weak pointer owned by and scoped to the life of
 115   // the Image. Must only be called if IsEmpty() is false.
 116   const SkBitmap* ToSkBitmap() const;
 117   const ImageSkia* ToImageSkia() const;
 118 #if defined(OS_IOS)
 119   UIImage* ToUIImage() const;
 120 #elif defined(OS_MACOSX)
 121   NSImage* ToNSImage() const;
 122 #endif
 123
 124   // Returns the raw PNG-encoded data for the bitmap at 1x. If the data is
 125   // unavailable, either because the image has no data for 1x or because it is
 126   // empty, an empty RefCountedBytes object is returned. NULL is never
 127   // returned.
 128   scoped_refptr<base::RefCountedMemory> As1xPNGBytes() const;
 129
 130   // Same as ToSkBitmap(), but returns a null SkBitmap if this image is empty.
 131   SkBitmap AsBitmap() const;
 132
 133   // Same as ToImageSkia(), but returns an empty ImageSkia if this
 134   // image is empty.
 135   ImageSkia AsImageSkia() const;
 136
 137 #if defined(OS_MACOSX) && !defined(OS_IOS)
 138   // Same as ToSkBitmap(), but returns nil if this image is empty.
 139   NSImage* AsNSImage() const;
 140 #endif
 141
 142   // Performs a conversion, like above, but returns a copy of the result rather
 143   // than a weak pointer. The caller is responsible for deleting the result.
 144   // Note that the result is only a copy in terms of memory management; the
 145   // backing pixels are shared amongst all copies (a fact of each of the
 146   // converted representations, rather than a limitation imposed by Image) and
 147   // so the result should be considered immutable.
 148   scoped_refptr<base::RefCountedMemory> Copy1xPNGBytes() const;
 149   ImageSkia* CopyImageSkia() const;
 150   SkBitmap* CopySkBitmap() const;
 151 #if defined(OS_IOS)
 152   UIImage* CopyUIImage() const;
 153 #elif defined(OS_MACOSX)
 154   NSImage* CopyNSImage() const;
 155 #endif
 156
 157   // Inspects the representations map to see if the given type exists.
 158   bool HasRepresentation(RepresentationType type) const;
 159
 160   // Returns the number of representations.
 161   size_t RepresentationCount() const;
 162
 163   // Returns true if this Image has no representations.
 164   bool IsEmpty() const;
 165
 166   // Width and height of image in DIP coordinate system.
 167   int Width() const;
 168   int Height() const;
 169   gfx::Size Size() const;
 170
 171   // Swaps this image's internal representations with |other|.
 172   void SwapRepresentations(gfx::Image* other);
 173
 174 #if defined(OS_MACOSX) && !defined(OS_IOS)
 175   // Set the default representation's color space. This is used for converting
 176   // to NSImage. This is used to compensate for PNGCodec not writing or reading
 177   // colorspace ancillary chunks. (sRGB, iCCP).
 178   void SetSourceColorSpace(CGColorSpaceRef color_space);
 179 #endif  // defined(OS_MACOSX) && !defined(OS_IOS)
 180
 181  private:
 182   // Returns the type of the default representation.
 183   RepresentationType DefaultRepresentationType() const;
 184
 185   // Returns the ImageRep of the appropriate type or NULL if there is no
 186   // representation of that type (and must_exist is false).
 187   internal::ImageRep* GetRepresentation(
 188       RepresentationType rep_type, bool must_exist) const;
 189
 190   // Stores a representation into the map.
 191   void AddRepresentation(scoped_ptr<internal::ImageRep> rep) const;
 192
 193   // Internal class that holds all the representations. This allows the Image to
 194   // be cheaply copied.
 195   scoped_refptr<internal::ImageStorage> storage_;
 196
 197   friend class ::ImageTest;
 198   friend class ::ImageMacTest;
 199 };
 200
 201 }  // namespace gfx
 202
 203 #endif  // UI_GFX_IMAGE_IMAGE_H_