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

include/core/SkPaint.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.
  */
 
 
@@ skipping 496 matching lines @@
     SkShader* getShader() const { return fShader; }
 
     /** Set or clear the shader object.
      *  Shaders specify the source color(s) for what is being drawn. If a paint
      *  has no shader, then the paint's color is used. If the paint has a
      *  shader, then the shader's color(s) are use instead, but they are
      *  modulated by the paint's alpha. This makes it easy to create a shader
      *  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.
      *  If shader is not NULL, its reference count is incremented.
      *  @param shader   May be NULL. The shader to be installed in the paint
      *  @return         shader
      */
     SkShader* setShader(SkShader* shader);
 
     /** Get the paint's colorfilter. If there is a colorfilter, its reference
@@ skipping 619 matching lines @@
 #ifdef SK_BUILD_FOR_ANDROID
     SkPaintOptionsAndroid fPaintOptionsAndroid;
 
     // In order for the == operator to work properly this must be the last field
     // in the struct so that we can do a memcmp to this field's offset.
     uint32_t        fGenerationID;
 #endif
 };
 
 #endif