Stroke and fill paths with PDF patterns

Support for stroking and filling paths with PDF patterns has been introduced in XFINIUM.PDF v3.7. Both tiling and shading patterns are supported.

The base class for all patterns is PdfPattern. Shading patterns are defined by PdfShadingPattern class and tiling patterns are defined by PdfTilingPattern class. Both classes inherit from PdfPattern.

A shading pattern uses a shading object to provide a smooth transition between colors across an area to be painted.

A tiling pattern consists of a small graphical figure called a pattern cell. Painting with the pattern replicates the cell at fixed horizontal and vertical intervals to fill an area. Tiling patterns are divided into 2 categories, colored tiling patterns represented by PdfColoredTilingPattern class and uncolored tiling patterns represented by PdfUncoloredTilingPattern class. Both classes inherit from PdfTilingPattern.
A colored tiling pattern sets explicitly the color of each graphical element it paints. An uncolored tiling pattern has no inherent color and the color is specified separately when the pattern is used.

A PdfPatternPen object is used to stroke a path with a pattern and a PdfPatternBrush is used to fill a path with a pattern. Both objects use a PdfPatternColor to specify the stroke and fill style. The PdfPatternColor is created based on a PdfPatternColorSpace which specifies the actual pattern used for painting.

Tiling patterns

When a tiling pattern is created the size of the pattern cell must be specified. The content of the pattern cell is created through the pattern’s Graphics property.
These properties are common to all tiling patterns:

  • PdfGraphics Graphics – the pattern cell drawing surface
  • double Width – the width of a pattern cell
  • double Height – the height of a pattern cell
  • double XStep – the desired horizontal spacing between pattern cells. If XStep matches Width then the pattern cells will painted one next to another. If XStep is lower than Width the pattern cells will overlap on horizontal and if XStep is higher than Width then there will be a horizontal space between pattern cells.
  • double YStep – the desired vertical spacing between pattern cells. If YStep matches Height then the pattern cells will painted one next to another. If YStep is lower than Height the pattern cells will overlap on vertical and if YStep is higher than Height then there will be a vertical space between pattern cells.
  • – PdfMatrix Matrix – the pattern matrix

The content of a colored tilling pattern is created like any other graphics drawn on the page, no special considerations are required.

The content of an uncolored tiling patterns is created by using null for pen and brush colors. In this way the paths are stroked and filled but without specifying a color. Also only image masks can be drawn in an uncolored pattern. When a pattern pen or pattern brush that uses an uncolored pattern is used to stroke or fill a path the UncoloredPatternPaintColor property must be set on the pen or brush. This color will actually be used to paint the pattern.

Shading patterns

A shading pattern encapsulates a shading object for stroking or filling a path. The shading can be specified when the pattern is created or later. The difference between drawing using a shading pattern and drawing using a simple shading object is that the shading pattern can be used for stroking and filling paths when the shading object can only be used to fill a clipping region.

The full sample source code is available in our Samples Explorer application, Vector Graphics sample, DrawPatterns method.

Leave a Reply