add peekPixels to canvas

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.

[scroggo, 2014/02/12 18:40:58]

Something to think about - kNo_Config meant invalid in all cases, whereas
kUnknown does not.

This may be fine as is (at least for now), but maybe we'll find it makes sense
to have one type that is invalid, and one that is, perhaps neutral? i.e. a
picture doesn't really have an unknown color type - it has no inherent color
type.

+     */
+    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 canvas (or its parent surface if any) will invalidate the

[scroggo, 2014/02/12 18:40:58]

"canvas canvas" -> "canvas"

[reed2, 2014/02/13 14:43:35]

Done.

+     *  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
+ *  succed (though be slower, since it will return a copy of the pixels).

[scroggo, 2014/02/12 18:40:58]

succeed*

[reed2, 2014/02/13 14:43:35]

Done.

+ *
+ *  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; }
+    
+private:
+    SkBitmap    fBitmap;    // used if peekPixels() fails
+    const void* fAddr;      // NULL on failure
+    SkImageInfo fInfo;
+    size_t      fRowBytes;
+};
+
 #endif