1 SkPaint Overview 2 ======= 3 <span id="top"></span> 4 5 *color, stroke, font, effects* 6 7 <div class="float"> 8 <ul> 9 <li><a href="#">SkPaint</a></li> 10 <li><a href="#SkXfermode">SkXfermode</a></li> 11 <li><a href="#SkShader">SkShader</a></li> 12 <li><a href="#SkMaskFilter">SkMaskFilter</a></li> 13 <li><a href="#SkColorFilter">SkColorFilter</a></li> 14 <li><a href="#SkPathEffect">SkPathEffect</a></li> 15 </ul> 16 </div> 17 18 19 Anytime you draw something in Skia, and want to specify what color it 20 is, or how it blends with the background, or what style or font to 21 draw it in, you specify those attributes in a paint. 22 23 Unlike `SkCanvas`, paints do not maintain an internal stack of state 24 (i.e. there is no save/restore on a paint). However, paints are 25 relatively light-weight, so the client may create and maintain any 26 number of paint objects, each set up for a particular use. Factoring 27 all of these color and stylistic attributes out of the canvas state, 28 and into (multiple) paint objects, allows canvas' save/restore to be 29 that much more efficient, as all they have to do is maintain the stack 30 of matrix and clip settings. 31 32 <fiddle-embed name='@skpaint_skia'></fiddle-embed> 33 34 This shows three different paints, each set up to draw in a different 35 style. Now the caller can intermix these paints freely, either using 36 them as is, or modifying them as the drawing proceeds. 37 38 <fiddle-embed name='@skpaint_mix'></fiddle-embed> 39 40 Beyond simple attributes such as color, strokes, and text values, 41 paints support effects. These are subclasses of different aspects of 42 the drawing pipeline, that when referenced by a paint (each of them is 43 reference-counted), are called to override some part of the drawing 44 pipeline. 45 46 For example, to draw using a gradient instead of a single color, 47 assign a SkShader to the paint. 48 49 <fiddle-embed name='@skpaint_shader'></fiddle-embed> 50 51 Now, anything drawn with that paint will be drawn with the gradient 52 specified in the call to `MakeLinear()`. The shader object that is 53 returned is reference-counted. Whenever any effects object, like a 54 shader, is assigned to a paint, its reference-count is increased by 55 the paint. To balance this, the caller in the above example calls 56 `unref()` on the shader once it has assigned it to the paint. Now the 57 paint is the only "owner" of that shader, and it will automatically 58 call `unref()` on the shader when either the paint goes out of scope, or 59 if another shader (or null) is assigned to it. 60 61 There are 6 types of effects that can be assigned to a paint: 62 63 * **SkPathEffect** - modifications to the geometry (path) before it 64 generates an alpha mask (e.g. dashing) 65 * **SkRasterizer** - composing custom mask layers (e.g. shadows) 66 * **SkMaskFilter** - modifications to the alpha mask before it is 67 colorized and drawn (e.g. blur) 68 * **SkShader** - e.g. gradients (linear, radial, sweep), bitmap patterns 69 (clamp, repeat, mirror) 70 * **SkColorFilter** - modify the source color(s) before applying the 71 xfermode (e.g. color matrix) 72 * **SkXfermode** - e.g. porter-duff transfermodes, blend modes 73 74 Paints also hold a reference to a SkTypeface. The typeface represents 75 a specific font style, to be used for measuring and drawing 76 text. Speaking of which, paints are used not only for drawing text, 77 but also for measuring it. 78 79 <!--?prettify lang=cc?--> 80 81 paint.measureText(...); 82 paint.getTextBounds(...); 83 paint.textToGlyphs(...); 84 paint.getFontMetrics(...); 85 86 <span id="SkXfermode"></span> 87 88 SkXfermode 89 ---------- 90 91 The following example demonstrates all of the Skia's standard transfer 92 modes. In this example the source is a solid magenta color with a 93 horizontal alpha gradient and the destination is a solid cyan color 94 with a vertical alpha gradient. 95 96 <fiddle-embed name='@skpaint_xfer'></fiddle-embed> 97 98 <span id="SkShader"></span> 99 100 SkShader 101 -------- 102 103 Several shaders are defined (besides the linear gradient already mentioned): 104 105 * Bitmap Shader 106 107 <fiddle-embed name='@skpaint_bitmap_shader'></fiddle-embed> 108 109 * Radial Gradient Shader 110 111 <fiddle-embed name='@skpaint_radial'></fiddle-embed> 112 113 * Two-Point Conical Gradient Shader 114 115 <fiddle-embed name='@skpaint_2pt'></fiddle-embed> 116 117 118 * Sweep Gradient Shader 119 120 <fiddle-embed name='@skpaint_sweep'></fiddle-embed> 121 122 * Fractal Perlin Noise Shader 123 124 <fiddle-embed name='@skpaint_perlin'></fiddle-embed> 125 126 * Turbulence Perlin Noise Shader 127 128 <fiddle-embed name='@skpaint_turb'></fiddle-embed> 129 130 * Compose Shader 131 132 <fiddle-embed name='@skpaint_compose_shader'></fiddle-embed> 133 134 135 <span id="SkMaskFilter"></span> 136 137 SkMaskFilter 138 ------------ 139 140 * Blur Mask Filter 141 142 <fiddle-embed name='@skpaint_blur_mask_filter'></fiddle-embed> 143 144 145 <span id="SkColorFilter"></span> 146 147 SkColorFilter 148 ------------- 149 150 * Color Matrix Color Filter 151 152 <fiddle-embed name='@skpaint_matrix_color_filter'></fiddle-embed> 153 154 * Color Table Color Filter 155 156 <fiddle-embed name='@skpaint_color_table_filter'></fiddle-embed> 157 158 <span id="SkPathEffect"></span> 159 160 SkPathEffect 161 ------------ 162 163 * SkPath2DPathEffect: Stamp the specified path to fill the shape, 164 using the matrix to define the latice. 165 166 <fiddle-embed name='@skpaint_path_2d_path_effect'></fiddle-embed> 167 168 * SkLine2DPathEffect: a special case of SkPath2DPathEffect where the 169 path is a straight line to be stroked, not a path to be filled. 170 171 <fiddle-embed name='@skpaint_line_2d_path_effect'></fiddle-embed> 172 173 * SkPath1DPathEffect: create dash-like effects by replicating the specified path along the drawn path. 174 175 <fiddle-embed name='@skpaint_path_1d_path_effect'></fiddle-embed> 176 177 * SkCornerPathEffect: a path effect that can turn sharp corners into 178 various treatments (e.g. rounded corners). 179 180 <fiddle-embed name='@skpaint_corner_path_effects'></fiddle-embed> 181 182 * SkDashPathEffect: a path effect that implements dashing. 183 184 <fiddle-embed name='@skpaint_dash_path_effect'></fiddle-embed> 185 186 * SkDiscretePathEffect: This path effect chops a path into discrete 187 segments, and randomly displaces them. 188 189 <fiddle-embed name='@skpaint_discrete_path_effect'></fiddle-embed> 190 191 * SkComposePathEffect: a pathEffect whose effect is to apply 192 first the inner pathEffect and the the outer pathEffect (i.e. 193 outer(inner(path))). 194 195 <fiddle-embed name='@skpaint_compose_path_effect'></fiddle-embed> 196 197 * SkSumPathEffect: a pathEffect whose effect is to apply two effects, 198 in sequence (i.e. first(path) + second(path)). 199 200 <fiddle-embed name='@skpaint_sum_path_effect'></fiddle-embed> 201 202
