Add discard API to SkCanvas, plumb it to glDiscardFramebuffer()

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 579 matching lines @@
      *      canvas.clipRect(hugeRect, kReplace_Op);
      *      paint.setColor(color);
      *      paint.setXfermodeMode(kSrc_Mode);
      *      canvas.drawPaint(paint);
      *      canvas.restore();
      *  though it is almost always much more efficient.
      */
     virtual void clear(SkColor);
 
     /**
+     * This makes the contents of the canvas undefined. Subsequent calls that
+     * require reading the canvas contents will produce undefined results. Examples
+     * include blending and readPixels. The actual implementation is backend-
+     * dependent and one legal implementation is to do nothing. Like clear(), this
+     * ignores the clip.
+     *
+     * This function should only be called if the caller intends to subsequently
+     * draw to the canvas. The canvas may do real work at discard() time in order
+     * to optimize performance on subsequent draws. Thus, if you call this and then
+     * never draw to the canvas subsequently you may pay a perfomance penalty.
+     */
+    void discard() { this->onDiscard(); }
+
+    /**
      *  Fill the entire canvas' bitmap (restricted to the current clip) with the
      *  specified paint.
      *  @param paint    The paint used to fill the canvas
      */
     virtual void drawPaint(const SkPaint& paint);
 
     enum PointMode {
         /** drawPoints draws each point separately */
         kPoints_PointMode,
         /** drawPoints draws each pair of points as a line segment */
@@ skipping 559 matching lines @@
     enum ClipEdgeStyle {
         kHard_ClipEdgeStyle,
         kSoft_ClipEdgeStyle
     };
 
     virtual void onClipRect(const SkRect& rect, SkRegion::Op op, ClipEdgeStyle edgeStyle);
     virtual void onClipRRect(const SkRRect& rrect, SkRegion::Op op, ClipEdgeStyle edgeStyle);
     virtual void onClipPath(const SkPath& path, SkRegion::Op op, ClipEdgeStyle edgeStyle);
     virtual void onClipRegion(const SkRegion& deviceRgn, SkRegion::Op op);
 
+    virtual void onDiscard();
+
     // 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 224 matching lines @@
     bool asROBitmap(SkBitmap*) const;
 
 private:
     SkBitmap    fBitmap;    // used if peekPixels() fails
     const void* fAddr;      // NULL on failure
     SkImageInfo fInfo;
     size_t      fRowBytes;
 };
 
 #endif