Culling API

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 917 matching lines @@
     virtual void beginCommentGroup(const char* description) {
         // do nothing. Subclasses may do something
     }
     virtual void addComment(const char* kywd, const char* value) {
         // do nothing. Subclasses may do something
     }
     virtual void endCommentGroup() {
         // do nothing. Subclasses may do something
     }
 
+    /**
+     *  This call asserts that subsequent draw operations (up to the matching popCull() call)
+     *  are fully contained within the given bounding box. The assertion is not enforced,
+     *  but the information might be used to quick-reject command blocks, so an incorrect
+     *  bounding box may result in incomplete rendering.
+     */

[iancottrell, 2014/02/26 10:36:07]

Forgive me if I am misunderstanding something, I am still learning the ways of
Skia.
It seems to me like this is the wrong contract to offer. If all we are doing is
promising all nested draw calls are fully contained, why are we not just working
out the box automatically.
If instead we are adding a clipping stack, I can see that being a big win, but
if so this comment is not quite right.
Also, if we are adding a clipping stack, why not go all the way and treat it as
such, keep track of the current clip box, do intersecting test with clips as the
get pushed, and then use the extra information you get (results that don't
change the clip are redundant, results of zero size can drop all nested writes
etc)
You can even do this right down to the draw operation clips.

[robertphillips, 2014/02/26 13:52:02]

This is more of a contract on the caller's side. With this call they are
promising not to draw outside of the provided box (or accept the consequences if
they do). The motivation here is that it can be somewhat expensive to determine
the bounds for a given chunk of text. Blink already has that information so it
can just hand it to us via this interface. We can then use the cull box
information with the existing clip information to eliminate draw calls.

[f(malita), 2014/02/26 14:23:54]

We are currently quick-rejecting individual draw ops, but this offers the
opportunity of (hierarchical) *grouping* and quick-rejecting much larger chunks
at a time - which is critical in tiled playback mode.

You can think of it as an alternative to the bbox hierarchy built by tile
grid/r-tree/q-tree recorders, with bounds information coming directly from Blink
instead being recomputed at record time (which is expensive since it requires
re-measuring each op - particularly text, as Robert mentioned).
Clipping would be just as useful for quick-reject purposes, but much more
expensive (maintaining the raster clip up to date, and also for the GPU IIRC).

This is just a cheap way for clients to assert content bounds that Skia can then
use for playback optimizations.

Does that make sense/answer your question?

+    void pushCull(const SkRect& cullRect) {
+        ++fCullCount;
+        this->onPushCull(cullRect);
+    }
 
+    /**
+     *  Terminates the current culling block, and restores the previous one (if any).
+     */
+    void popCull() {
+        if (fCullCount > 0) {
+            --fCullCount;
+            this->onPopCull();
+        }
+    }
     //////////////////////////////////////////////////////////////////////////
 
     /** Get the current bounder object.
         The bounder's reference count is unchaged.
         @return the canva's bounder (or NULL).
     */
     SkBounder*  getBounder() const { return fBounder; }
 
     /** Set a new bounder (or NULL).
         Pass NULL to clear any previous bounder.
@@ skipping 145 matching lines @@
 
     // Called by child classes that override clipPath and clipRRect to only
     // track fast conservative clip bounds, rather than exact clips.
     bool updateClipConservativelyUsingBounds(const SkRect&, SkRegion::Op,
                                              bool inverseFilled);
 
     // notify our surface (if we have one) that we are about to draw, so it
     // can perform copy-on-write or invalidate any cached images
     void predrawNotify();
 
+    virtual void onPushCull(const SkRect& cullRect);
+    virtual void onPopCull();
+
 private:
     class MCRec;
 
     SkClipStack fClipStack;
     SkDeque     fMCStack;
     // points to top of stack
     MCRec*      fMCRec;
     // the first N recs that can fit here mean we won't call malloc
     uint32_t    fMCRecStorage[32];
 
     SkBounder*  fBounder;
     int         fSaveLayerCount;    // number of successful saveLayer calls
+    int         fCullCount;         // number of active culls
 
     SkMetaData* fMetaData;
 
     SkSurface_Base*  fSurfaceBase;
     SkSurface_Base* getSurfaceBase() const { return fSurfaceBase; }
     void setSurfaceBase(SkSurface_Base* sb) {
         fSurfaceBase = sb;
     }
     friend class SkSurface_Base;
     friend class SkSurface_Gpu;
@@ skipping 174 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