remove SkBitmap::allocConfigPixels and update dox

include/core/SkBitmap.h

 /*
  * Copyright 2006 The Android Open Source Project
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkBitmap_DEFINED
 #define SkBitmap_DEFINED
 
 #include "SkColor.h"
 #include "SkColorTable.h"
 #include "SkImageInfo.h"
 #include "SkPoint.h"
 #include "SkRefCnt.h"
 
 struct SkMask;
 struct SkIRect;
 struct SkRect;
 class SkPaint;
 class SkPixelRef;
 class SkPixelRefFactory;
 class SkRegion;
 class SkString;
 class GrTexture;
 
 /** \class SkBitmap
 
     The SkBitmap class specifies a raster bitmap. A bitmap has an integer width
-    and height, and a format (config), and a pointer to the actual pixels.
+    and height, and a format (colortype), and a pointer to the actual pixels.
     Bitmaps can be drawn into a SkCanvas, but they are also used to specify the
     target of a SkCanvas' drawing operations.
     A const SkBitmap exposes getAddr(), which lets a caller write its pixels;
     the constness is considered to apply to the bitmap's configuration, not
     its contents.
 */
 class SK_API SkBitmap {
 public:
     class SK_API Allocator;
 
     enum Config {
         kNo_Config,         //!< bitmap has not been configured
         kA8_Config,         //!< 8-bits per pixel, with only alpha specified (0 is transparent, 0xFF is opaque)
         kIndex8_Config,     //!< 8-bits per pixel, using SkColorTable to specify the colors
         kRGB_565_Config,    //!< 16-bits per pixel, (see SkColorPriv.h for packing)
         kARGB_4444_Config,  //!< 16-bits per pixel, (see SkColorPriv.h for packing)
         kARGB_8888_Config,  //!< 32-bits per pixel, (see SkColorPriv.h for packing)
     };
 
     // do not add this to the Config enum, otherwise the compiler will let us
     // pass this as a valid parameter for Config.
     enum {
         kConfigCount = kARGB_8888_Config + 1
     };
 
+    /** Return the config for the bitmap. */
+    Config  config() const;

[scroggo, 2014/06/05 16:59:34]

Should we deprecate this one too?

+    
+    SK_ATTR_DEPRECATED("use config()")
+    Config  getConfig() const { return this->config(); }

[scroggo, 2014/06/05 16:59:34]

Does Chrome still use this version? I removed Android's callers a while ago (and
I don't think any have snuck back in without me catching them).

+
     /**
      *  Default construct creates a bitmap with zero width and height, and no pixels.
-     *  Its config is set to kNo_Config.
+     *  Its colortype is set to kUnknown_SkColorType.
      */
     SkBitmap();
 
     /**
      *  Copy the settings from the src into this bitmap. If the src has pixels
      *  allocated, they will be shared, not copied, so that the two bitmaps will
      *  reference the same memory for the pixels. If a deep copy is needed,
      *  where the new bitmap has its own separate copy of the pixels, use
      *  deepCopyTo().
      */
@@ skipping 25 matching lines @@
         if (kUnknown_SkColorType == this->colorType()) {
             return false;
         }
         if (info) {
             *info = this->info();
         }
         return true;
     }
 #endif
 
-    /** Return the number of bytes per pixel based on the config. If the config
-     does not have at least 1 byte per (e.g. kA1_Config) then 0 is returned.
+    /**
+     *  Return the number of bytes per pixel based on the colortype. If the colortype is
+     *  kUnknown_SkColorType, then 0 is returned.
      */
     int bytesPerPixel() const { return fInfo.bytesPerPixel(); }
 
-    /** Return the rowbytes expressed as a number of pixels (like width and
-     height). Note, for 1-byte per pixel configs like kA8_Config, this will
-     return the same as rowBytes(). Is undefined for configs that are less
-     than 1-byte per pixel (e.g. kA1_Config)
+    /**
+     *  Return the rowbytes expressed as a number of pixels (like width and height).
+     *  If the colortype is kUnknown_SkColorType, then 0 is returned.
      */
     int rowBytesAsPixels() const {
         return fRowBytes >> this->shiftPerPixel();
     }
 
-    /** Return the shift amount per pixel (i.e. 0 for 1-byte per pixel, 1 for
-     2-bytes per pixel configs, 2 for 4-bytes per pixel configs). Return 0
-     for configs that are not at least 1-byte per pixel (e.g. kA1_Config
-     or kNo_Config)
+    /**
+     *  Return the shift amount per pixel (i.e. 0 for 1-byte per pixel, 1 for 2-bytes per pixel
+     *  colortypes, 2 for 4-bytes per pixel colortypes). Return 0 for kUnknown_SkColorType.
      */
     int shiftPerPixel() const { return this->bytesPerPixel() >> 1; }
 
     ///////////////////////////////////////////////////////////////////////////
 
     /** Return true iff the bitmap has empty dimensions.
      *  Hey!  Before you use this, see if you really want to know drawsNothing() instead.
      */
     bool empty() const { return fInfo.isEmpty(); }
 
     /** Return true iff the bitmap has no pixelref. Note: this can return true even if the
      *  dimensions of the bitmap are > 0 (see empty()).
      *  Hey!  Before you use this, see if you really want to know drawsNothing() instead.
      */
     bool isNull() const { return NULL == fPixelRef; }
 
     /** Return true iff drawing this bitmap has no effect.
      */
     bool drawsNothing() const { return this->empty() || this->isNull(); }
 
-    /** Return the config for the bitmap. */
-    Config  config() const;
-
-    SK_ATTR_DEPRECATED("use config()")
-    Config  getConfig() const { return this->config(); }
-
     /** Return the number of bytes between subsequent rows of the bitmap. */
     size_t rowBytes() const { return fRowBytes; }
 
     /**
      *  Set the bitmap's alphaType, returning true on success. If false is
      *  returned, then the specified new alphaType is incompatible with the
-     *  Config, and the current alphaType is unchanged.
+     *  colortype, and the current alphaType is unchanged.
      *
      *  Note: this changes the alphatype for the underlying pixels, which means
      *  that all bitmaps that might be sharing (subsets of) the pixels will
      *  be affected.
      */
     bool setAlphaType(SkAlphaType);
 
     /** Return the address of the pixels for this SkBitmap.
     */
     void* getPixels() const { return fPixels; }
@@ skipping 56 matching lines @@
         improve performance by avoiding unnecessary overhead and resource
         consumption on the device.
     */
     void setIsVolatile(bool);
 
     /** Reset the bitmap to its initial state (see default constructor). If we are a (shared)
         owner of the pixels, that ownership is decremented.
     */
     void reset();
 
+#ifdef SK_SUPPORT_LEGACY_COMPUTE_CONFIG_SIZE

[scroggo, 2014/06/05 16:59:34]

This needs to be defined in skia_for_android_framework_defines (this CL broke
Android).

     /** Given a config and a width, this computes the optimal rowBytes value. This is called automatically
         if you pass 0 for rowBytes to setConfig().
     */
     static size_t ComputeRowBytes(Config c, int width);
 
     /** Return the bytes-per-pixel for the specified config. If the config is
         not at least 1-byte per pixel, return 0, including for kNo_Config.
     */
     static int ComputeBytesPerPixel(Config c);
 
     /** Return the shift-per-pixel for the specified config. If the config is
      not at least 1-byte per pixel, return 0, including for kNo_Config.
      */
     static int ComputeShiftPerPixel(Config c) {
         return ComputeBytesPerPixel(c) >> 1;
     }
 
     static int64_t ComputeSize64(Config, int width, int height);
     static size_t ComputeSize(Config, int width, int height);
+#endif
 
     /**
      *  This will brute-force return true if all of the pixels in the bitmap
      *  are opaque. If it fails to read the pixels, or encounters an error,
      *  it will return false.
      *
      *  Since this can be an expensive operation, the bitmap stores a flag for
      *  this (isOpaque). Only call this if you need to compute this value from
      *  "unknown" pixels.
      */
@@ skipping 35 matching lines @@
     /**
      *  Allocate a pixelref to match the specified image info, using the default
      *  allocator.
      *  On success, the bitmap's pixels will be "locked", and return true.
      *  On failure, the bitmap will be set to empty and return false.
      */
     bool allocPixels(const SkImageInfo& info) {
         return this->allocPixels(info, NULL, NULL);
     }
 
-    /**
-     *  Legacy helper function, which creates an SkImageInfo from the specified
-     *  config and then calls allocPixels(info).
-     */
-    bool allocConfigPixels(Config, int width, int height, bool isOpaque = false);
-
     bool allocN32Pixels(int width, int height, bool isOpaque = false) {
         SkImageInfo info = SkImageInfo::MakeN32Premul(width, height);
         if (isOpaque) {
             info.fAlphaType = kOpaque_SkAlphaType;
         }
         return this->allocPixels(info);
     }
 
     /**
      *  Install a pixelref that wraps the specified pixels and rowBytes, and
@@ skipping 56 matching lines @@
         @param dstSize  Size of destination buffer. Must be large enough to hold
                         pixels using indicated stride.
         @param dstRowBytes  Width of each line in the buffer. If 0, uses
                             bitmap's internal stride.
         @param preserveDstPad Must we preserve padding in the dst
     */
     bool copyPixelsTo(void* const dst, size_t dstSize, size_t dstRowBytes = 0,
                       bool preserveDstPad = false) const;
 
     /** Use the standard HeapAllocator to create the pixelref that manages the
-        pixel memory. It will be sized based on the current width/height/config.
+        pixel memory. It will be sized based on the current ImageInfo.
         If this is called multiple times, a new pixelref object will be created
         each time.
 
         If the bitmap retains a reference to the colortable (assuming it is
         not null) it will take care of incrementing the reference count.
 
         @param ctable   ColorTable (or null) to use with the pixels that will
-                        be allocated. Only used if config == Index8_Config
+                        be allocated. Only used if colortype == kIndex_8_SkColorType
         @return true if the allocation succeeds. If not the pixelref field of
                      the bitmap will be unchanged.
     */
     bool allocPixels(SkColorTable* ctable = NULL) {
         return this->allocPixels(NULL, ctable);
     }
 
     /** Use the specified Allocator to create the pixelref that manages the
-        pixel memory. It will be sized based on the current width/height/config.
+        pixel memory. It will be sized based on the current ImageInfo.
         If this is called multiple times, a new pixelref object will be created
         each time.
 
         If the bitmap retains a reference to the colortable (assuming it is
         not null) it will take care of incrementing the reference count.
 
         @param allocator The Allocator to use to create a pixelref that can
-                         manage the pixel memory for the current
-                         width/height/config. If allocator is NULL, the standard
-                         HeapAllocator will be used.
+                         manage the pixel memory for the current ImageInfo.
+                         If allocator is NULL, the standard HeapAllocator will be used.
         @param ctable   ColorTable (or null) to use with the pixels that will
-                        be allocated. Only used if config == Index8_Config.
-                        If it is non-null and the config is not Index8, it will
+                        be allocated. Only used if colortype == kIndex_8_SkColorType.
+                        If it is non-null and the colortype is not indexed, it will
                         be ignored.
         @return true if the allocation succeeds. If not the pixelref field of
                      the bitmap will be unchanged.
     */
     bool allocPixels(Allocator* allocator, SkColorTable* ctable);
 
     /**
      *  Return the current pixelref object or NULL if there is none. This does
      *  not affect the refcount of the pixelref.
      */
@@ skipping 43 matching lines @@
 
     /**
      *  Some bitmaps can return a copy of their pixels for lockPixels(), but
      *  that copy, if modified, will not be pushed back. These bitmaps should
      *  not be used as targets for a raster device/canvas (since all pixels
      *  modifications will be lost when unlockPixels() is called.)
      */
     bool lockPixelsAreWritable() const;
 
     /** Call this to be sure that the bitmap is valid enough to be drawn (i.e.
-        it has non-null pixels, and if required by its config, it has a
+        it has non-null pixels, and if required by its colortype, it has a
         non-null colortable. Returns true if all of the above are met.
     */
     bool readyToDraw() const {
         return this->getPixels() != NULL &&
                (this->colorType() != kIndex_8_SkColorType || NULL != fColorTable);
     }
 
     /** Returns the pixelRef's texture, or NULL
      */
     GrTexture* getTexture() const;
@@ skipping 13 matching lines @@
     uint32_t getGenerationID() const;
 
     /** Call this if you have changed the contents of the pixels. This will in-
         turn cause a different generation ID value to be returned from
         getGenerationID().
     */
     void notifyPixelsChanged() const;
 
     /**
      *  Fill the entire bitmap with the specified color.
-     *  If the bitmap's config does not support alpha (e.g. 565) then the alpha
-     *  of the color is ignored (treated as opaque). If the config only supports
+     *  If the bitmap's colortype does not support alpha (e.g. 565) then the alpha
+     *  of the color is ignored (treated as opaque). If the colortype only supports
      *  alpha (e.g. A1 or A8) then the color's r,g,b components are ignored.
      */
     void eraseColor(SkColor c) const {
         this->eraseARGB(SkColorGetA(c), SkColorGetR(c), SkColorGetG(c),
                         SkColorGetB(c));
     }
 
     /**
      *  Fill the entire bitmap with the specified color.
-     *  If the bitmap's config does not support alpha (e.g. 565) then the alpha
-     *  of the color is ignored (treated as opaque). If the config only supports
+     *  If the bitmap's colortype does not support alpha (e.g. 565) then the alpha
+     *  of the color is ignored (treated as opaque). If the colortype only supports
      *  alpha (e.g. A1 or A8) then the color's r,g,b components are ignored.
      */
     void eraseARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b) const;
 
     SK_ATTR_DEPRECATED("use eraseARGB or eraseColor")
     void eraseRGB(U8CPU r, U8CPU g, U8CPU b) const {
         this->eraseARGB(0xFF, r, g, b);
     }
 
     /**
      *  Fill the specified area of this bitmap with the specified color.
-     *  If the bitmap's config does not support alpha (e.g. 565) then the alpha
-     *  of the color is ignored (treated as opaque). If the config only supports
+     *  If the bitmap's colortype does not support alpha (e.g. 565) then the alpha
+     *  of the color is ignored (treated as opaque). If the colortype only supports
      *  alpha (e.g. A1 or A8) then the color's r,g,b components are ignored.
      */
     void eraseArea(const SkIRect& area, SkColor c) const;
 
     /** Scroll (a subset of) the contents of this bitmap by dx/dy. If there are
         no pixels allocated (i.e. getPixels() returns null) the method will
         still update the inval region (if present). If the bitmap is immutable,
         do nothing and return false.
 
         @param subset The subset of the bitmap to scroll/move. To scroll the
                       entire contents, specify [0, 0, width, height] or just
                       pass null.
         @param dx The amount to scroll in X
         @param dy The amount to scroll in Y
         @param inval Optional (may be null). Returns the area of the bitmap that
                      was scrolled away. E.g. if dx = dy = 0, then inval would
                      be set to empty. If dx >= width or dy >= height, then
                      inval would be set to the entire bounds of the bitmap.
-        @return true if the scroll was doable. Will return false if the bitmap
-                     uses an unsupported config for scrolling (only kA8,
-                     kIndex8, kRGB_565, kARGB_4444, kARGB_8888 are supported).
+        @return true if the scroll was doable. Will return false if the colortype is kUnkown or
+                     if the bitmap is immutable.
                      If no pixels are present (i.e. getPixels() returns false)
                      inval will still be updated, and true will be returned.
     */
     bool scrollRect(const SkIRect* subset, int dx, int dy,
                     SkRegion* inval = NULL) const;
 
     /**
      *  Return the SkColor of the specified pixel.  In most cases this will
-     *  require un-premultiplying the color.  Alpha only configs (A1 and A8)
+     *  require un-premultiplying the color.  Alpha only colortypes (e.g. kAlpha_8_SkColorType)
      *  return black with the appropriate alpha set.  The value is undefined
-     *  for kNone_Config or if x or y are out of bounds, or if the bitmap
+     *  for kUnknown_SkColorType or if x or y are out of bounds, or if the bitmap
      *  does not have any pixels (or has not be locked with lockPixels()).
      */
     SkColor getColor(int x, int y) const;
 
     /** Returns the address of the specified pixel. This performs a runtime
         check to know the size of the pixels, and will return the same answer
         as the corresponding size-specific method (e.g. getAddr16). Since the
         check happens at runtime, it is much slower than using a size-specific
         version. Unlike the size-specific methods, this routine also checks if
         getPixels() returns null, and returns that. The size-specific routines
         perform a debugging assert that getPixels() is not null, but they do
         not do any runtime checks.
     */
     void* getAddr(int x, int y) const;
 
     /** Returns the address of the pixel specified by x,y for 32bit pixels.
      *  In debug build, this asserts that the pixels are allocated and locked,
-     *  and that the config is 32-bit, however none of these checks are performed
+     *  and that the colortype is 32-bit, however none of these checks are performed
      *  in the release build.
      */
     inline uint32_t* getAddr32(int x, int y) const;
 
     /** Returns the address of the pixel specified by x,y for 16bit pixels.
      *  In debug build, this asserts that the pixels are allocated and locked,
-     *  and that the config is 16-bit, however none of these checks are performed
+     *  and that the colortype is 16-bit, however none of these checks are performed
      *  in the release build.
      */
     inline uint16_t* getAddr16(int x, int y) const;
 
     /** Returns the address of the pixel specified by x,y for 8bit pixels.
      *  In debug build, this asserts that the pixels are allocated and locked,
-     *  and that the config is 8-bit, however none of these checks are performed
+     *  and that the colortype is 8-bit, however none of these checks are performed
      *  in the release build.
      */
     inline uint8_t* getAddr8(int x, int y) const;
 
     /** Returns the color corresponding to the pixel specified by x,y for
      *  colortable based bitmaps.
      *  In debug build, this asserts that the pixels are allocated and locked,
-     *  that the config is kIndex8, and that the colortable is allocated,
+     *  that the colortype is indexed, and that the colortable is allocated,
      *  however none of these checks are performed in the release build.
      */
     inline SkPMColor getIndex8Color(int x, int y) const;
 
     /** Set dst to be a setset of this bitmap. If possible, it will share the
-        pixel memory, and just point into a subset of it. However, if the config
+        pixel memory, and just point into a subset of it. However, if the colortype
         does not support this, a local copy will be made and associated with
         the dst bitmap. If the subset rectangle, intersected with the bitmap's
-        dimensions is empty, or if there is an unsupported config, false will be
+        dimensions is empty, or if there is an unsupported colortype, false will be
         returned and dst will be untouched.
         @param dst  The bitmap that will be set to a subset of this bitmap
         @param subset The rectangle of pixels in this bitmap that dst will
                       reference.
         @return true if the subset copy was successfully made.
     */
     bool extractSubset(SkBitmap* dst, const SkIRect& subset) const;
 
     /** Makes a deep copy of this bitmap, respecting the requested colorType,
      *  and allocating the dst pixels on the cpu.
      *  Returns false if either there is an error (i.e. the src does not have
      *  pixels) or the request cannot be satisfied (e.g. the src has per-pixel
-     *  alpha, and the requested config does not support alpha).
+     *  alpha, and the requested colortype does not support alpha).
      *  @param dst The bitmap to be sized and allocated
      *  @param ct The desired colorType for dst
      *  @param allocator Allocator used to allocate the pixelref for the dst
      *                   bitmap. If this is null, the standard HeapAllocator
      *                   will be used.
      *  @return true if the copy was made.
      */
     bool copyTo(SkBitmap* dst, SkColorType ct, Allocator* = NULL) const;
 
     bool copyTo(SkBitmap* dst, Allocator* allocator = NULL) const {
@@ skipping 53 matching lines @@
     bool extractAlpha(SkBitmap* dst, const SkPaint* paint, Allocator* allocator,
                       SkIPoint* offset) const;
 
     SkDEBUGCODE(void validate() const;)
 
     class Allocator : public SkRefCnt {
     public:
         SK_DECLARE_INST_COUNT(Allocator)
 
         /** Allocate the pixel memory for the bitmap, given its dimensions and
-            config. Return true on success, where success means either setPixels
+            colortype. Return true on success, where success means either setPixels
             or setPixelRef was called. The pixels need not be locked when this
-            returns. If the config requires a colortable, it also must be
+            returns. If the colortype requires a colortable, it also must be
             installed via setColorTable. If false is returned, the bitmap and
             colortable should be left unchanged.
         */
         virtual bool allocPixelRef(SkBitmap*, SkColorTable*) = 0;
     private:
         typedef SkRefCnt INHERITED;
     };
 
     /** Subclass of Allocator that returns a pixelref that allocates its pixel
         memory from the heap. This is the default Allocator invoked by
@@ skipping 50 matching lines @@
     };
 
     SkImageInfo fInfo;
 
     uint32_t    fRowBytes;
 
     uint8_t     fFlags;
 
     void internalErase(const SkIRect&, U8CPU a, U8CPU r, U8CPU g, U8CPU b)const;
 
-    /* Internal computations for safe size.
-    */
-    static int64_t ComputeSafeSize64(Config   config,
-                                     uint32_t width,
-                                     uint32_t height,
-                                     size_t   rowBytes);
-    static size_t ComputeSafeSize(Config   config,
-                                  uint32_t width,
-                                  uint32_t height,
-                                  size_t   rowBytes);
-
     /*  Unreference any pixelrefs or colortables
     */
     void freePixels();
     void updatePixelsFromRef() const;
 
     void legacyUnflatten(SkReadBuffer&);
 
     static void WriteRawPixels(SkWriteBuffer*, const SkBitmap&);
     static bool ReadRawPixels(SkReadBuffer*, SkBitmap*);
 
@@ skipping 110 matching lines @@
 }
 
 ///////////////////////////////////////////////////////////////////////////////
 //
 // Helpers until we can fully deprecate SkBitmap::Config
 //
 extern SkBitmap::Config SkColorTypeToBitmapConfig(SkColorType);
 extern SkColorType SkBitmapConfigToColorType(SkBitmap::Config);
 
 #endif