add peekPixels to SkCanvas and SkSurface

include/core/SkCanvas.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 SkCanvas_DEFINED
 #define SkCanvas_DEFINED
 
@@ skipping 58 matching lines @@
 
     /** Construct a canvas with the specified bitmap to draw into.
         @param bitmap   Specifies a bitmap for the canvas to draw into. Its
                         structure are copied to the canvas.
     */
     explicit SkCanvas(const SkBitmap& bitmap);
     virtual ~SkCanvas();
 
     SkMetaData& getMetaData();
 
+    /**
+     *  Return ImageInfo for this canvas. If the canvas is not backed by pixels
+     *  (cpu or gpu), then the info's ColorType will be kUnknown_SkColorType.
+     */
+    SkImageInfo imageInfo() const;
+
     ///////////////////////////////////////////////////////////////////////////
 
     /**
      *  Trigger the immediate execution of all pending draw operations.
      */
     void flush();
 
     /**
+     *  DEPRECATED: call imageInfo() instead.
      *  Return the width/height of the underlying device. The current drawable
      *  area may be small (due to clipping or saveLayer). For a canvas with
      *  no device, 0,0 will be returned.
      */
     SkISize getDeviceSize() const;
 
-    /** Return the canvas' device object, which may be null. The device holds
-        the bitmap of the pixels that the canvas draws into. The reference count
-        of the returned device is not changed by this call.
-    */
+    /**
+     *  DEPRECATED.
+     *  Return the canvas' device object, which may be null. The device holds
+     *  the bitmap of the pixels that the canvas draws into. The reference count
+     *  of the returned device is not changed by this call.
+     */
     SkBaseDevice* getDevice() const;
 
     /**
      *  saveLayer() can create another device (which is later drawn onto
      *  the previous device). getTopDevice() returns the top-most device current
      *  installed. Note that this can change on other calls like save/restore,
      *  so do not access this device after subsequent canvas calls.
      *  The reference count of the device is not changed.
      *
      * @param updateMatrixClip If this is true, then before the device is
@@ skipping 12 matching lines @@
 
     /**
      * Return the GPU context of the device that is associated with the canvas.
      * For a canvas with non-GPU device, NULL is returned.
      */
     GrContext* getGrContext();
 
     ///////////////////////////////////////////////////////////////////////////
 
     /**
+     *  If the canvas has pixels (and is not recording to a picture or other
+     *  non-raster target) and has direct access to its pixels (i.e. they are in
+     *  local RAM) return the const-address of those pixels, and if not null,
+     *  return the ImageInfo and rowBytes. The returned address is only valid
+     *  while the canvas object is in scope and unchanged. Any API calls made on
+     *  canvas (or its parent surface if any) will invalidate the
+     *  returned address (and associated information).
+     *
+     *  On failure, returns NULL and the info and rowBytes parameters are
+     *  ignored.
+     */
+    const void* peekPixels(SkImageInfo* info, size_t* rowBytes);
+
+    /**
      * This enum can be used with read/writePixels to perform a pixel ops to or
      * from an 8888 config other than Skia's native config (SkPMColor). There
      * are three byte orders supported: native, BGRA, and RGBA. Each has a
      * premultiplied and unpremultiplied variant.
      *
      * Components of a 8888 pixel can be packed/unpacked from a 32bit word using
      * either byte offsets or shift values. Byte offsets are endian-invariant
      * while shifts are not. BGRA and RGBA configs are defined by byte
      * orderings. The native config is defined by shift values (SK_A32_SHIFT,
      * ..., SK_B32_SHIFT).
@@ skipping 873 matching lines @@
         intptr_t          fStorage[32];
         class SkDrawIter* fImpl;    // this points at fStorage
         SkPaint           fDefaultPaint;
         bool              fDone;
     };
 
 protected:
     // default impl defers to getDevice()->newSurface(info)
     virtual SkSurface* onNewSurface(const SkImageInfo&);
 
+    // default impl defers to its device
+    virtual const void* onPeekPixels(SkImageInfo*, size_t* rowBytes);
+
     // Returns the canvas to be used by DrawIter. Default implementation
     // returns this. Subclasses that encapsulate an indirect canvas may
     // need to overload this method. The impl must keep track of this, as it
     // is not released or deleted by the caller.
     virtual SkCanvas* canvasForDrawIter();
 
     // Clip rectangle bounds. Called internally by saveLayer.
     // returns false if the entire rectangle is entirely clipped out
     // If non-NULL, The imageFilter parameter will be used to expand the clip
     // and offscreen bounds for any margin required by the filter DAG.
@@ skipping 167 matching lines @@
         if (NULL != fCanvas) {
             fCanvas->endCommentGroup();
         }
     }
 
 private:
     SkCanvas* fCanvas;
 };
 #define SkAutoCommentBlock(...) SK_REQUIRE_LOCAL_VAR(SkAutoCommentBlock)
 
+/**
+ *  If the caller wants read-only access to the pixels in a canvas, it can just
+ *  call canvas->peekPixels(), since that is the fastest way to "peek" at the
+ *  pixels on a raster-backed canvas.
+ *
+ *  If the canvas has pixels, but they are not readily available to the CPU
+ *  (e.g. gpu-backed), then peekPixels() will fail, but readPixels() will
+ *  succeed (though be slower, since it will return a copy of the pixels).
+ *
+ *  SkAutoROCanvasPixels encapsulates these two techniques, trying first to call
+ *  peekPixels() (for performance), but if that fails, calling readPixels() and
+ *  storing the copy locally.
+ *
+ *  The caller must respect the restrictions associated with peekPixels(), since
+ *  that may have been called: The returned information is invalidated if...
+ *      - any API is called on the canvas (or its parent surface if present)
+ *      - the canvas goes out of scope
+ */
+class SkAutoROCanvasPixels : SkNoncopyable {
+public:
+    SkAutoROCanvasPixels(SkCanvas* canvas);
+
+    // returns NULL on failure
+    const void* addr() const { return fAddr; }
+    
+    // undefined if addr() == NULL
+    size_t rowBytes() const { return fRowBytes; }
+    
+    // undefined if addr() == NULL
+    const SkImageInfo& info() const { return fInfo; }
+
+    // helper that, if returns true, installs the pixels into the bitmap. Note
+    // that the bitmap may reference the address returned by peekPixels(), so
+    // the caller must respect the restrictions associated with peekPixels().
+    bool asROBitmap(SkBitmap*) const;
+
+private:
+    SkBitmap    fBitmap;    // used if peekPixels() fails
+    const void* fAddr;      // NULL on failure
+    SkImageInfo fInfo;
+    size_t      fRowBytes;
+};
+
 #endif