update comment on setShader to clarify alpha-bitmap behavior in bitmapshaders

BUG=skia:2293
R=bsalomon@google.com, yunchao.he@intel.com

Author: reed@google.com

Review URL: https://codereview.chromium.org/203203005

git-svn-id: http://skia.googlecode.com/svn/trunk@13851 2bbb7eff-a529-9590-31e7-b0007b416f81
diff --git a/gm/bitmapshader.cpp b/gm/bitmapshader.cpp
index 4649b7e..fb56307 100644
--- a/gm/bitmapshader.cpp
+++ b/gm/bitmapshader.cpp
@@ -35,6 +35,11 @@
     canvas.drawCircle(10, 10, 10, circlePaint);
 }
 
+static void adopt_shader(SkPaint* paint, SkShader* shader) {
+    paint->setShader(shader);
+    SkSafeUnref(shader);
+}
+
 class BitmapShaderGM : public GM {
 public:
 
@@ -50,40 +55,33 @@
     }
 
     virtual SkISize onISize() {
-        return make_isize(75, 100);
+        return SkISize::Make(75, 100);
     }
 
     virtual void onDraw(SkCanvas* canvas) {
-        SkShader* shader = SkShader::CreateBitmapShader(fBitmap,
-                                                        SkShader::kClamp_TileMode,
-                                                        SkShader::kClamp_TileMode);
         SkPaint paint;
-        paint.setShader(shader);
-        // release the shader ref as the paint now holds a reference
-        shader->unref();
+
+        adopt_shader(&paint, SkShader::CreateBitmapShader(fBitmap, SkShader::kClamp_TileMode,
+                                                          SkShader::kClamp_TileMode));
 
         // draw the shader with a bitmap mask
         canvas->drawBitmap(fMask, 0, 0, &paint);
         canvas->drawBitmap(fMask, 30, 0, &paint);
 
-           canvas->translate(0, 25);
+        canvas->translate(0, 25);
 
-        // draw the shader with standard geometry
-           canvas->drawCircle(10, 10, 10, paint);
-           canvas->drawCircle(40, 10, 10, paint); // no blue circle expected
+        canvas->drawCircle(10, 10, 10, paint);
+        canvas->drawCircle(40, 10, 10, paint); // no blue circle expected
 
-           canvas->translate(0, 25);
+        canvas->translate(0, 25);
 
-        shader = SkShader::CreateBitmapShader(fMask,
-                                              SkShader::kRepeat_TileMode,
-                                              SkShader::kRepeat_TileMode);
-        paint.setShader(shader);
+        adopt_shader(&paint, SkShader::CreateBitmapShader(fMask, SkShader::kRepeat_TileMode,
+                                                          SkShader::kRepeat_TileMode));
         paint.setColor(SK_ColorRED);
-        shader->unref();
 
-           // draw the mask using the shader and a color
-           canvas->drawRect(SkRect::MakeXYWH(0, 0, 20, 20), paint);
-           canvas->drawRect(SkRect::MakeXYWH(30, 0, 20, 20), paint);
+        // draw the mask using the shader and a color
+        canvas->drawRect(SkRect::MakeXYWH(0, 0, 20, 20), paint);
+        canvas->drawRect(SkRect::MakeXYWH(30, 0, 20, 20), paint);
     }
 
 private:
diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h
index d1853c6..e86d011 100644
--- a/include/core/SkPaint.h
+++ b/include/core/SkPaint.h
@@ -514,7 +514,12 @@
      *  once (e.g. bitmap tiling or gradient) and then change its transparency
      *  w/o having to modify the original shader... only the paint's alpha needs
      *  to be modified.
-     *  <p />
+     *
+     *  There is an exception to this only-respect-paint's-alpha rule: If the shader only generates
+     *  alpha (e.g. SkShader::CreateBitmapShader(bitmap, ...) where bitmap's colortype is kAlpha_8)
+     *  then the shader will use the paint's entire color to "colorize" its output (modulating the
+     *  bitmap's alpha with the paint's color+alpha).
+     *
      *  Pass NULL to clear any previous shader.
      *  As a convenience, the parameter passed is also returned.
      *  If a previous shader exists, its reference count is decremented.