documentation: more API details and examples.

site/user/api/skpaint.md

Index: site/user/api/skpaint.md
diff --git a/site/user/api/skpaint.md b/site/user/api/skpaint.md
index 1160df08d3af9ef4b04b11888284e629e2ba2f28..c160db52e77bbdfc1a3727a3ad2ac1cf10ab834b 100644
--- a/site/user/api/skpaint.md
+++ b/site/user/api/skpaint.md
@@ -56,16 +56,25 @@ them as is, or modifying them as the drawing proceeds.
 
 <!--?prettify lang=cc?-->
 
-    canvas->drawRect(..., paint1);
-    canvas->drawRect(..., paint2);
+    SkPaint paint1, paint2, paint3;
+    paint2.setStyle(SkPaint::kStroke_Style);
+    paint2.setStrokeWidth(3);
+    paint3.setAntiAlias(true);
+    paint3.setColor(SK_ColorRED);
+    paint3.setTextSize(80);
+
+    canvas->drawRect(SkRect::MakeXYWH(10,10,60,20), paint1);
+    canvas->drawRect(SkRect::MakeXYWH(80,10,60,20), paint2);
 
     paint2.setStrokeWidth(SkIntToScalar(5));
-    canvas->drawOval(..., paint2);
+    canvas->drawOval(SkRect::MakeXYWH(150,10,60,20), paint2);
 
-    canvas->drawText(..., paint3);
-    paint3.setColor(0xFF0000FF);
-    canvas->drawText(..., paint3);
+    canvas->drawText("SKIA", 4, 20, 120, paint3);
+    paint3.setColor(SK_ColorBLUE);
+    canvas->drawText("SKIA", 4, 20, 220, paint3);
 
+<a href="https://fiddle.skia.org/c/5203b17103f487dd33965b4211d80956">
+<img src="https://fiddle.skia.org/i/5203b17103f487dd33965b4211d80956_raster.png"></a>
 
 Beyond simple attributes such as color, strokes, and text values,
 paints support effects. These are subclasses of different aspects of
@@ -78,18 +87,31 @@ assign a SkShader to the paint.
 
 <!--?prettify lang=cc?-->
 
-    SkShader* shader = SkGradientShader::CreateLinear(...);
+    SkPoint points[2] = {
+        SkPoint::Make(0.0f, 0.0f),
+        SkPoint::Make(256.0f, 256.0f)
+    };
+    SkColor colors[2] = {SK_ColorBLUE, SK_ColorYELLOW};
+    SkShader* shader =
+            SkGradientShader::CreateLinear(
+                     points, colors, NULL, 2,
+                     SkShader::kClamp_TileMode, 0, NULL);
+    SkPaint paint;
     paint.setShader(shader);
     shader->unref();
+    canvas->drawPaint(paint);
+
+<a href="https://fiddle.skia.org/c/f91b5310d57744a5a1475b7e47d4a172">
+<img src="https://fiddle.skia.org/i/f91b5310d57744a5a1475b7e47d4a172_raster.png"></a>
 
 Now, anything drawn with that paint will be drawn with the gradient
-specified in the call to CreateLinear(). The shader object that is
+specified in the call to `CreateLinear()`. The shader object that is
 returned is reference-counted. Whenever any effects object, like a
 shader, is assigned to a paint, its reference-count is increased by
 the paint. To balance this, the caller in the above example calls
-unref() on the shader once it has assigned it to the paint. Now the
+`unref()` on the shader once it has assigned it to the paint. Now the
 paint is the only "owner" of that shader, and it will automatically
-call unref() on the shader when either the paint goes out of scope, or
+call `unref()` on the shader when either the paint goes out of scope, or
 if another shader (or null) is assigned to it.
 
 There are 6 types of effects that can be assigned to a paint:
@@ -116,3 +138,275 @@ but also for measuring it.
     paint.getTextBounds(...);
     paint.textToGlyphs(...);
     paint.getFontMetrics(...);
+
+ShShader
+--------
+
+Several shaders are defined (besides the linear gradient already mentioned):
+
+*   Bitmap Shader
+
+    <!--?prettify lang=cc?-->
+
+        canvas->clear(SK_ColorWHITE);
+        SkMatrix matrix;
+        matrix.setScale(0.75f, 0.75f);
+        matrix.preRotate(30.0f);
+        SkShader* shader =
+            SkShader::CreateBitmapShader(
+                source,
+                SkShader::kRepeat_TileMode ,
+                SkShader::kRepeat_TileMode ,
+                &matrix);
+        SkPaint paint;
+        paint.setShader(shader);
+        shader->unref();
+        canvas->drawPaint(paint);
+
+    <a href="https://fiddle.skia.org/c/0e8d08e0a0b342e9e45c364d0e5cea8a">
+    <img src="https://fiddle.skia.org/i/0e8d08e0a0b342e9e45c364d0e5cea8a_raster.png"></a>
+
+*   Radial Gradient Shader
+
+    <!--?prettify lang=cc?-->
+
+        SkColor colors[2] = {SK_ColorBLUE, SK_ColorYELLOW};
+        SkShader* shader =
+                SkGradientShader::CreateRadial(
+                        SkPoint::Make(128.0f, 128.0f), 180.0f,
+                        colors, NULL, 2, SkShader::kClamp_TileMode, 0, NULL);
+        SkPaint paint;
+        paint.setShader(shader);
+        shader->unref();
+        canvas->drawPaint(paint);
+
+    <a href="https://fiddle.skia.org/c/601abd2819e38365900bf62286986024">
+    <img src="https://fiddle.skia.org/i/601abd2819e38365900bf62286986024_raster.png"></a>
+
+*  Two-Point Conical Gradient Shader
+
+    <!--?prettify lang=cc?-->
+
+        SkColor colors[2] = {SK_ColorBLUE, SK_ColorYELLOW};
+        SkShader* shader =
+                SkGradientShader::CreateTwoPointConical(
+                         SkPoint::Make(128.0f, 128.0f), 128.0f,
+                         SkPoint::Make(128.0f, 16.0f), 16.0f,
+                         colors, NULL, 2, SkShader::kClamp_TileMode, 0, NULL);
+        SkPaint paint;
+        paint.setShader(shader);
+        shader->unref();
+        canvas->drawPaint(paint);
+
+    <a href="https://fiddle.skia.org/c/991f7d67ff1ccebd6c2c4fab18a76edc">
+    <img src="https://fiddle.skia.org/i/991f7d67ff1ccebd6c2c4fab18a76edc_raster.png"></a>
+
+
+*   Sweep Gradient Shader
+
+    <!--?prettify lang=cc?-->
+
+        SkColor colors[4] = {
+            SK_ColorCYAN, SK_ColorMAGENTA, SK_ColorYELLOW, SK_ColorCYAN};
+        SkShader* shader =
+                SkGradientShader::CreateSweep(
+                    128.0f, 128.0f, colors, NULL, 4, 0, NULL);
+        SkPaint paint;
+        paint.setShader(shader);
+        shader->unref();
+        canvas->drawPaint(paint);
+
+    <a href="https://fiddle.skia.org/c/cee9d1831f6679c3d88170f857995d12">
+    <img src="https://fiddle.skia.org/i/cee9d1831f6679c3d88170f857995d12_raster.png"></a>
+
+*   Fractal Perlin Noise Shader
+
+    <!--?prettify lang=cc?-->
+
+        canvas->clear(SK_ColorWHITE);
+        SkShader* shader = SkPerlinNoiseShader::CreateFractalNoise(
+                 0.05f, 0.05f, 4, 0.0f, NULL);
+        SkPaint paint;
+        paint.setShader(shader);
+        shader->unref();
+        canvas->drawPaint(paint);
+
+    <a href="https://fiddle.skia.org/c/cc45c5349c3b31f97da7c1af7f84162a">
+    <img src="https://fiddle.skia.org/i/cc45c5349c3b31f97da7c1af7f84162a_raster.png"></a>
+
+*   Turbulence Perlin Noise Shader
+
+    <!--?prettify lang=cc?-->
+
+        canvas->clear(SK_ColorWHITE);
+        SkShader* shader = SkPerlinNoiseShader::CreateTurbulence(
+                 0.05f, 0.05f, 4, 0.0f, NULL);
+        SkPaint paint;
+        paint.setShader(shader);
+        shader->unref();
+        canvas->drawPaint(paint);
+
+    <a href="https://fiddle.skia.org/c/52729ed3a71b89a6dba4f60e8eb67727">
+    <img src="https://fiddle.skia.org/i/52729ed3a71b89a6dba4f60e8eb67727_raster.png"></a>
+
+*   Compose Shader
+
+    <!--?prettify lang=cc?-->
+
+        SkColor colors[2] = {SK_ColorBLUE, SK_ColorYELLOW};
+        SkShader* shader1 =
+                SkGradientShader::CreateRadial(
+                    SkPoint::Make(128.0f, 128.0f), 180.0f,
+                    colors, NULL, 2, SkShader::kClamp_TileMode, 0, NULL);
+        SkShader* shader2 = SkPerlinNoiseShader::CreateTurbulence(
+                 0.025f, 0.025f, 2, 0.0f, NULL);
+        SkShader* shader =
+            new SkComposeShader(shader1, shader2);
+        SkPaint paint;
+        paint.setShader(shader);
+        shader->unref();
+        shader2->unref();
+        shader1->unref();
+        canvas->drawPaint(paint);
+
+    <a href="https://fiddle.skia.org/c/1209b7a29d870302edcc43dc0916e8d5">
+    <img src="https://fiddle.skia.org/i/1209b7a29d870302edcc43dc0916e8d5_raster.png"></a>
+
+
+SkMaskFilter
+------------
+
+*   Blur Mask Filter
+
+    <!--?prettify lang=cc?-->
+
+        canvas->drawColor(SK_ColorWHITE);
+        SkPaint paint;
+        paint.setAntiAlias(true);
+        paint.setTextSize(120);
+        SkMaskFilter* filter =
+            SkBlurMaskFilter::Create(
+                kNormal_SkBlurStyle, 5.0f, 0);
+        paint.setMaskFilter(filter);
+        filter->unref();
+        const char text[] = "Skia";
+        canvas->drawText(text, strlen(text), 0, 160, paint);
+
+    <a href="https://fiddle.skia.org/c/0e004664122851691d67a291007b64d7">
+    <img src="https://fiddle.skia.org/i/0e004664122851691d67a291007b64d7_raster.png"></a>
+
+*   Emboss Mask Filter
+
+    <!--?prettify lang=cc?-->
+
+        canvas->drawColor(SK_ColorWHITE);
+        SkPaint paint;
+        paint.setAntiAlias(true);
+        paint.setTextSize(120);
+        SkScalar direction[3] = {1.0f, 1.0f, 1.0f};
+        SkMaskFilter* filter =
+            SkBlurMaskFilter::CreateEmboss(
+                2.0f, direction, 0.3f, 0.1f);
+        paint.setMaskFilter(filter);
+        filter->unref();
+        const char text[] = "Skia";
+        canvas->drawText(text, strlen(text), 0, 160, paint);
+
+    <a href="https://fiddle.skia.org/c/1ef71be7fb749a2d81a55721b2d2c77d">
+    <img src="https://fiddle.skia.org/i/1ef71be7fb749a2d81a55721b2d2c77d_raster.png"></a>
+
+
+SkColorFilter
+-------------
+
+*   Color Matrix Color Filter
+
+    <!--?prettify lang=cc?-->
+
+        void f(SkCanvas* c, SkScalar x, SkScalar y, SkScalar colorMatrix[20]) {
+            SkColorFilter* cf = SkColorMatrixFilter::Create(colorMatrix);
+            SkPaint paint;
+            paint.setColorFilter(cf);
+            cf->unref();
+            c->drawBitmap(source, x, y, &paint);
+        }
+        void draw(SkCanvas* c) {
+            c->scale(0.25, 0.25);
+            SkScalar colorMatrix1[20] = {
+                0, 1, 0, 0, 0,
+                0, 0, 1, 0, 0,
+                1, 0, 0, 0, 0,
+                0, 0, 0, 1, 0};
+            f(c, 0, 0, colorMatrix1);
+
+            SkScalar grayscale[20] = {
+                0.21, 0.72, 0.07, 0.0, 0.0,
+                0.21, 0.72, 0.07, 0.0, 0.0,
+                0.21, 0.72, 0.07, 0.0, 0.0,
+                0.0,  0.0,  0.0,  1.0, 0.0};
+            f(c, 512, 0, grayscale);
+
+            SkScalar colorMatrix3[20] = {
+                -1, 1, 1, 0, 0,
+                1, -1, 1, 0, 0,
+                1, 1, -1, 0, 0,
+                0, 0, 0, 1, 0};
+            f(c, 0, 512, colorMatrix3);
+
+            SkScalar colorMatrix4[20] = {
+                0.0, 0.5, 0.5, 0, 0,
+                0.5, 0.0, 0.5, 0, 0,
+                0.5, 0.5, 0.0, 0, 0,
+                0.0, 0.0, 0.0, 1, 0};
+            f(c, 512, 512, colorMatrix4);
+
+            SkScalar highContrast[20] = {
+                4.0, 0.0, 0.0, 0.0, -4.0 * 255 / (4.0 - 1),
+                0.0, 4.0, 0.0, 0.0, -4.0 * 255 / (4.0 - 1),
+                0.0, 0.0, 4.0, 0.0, -4.0 * 255 / (4.0 - 1),
+                0.0, 0.0, 0.0, 1.0, 0.0};
+            f(c, 1024, 0, highContrast);
+
+            SkScalar colorMatrix6[20] = {
+                0, 0, 1, 0, 0,
+                1, 0, 0, 0, 0,
+                0, 1, 0, 0, 0,
+                0, 0, 0, 1, 0};
+            f(c, 1024, 512, colorMatrix6);
+
+            SkScalar sepia[20] = {
+                0.393, 0.769, 0.189, 0.0, 0.0,
+                0.349, 0.686, 0.168, 0.0, 0.0,
+                0.272, 0.534, 0.131, 0.0, 0.0,
+                0.0,   0.0,   0.0,   1.0, 0.0};
+            f(c, 1536, 0, sepia);
+
+            SkScalar inverter[20] = {
+                -1,  0,  0, 0, 255,
+                 0, -1,  0, 0, 255,
+                 0,  0, -1, 0, 255,
+                 0,  0,  0, 1, 0};
+            f(c, 1536, 512, inverter);
+        }
+
+    <a href="https://fiddle.skia.org/c/91fb5341ee7903c9682df20bb3d73dbb">
+    <img src="https://fiddle.skia.org/i/91fb5341ee7903c9682df20bb3d73dbb_raster.png"></a>
+
+*   Color Table Color Filter
+
+    <!--?prettify lang=cc?-->
+
+        canvas->scale(0.5, 0.5);
+        uint8_t ct[256];
+        for (int i = 0; i < 256; ++i) {
+            int x = (i - 96) * 255 / 64;
+            ct[i] = x < 0 ? 0 : x > 255 ? 255 : x;
+        }
+        SkColorFilter* cf = SkTableColorFilter::CreateARGB(NULL, ct, ct, ct);
+        SkPaint paint;
+        paint.setColorFilter(cf);
+        cf->unref();
+        canvas->drawBitmap(source, 0, 0, &paint);
+
+    <a href="https://fiddle.skia.org/c/0d3d339543afa1b10c60f9826f264c3f">
+    <img src="https://fiddle.skia.org/i/0d3d339543afa1b10c60f9826f264c3f_raster.png"></a>