From a3a9ebcfb043b263d42c7d532ef487b99b9279fa Mon Sep 17 00:00:00 2001 From: halcanary Date: Mon, 27 Jul 2015 13:13:03 -0700 Subject: [PATCH] documentation: more API details and examples. NOTRY=true DOCS_PREVIEW= https://skia.org/user/api/skpaint?cl=1240893003 Review URL: https://codereview.chromium.org/1240893003 --- site/user/api/skpaint.md | 320 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 306 insertions(+), 14 deletions(-) diff --git a/site/user/api/skpaint.md b/site/user/api/skpaint.md index 1160df0..4db81c3 100644 --- a/site/user/api/skpaint.md +++ b/site/user/api/skpaint.md @@ -3,8 +3,6 @@ SkPaint *color, stroke, font, effects* - - Anytime you draw something in Skia, and want to specify what color it is, or how it blends with the background, or what style or font to draw it in, you specify those attributes in a paint. @@ -12,7 +10,7 @@ draw it in, you specify those attributes in a paint. Unlike `SkCanvas`, paints do not maintain an internal stack of state (i.e. there is no save/restore on a paint). However, paints are relatively light-weight, so the client may create and maintain any -number of paint objects, each setup for a particular use. Factoring +number of paint objects, each set up for a particular use. Factoring all of these color and stylistic attribute out of the canvas state, and into (multiple) paint objects, allows canvas' save/restore to be that much more efficient, as all they have to do is maintain the stack @@ -50,22 +48,31 @@ of matrix and clip settings. -This shows three different paints, each setup to draw in a different +This shows three different paints, each set up to draw in a different style. Now the caller can intermix these paints freely, either using them as is, or modifying them as the drawing proceeds. - 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); + + Beyond simple attributes such as color, strokes, and text values, paints support effects. These are subclasses of different aspects of @@ -78,18 +85,31 @@ assign a SkShader to the paint. - 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); + + + 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 +136,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 + + + + 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); + + + + +* Radial Gradient Shader + + + + 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); + + + + +* Two-Point Conical Gradient Shader + + + + 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); + + + + + +* Sweep Gradient Shader + + + + 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); + + + + +* Fractal Perlin Noise Shader + + + + 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); + + + + +* Turbulence Perlin Noise Shader + + + + 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); + + + + +* Compose Shader + + + + 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); + + + + + +SkMaskFilter +------------ + +* Blur Mask Filter + + + + 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); + + + + +* Emboss Mask Filter + + + + 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); + + + + + +SkColorFilter +------------- + +* Color Matrix Color Filter + + + + 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); + } + + + + +* Color Table Color Filter + + + + 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); + + + -- 2.7.4