diff options
Diffstat (limited to 'site/user/api/skpaint.md')
-rw-r--r-- | site/user/api/skpaint.md | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/site/user/api/skpaint.md b/site/user/api/skpaint.md new file mode 100644 index 0000000000..fdee783d4b --- /dev/null +++ b/site/user/api/skpaint.md @@ -0,0 +1,102 @@ +SkPaint +======= + +*color, stroke, font, effects* + +<!-- Updated Jan 17, 2013 by humper@google.com --> + +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. + +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 +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 +of matrix and clip settings. + +<!--?prettify lang=cc?--> + + SkPaint paint1, paint2, paint3; + + paint1.setColor(0xFFFF0000: + paint1.setStyle(SkPaint::kFill_Style); + + paint2.setColor(0x8000FF00); + paint2.setStyle(SkPaint::kStroke_Style); + paint2.setStrokeWidth(SkIntToScalar(3)); + + paint3.setColor(0xFF888888); + paint3.setTextSize(SkIntToScalar(24)); + paint3.setTextScaleX(SkFloatToScalar(0.75f)); + + +This shows three different paints, each setup 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. + +<!--?prettify lang=cc?--> + + canvas->drawRect(..., paint1); + canvas->drawRect(..., paint2); + + paint2.setStrokeWidth(SkIntToScalar(5)); + canvas->drawOval(..., paint2); + + canvas->drawText(..., paint3); + paint3.setColor(0xFF0000FF); + canvas->drawText(..., paint3); + + +Beyond simple attributes such as color, strokes, and text values, +paints support effects. These are subclasses of different aspects of +the drawing pipeline, that when referenced by a paint (each of them is +reference-counted), are called to override some part of the drawing +pipeline. + +For example, to draw using a gradient instead of a single color, +assign a SkShader to the paint. + +<!--?prettify lang=cc?--> + + SkShader* shader = SkGradientShader::CreateLinear(...); + paint.setShader(shader); + shader->unref(); + +Now, anything drawn with that paint will be drawn with the gradient +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 +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 +if another shader (or null) is assigned to it. + +There are 6 types of effects that can be assigned to a paint: + +* **SkPathEffect** - modifications to the geometry (path) before it + generates an alpha mask (e.g. dashing) +* **SkRasterizer** - composing custom mask layers (e.g. shadows) +* **SkMaskFilter** - modifications to the alpha mask before it is + colorized and drawn (e.g. blur, emboss) +* **SkShader** - e.g. gradients (linear, radial, sweep), bitmap patterns + (clamp, repeat, mirror) +* **SkColorFilter** - modify the source color(s) before applying the + xfermode (e.g. color matrix) +* **SkXfermode** - e.g. porter-duff transfermodes, blend modes + +Paints also hold a reference to a SkTypeface. The typeface represents +a specific font style, to be used for measuring and drawing +text. Speaking of which, paints are used not only for drawing text, +but also for measuring it. + +<!--?prettify lang=cc?--> + + paint.measureText(...); + paint.getTextBounds(...); + paint.textToGlyphs(...); + paint.getFontMetrics(...); |