Some SKPaint docs

docs/en/SkiaSharp/SKPaint.xml

@@ -19,6 +19,55 @@
   <Docs>
     <summary>Holds the style and color information about how to draw geometries, text and bitmaps.</summary>
     <remarks>
+      <para>Anytime you draw something in SkiaSharp, 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.</para>
+      <para>Unlike <see cref="T:SkiaSharp.SKCanvas" />, an SKPaint object do not maintain an internal stack of state.   That is, there is no save/restore on a paint. However, SKPaint objects are relatively light-weight, so the client may create and maintain any number of paint objects, each set up for a particular use. </para>
+      <para>Factoring all of these color and stylistic attributes out of the canvas state, and into (multiple) paint objects, allows the save and restore operations on the <see cref="T:SkiaSharp.SKCanvas" /> to be that much more efficient, as all they have to do is maintain the stack of matrix and clip settings.</para>
+      <para></para>
+      <para>The example above produces the following:</para>
+      <para>
+        <img href="SKPaintText.png" />
+      </para>
+      <para>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.</para>
+      <para>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.</para>
+      <para>For example, to draw using a gradient instead of a single color, assign a SkShader to the paint.</para>
+      <para>
+        <example>
+          <code lang="C#"><![CDATA[canvas.Clear (canvasColor);]]>
+<![CDATA[var points = new SKPoint (0, 0), new SKPoint (256, 256);]]>
+<![CDATA[var colors = new SKColor [] { new SKColor (0, 0, 255), new SKColor (0, 255, 0)};]]>
+<![CDATA[var offsets = new float [] { 0, 1 };
+var shader = SKShader.CreateLinearGradient (points, colors, offsets, SKShaderTileMode.Clamp);
+var paint = new SKPaint () {
+    Shader = shader,
+};
+canvas.DrawPaint (paint);]]></code>
+        </example>
+      </para>
+      <para>
+        <img href="gradient.png" />
+      </para>
+      <para>Now, anything drawn with that paint will be drawn with the gradient specified in the call to CreateLinearGradient.</para>
+      <para>There are five types of effects that can be assigned to an <see cref="T:SkiaSharp.SKPaint" /> object:</para>
+      <para>
+        <list type="bullet">
+          <item>
+            <term>BlendMode - Blend modes and Duff-Porter transfer modes.</term>
+          </item>
+          <item>
+            <term>ColorFilter - Modifies the source colors before applying the BlendMode.</term>
+          </item>
+          <item>
+            <term>MaskFilter - Modification of the alpha mask before it is colorized and drawn (for example, blur)</term>
+          </item>
+          <item>
+            <term>PathEffect - Modification of the geometry (path) before the alpha mask is generated (for example, dashing)</term>
+          </item>
+          <item>
+            <term>Shader - Gradients and bitmap patterns.</term>
+          </item>
+        </list>
+      </para>
+      <para></para>
       <para></para>
     </remarks>
   </Docs>