Doxygen configuration file, documentation and minor cleanup on blitters.

git-svn-id: http://skia.googlecode.com/svn/trunk@2782 2bbb7eff-a529-9590-31e7-b0007b416f81

4 files changed, 141 insertions, 22 deletions

diff --git a/Doxyfile b/Doxyfile
new file mode 100644
index 0000000000..a1c7e4f10b
--- /dev/null
+++ b/Doxyfile
@@ -0,0 +1,45 @@
+PROJECT_NAME = skia
+PROJECT_BRIEF = 2D Graphics Library
+OUTPUT_DIRECTORY = doc
+
+EXTRACT_ALL = NO
+INHERIT_DOCS = YES
+INLINE_INHERITED_MEMB = NO
+JAVADOC_AUTOBRIEF = YES
+TAB_SIZE = 4
+WARN_IF_UNDOCUMENTED = NO
+
+# This file only creates documentation for the most important parts of the
+# external-visible API.
+INPUT = include/core include/effects
+EXTRACT_PRIVATE = YES
+EXTRACT_STATIC = YES
+
+HTML_DYNAMIC_SECTIONS = NO
+GENERATE_TREEVIEW = YES
+
+GENERATE_LATEX = NO
+
+# Good class diagrams require graphviz, but also more parameter tuning and
+# more build time than seems worthwhile.
+CLASS_DIAGRAMS = YES
+# HAVE_DOT = YES
+# CLASS_GRAPH = YES
+# COLLABORATION_GRAPH = YES
+# UML_LOOK = YES
+# GRAPHICAL_HIERARCHY = YES 
+
+# Make SkDEBUGCODE disappear, but not SK_OVERRIDE.
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+EXPAND_AS_DEFINED = SkDEBUGCODE
+
+# experimental evil only! inflates build time by 10 minutes
+# SEARCH_INCLUDES = YES
+# INCLUDE_GRAPH = YES
+# INCLUDED_BY_GRAPH = YES
+# DIRECTORY_GRAPH = YES
+# INTERACTIVE_SVG = YES
+
+
diff --git a/include/core/SkBlitter.h b/include/core/SkBlitter.h
index 18ec1e16a5..e58f216f28 100644
--- a/include/core/SkBlitter.h
+++ b/include/core/SkBlitter.h
@@ -17,29 +17,42 @@
 #include "SkRegion.h"
 #include "SkMask.h"
 
+/** SkBlitter and its subclasses are responsible for actually writing pixels
+    into memory. Besides efficiency, they handle clipping and antialiasing.
+*/
 class SkBlitter {
 public:
     virtual ~SkBlitter();
 
+    /// Blit a horizontal run of pixels.
     virtual void blitH(int x, int y, int width);
-    virtual void blitAntiH(int x, int y, const SkAlpha* antialias,
-                           const int16_t* runs);
+    /// Blit a horizontal run of antialiased pixels; runs[] is a *sparse*
+    /// zero-terminated run-length encoding of spans of constant alpha values.
+    virtual void blitAntiH(int x, int y, const SkAlpha antialias[],
+                           const int16_t runs[]);
+    /// Blit a vertical run of pixels with a constant alpha value.
     virtual void blitV(int x, int y, int height, SkAlpha alpha);
+    /// Blit a solid rectangle.
     virtual void blitRect(int x, int y, int width, int height);
+    /// Blit a pattern of pixels defined by a rectangle-clipped mask;
+    /// typically used for text.
     virtual void blitMask(const SkMask&, const SkIRect& clip);
 
-    /*  If the blitter just sets a single value for each pixel, return the
+    /** If the blitter just sets a single value for each pixel, return the
         bitmap it draws into, and assign value. If not, return NULL and ignore
         the value parameter.
     */
     virtual const SkBitmap* justAnOpaqueColor(uint32_t* value);
 
-    // not virtual, just helpers
+    ///@name non-virtual helpers
     void blitMaskRegion(const SkMask& mask, const SkRegion& clip);
     void blitRectRegion(const SkIRect& rect, const SkRegion& clip);
     void blitRegion(const SkRegion& clip);
+    ///@}
 
-    // factories
+    /** @name Factories
+        Return the correct blitter to use given the specified context.
+     */
     static SkBlitter* Choose(const SkBitmap& device,
                              const SkMatrix& matrix,
                              const SkPaint& paint) {
@@ -56,6 +69,7 @@ public:
                                    const SkBitmap& src,
                                    int left, int top,
                                    void* storage, size_t storageSize);
+    ///@}
 
 private:
 };
@@ -85,7 +99,6 @@ public:
         fClipRect = clipRect;
     }
 
-    // overrides
     virtual void blitH(int x, int y, int width) SK_OVERRIDE;
     virtual void blitAntiH(int x, int y, const SkAlpha[],
                            const int16_t runs[]) SK_OVERRIDE;
@@ -100,8 +113,8 @@ private:
 };
 
 /** Wraps another (real) blitter, and ensures that the real blitter is only
-called with coordinates that have been clipped by the specified clipRgn.
-This means the caller need not perform the clipping ahead of time.
+    called with coordinates that have been clipped by the specified clipRgn.
+    This means the caller need not perform the clipping ahead of time.
 */
 class SkRgnClipBlitter : public SkBlitter {
 public:
@@ -111,7 +124,6 @@ public:
         fRgn = clipRgn;
     }
 
-    // overrides
     virtual void blitH(int x, int y, int width) SK_OVERRIDE;
     virtual void blitAntiH(int x, int y, const SkAlpha[],
                            const int16_t runs[]) SK_OVERRIDE;
@@ -125,6 +137,10 @@ private:
     const SkRegion* fRgn;
 };
 
+/** Factory to set up the appropriate most-efficient wrapper blitter
+    to apply a clip. Returns a pointer to a member, so lifetime must
+    be managed carefully.
+*/
 class SkBlitterClipper {
 public:
     SkBlitter*  apply(SkBlitter* blitter, const SkRegion* clip,
diff --git a/src/core/SkAntiRun.h b/src/core/SkAntiRun.h
index 72d7a0c881..56b5ee5f73 100644
--- a/src/core/SkAntiRun.h
+++ b/src/core/SkAntiRun.h
@@ -12,19 +12,35 @@
 
 #include "SkBlitter.h"
 
+/** Sparse array of run-length-encoded alpha (supersampling coverage) values.
+    Sparseness allows us to independently compose several paths into the
+    same SkAlphaRuns buffer.
+*/
+
 class SkAlphaRuns {
 public:
     int16_t*    fRuns;
     uint8_t*     fAlpha;
 
+    /// Returns true if the scanline contains only a single run,
+    /// of alpha value 0.
     bool empty() const {
         SkASSERT(fRuns[0] > 0);
         return fAlpha[0] == 0 && fRuns[fRuns[0]] == 0;
     }
 
+    /// Reinitialize for a new scanline.
     void    reset(int width);
     
     /**
+     *  Insert into the buffer a run starting at (x-offsetX):
+     *      if startAlpha > 0
+     *          one pixel with value += startAlpha,
+     *              max 255
+     *      if middleCount > 0
+     *          middleCount pixels with value += maxValue
+     *      if stopAlpha > 0
+     *          one pixel with value += stopAlpha
      *  Returns the offsetX value that should be passed on the next call,
      *  assuming we're on the same scanline. If the caller is switching
      *  scanlines, then offsetX should be 0 when this is called.
@@ -35,8 +51,22 @@ public:
     SkDEBUGCODE(void assertValid(int y, int maxStep) const;)
     SkDEBUGCODE(void dump() const;)
 
+    /**
+     * Break the runs in the buffer at offsets x and x+count, properly
+     * updating the runs to the right and left.
+     *   i.e. from the state AAAABBBB, run-length encoded as A4B4,
+     *   Break(..., 2, 5) would produce AAAABBBB rle as A2A2B3B1.
+     * Allows add() to sum another run to some of the new sub-runs.
+     *   i.e. adding ..CCCCC. would produce AADDEEEB, rle as A2D2E3B1.
+     */
     static void Break(int16_t runs[], uint8_t alpha[], int x, int count);
 
+    /**
+     * Cut (at offset x in the buffer) a run into two shorter runs with
+     * matching alpha values.
+     * Used by the RectClipBlitter to trim a RLE encoding to match the
+     * clipping rectangle.
+     */
     static void BreakAt(int16_t runs[], uint8_t alpha[], int x) {
         while (x > 0) {
             int n = runs[0];
diff --git a/src/core/SkScan_AntiPath.cpp b/src/core/SkScan_AntiPath.cpp
index d33dd2e714..bf9866ec97 100644
--- a/src/core/SkScan_AntiPath.cpp
+++ b/src/core/SkScan_AntiPath.cpp
@@ -18,13 +18,18 @@
 #define SCALE   (1 << SHIFT)
 #define MASK    (SCALE - 1)
 
-/*
+/** @file
     We have two techniques for capturing the output of the supersampler:
     - SUPERMASK, which records a large mask-bitmap
         this is often faster for small, complex objects
     - RLE, which records a rle-encoded scanline
         this is often faster for large objects with big spans
 
+    These blitters use two coordinate systems:
+    - destination coordinates, scale equal to the output - often
+        abbreviated with 'i' or 'I' in variable names
+    - supersampled coordinates, scale equal to the output * SCALE
+
     NEW_AA is a set of code-changes to try to make both paths produce identical
     results. Its not quite there yet, though the remaining differences may be
     in the subsequent blits, and not in the different masks/runs...
@@ -35,26 +40,37 @@
 
 ///////////////////////////////////////////////////////////////////////////////
 
+/// Base class for a single-pass supersampled blitter.
 class BaseSuperBlitter : public SkBlitter {
 public:
     BaseSuperBlitter(SkBlitter* realBlitter, const SkIRect& ir,
                      const SkRegion& clip);
 
+    /// Must be explicitly defined on subclasses.
     virtual void blitAntiH(int x, int y, const SkAlpha antialias[],
                            const int16_t runs[]) SK_OVERRIDE {
         SkASSERT(!"How did I get here?");
     }
+    /// May not be called on BaseSuperBlitter because it blits out of order.
     virtual void blitV(int x, int y, int height, SkAlpha alpha) SK_OVERRIDE {
         SkASSERT(!"How did I get here?");
     }
 
 protected:
     SkBlitter*  fRealBlitter;
+    /// Current y coordinate, in destination coordinates.
     int         fCurrIY;
-    int         fWidth, fLeft, fSuperLeft;
+    /// Widest row of region to be blitted, in destination coordinates.
+    int         fWidth;
+    /// Leftmost x coordinate in any row, in destination coordinates.
+    int         fLeft;
+    /// Leftmost x coordinate in any row, in supersampled coordinates.
+    int         fSuperLeft;
 
     SkDEBUGCODE(int fCurrX;)
+    /// Current y coordinate in supersampled coordinates.
     int fCurrY;
+    /// Initial y coordinate (top of bounds).
     int fTop;
 };
 
@@ -81,6 +97,7 @@ BaseSuperBlitter::BaseSuperBlitter(SkBlitter* realBlitter, const SkIRect& ir,
     SkDEBUGCODE(fCurrX = -1;)
 }
 
+/// Run-length-encoded supersampling antialiased blitter.
 class SuperBlitter : public BaseSuperBlitter {
 public:
     SuperBlitter(SkBlitter* realBlitter, const SkIRect& ir,
@@ -91,9 +108,15 @@ public:
         sk_free(fRuns.fRuns);
     }
 
+    /// Once fRuns contains a complete supersampled row, flush() blits
+    /// it out through the wrapped blitter.
     void flush();
 
+    /// Blits a row of pixels, with location and width specified
+    /// in supersampled coordinates.
     virtual void blitH(int x, int y, int width) SK_OVERRIDE;
+    /// Blits a rectangle of pixels, with location and size specified
+    /// in supersampled coordinates.
     virtual void blitRect(int x, int y, int width, int height) SK_OVERRIDE;
 
 private:
@@ -133,8 +156,6 @@ static inline int coverage_to_alpha(int aa) {
     return aa;
 }
 
-#define SUPER_Mask      ((1 << SHIFT) - 1)
-
 void SuperBlitter::blitH(int x, int y, int width) {
     SkASSERT(width > 0);
 
@@ -170,8 +191,9 @@ void SuperBlitter::blitH(int x, int y, int width) {
     int stop = x + width;
 
     SkASSERT(start >= 0 && stop > start);
-    int fb = start & SUPER_Mask;
-    int fe = stop & SUPER_Mask;
+    // integer-pixel-aligned ends of blit, rounded out
+    int fb = start & MASK;
+    int fe = stop & MASK;
     int n = (stop >> SHIFT) - (start >> SHIFT) - 1;
 
     if (n < 0) {
@@ -186,7 +208,8 @@ void SuperBlitter::blitH(int x, int y, int width) {
         }
     }
 
-    fOffsetX = fRuns.add(x >> SHIFT, coverage_to_alpha(fb), n, coverage_to_alpha(fe),
+    fOffsetX = fRuns.add(x >> SHIFT, coverage_to_alpha(fb),
+                         n, coverage_to_alpha(fe),
                          (1 << (8 - SHIFT)) - (((y & MASK) + 1) >> SHIFT),
                          fOffsetX);
 
@@ -236,7 +259,8 @@ void SuperBlitter::blitRect(int x, int y, int width, int height) {
     SkASSERT(width > 0);
     SkASSERT(height > 0);
 
-    while ((y & SUPER_Mask)) {
+    // blit leading rows
+    while ((y & MASK)) {
         this->blitH(x, y++, width);
         if (--height <= 0) {
             return;
@@ -244,6 +268,9 @@ void SuperBlitter::blitRect(int x, int y, int width, int height) {
     }
     SkASSERT(height > 0);
 
+    // Since this is a rect, instead of blitting supersampled rows one at a
+    // time and then resolving to the destination canvas, we can blit
+    // directly to the destintion canvas one row per SCALE supersampled rows.
     int start_y = y >> SHIFT;
     int stop_y = (y + height) >> SHIFT;
     int count = stop_y - start_y;
@@ -262,9 +289,9 @@ void SuperBlitter::blitRect(int x, int y, int width, int height) {
         }
 
         int ileft = x >> SHIFT;
-        int xleft = x & SUPER_Mask;
+        int xleft = x & MASK;
         int irite = (x + width) >> SHIFT;
-        int xrite = (x + width) & SUPER_Mask;
+        int xrite = (x + width) & MASK;
         int n = irite - ileft - 1;
         if (n < 0) {
             // only one pixel, call blitV()?
@@ -314,7 +341,7 @@ void SuperBlitter::blitRect(int x, int y, int width, int height) {
     }
 
     // catch any remaining few
-    SkASSERT(height <= SUPER_Mask);
+    SkASSERT(height <= MASK);
     while (--height >= 0) {
         this->blitH(x, y++, width);
     }
@@ -322,6 +349,7 @@ void SuperBlitter::blitRect(int x, int y, int width, int height) {
 
 ///////////////////////////////////////////////////////////////////////////////
 
+/// Masked supersampling antialiased blitter.
 class MaskSuperBlitter : public BaseSuperBlitter {
 public:
     MaskSuperBlitter(SkBlitter* realBlitter, const SkIRect& ir,
@@ -489,8 +517,8 @@ void MaskSuperBlitter::blitH(int x, int y, int width) {
     int stop = x + width;
 
     SkASSERT(start >= 0 && stop > start);
-    int fb = start & SUPER_Mask;
-    int fe = stop & SUPER_Mask;
+    int fb = start & MASK;
+    int fe = stop & MASK;
     int n = (stop >> SHIFT) - (start >> SHIFT) - 1;