PDFlib 8 Windows COM/.NET Tutorial

3.5 Working with Color
Note The PDFlib API Reference contains a detailed list of supported color spaces with descriptions.
Cookbook Code samples regarding color issues can be found in the color category of the PDFlib Cookbook.
For an overview of using color spaces, see the Cookbook topic color/starter_color.
3.5.1 Patterns and Smooth Shadings
As an alternative to solid colors, patterns and shadings are special kinds of colors which
can be used to fill or stroke arbitrary objects.
Patterns. A pattern is defined by an arbitrary number of painting operations which
are grouped into a single entity. This group of objects can be used to fill or stroke arbitrary
other objects by replicating (or tiling) the group over the entire area to be filled or
the path to be stroked. Working with patterns involves the following steps:
> First, the pattern must be defined between begin_pattern( ) and end_pattern( ). Most
graphics operators can be used to define a pattern.
> The pattern handle returned by begin_pattern( ) can be used to set the pattern as the
current color using setcolor( ).
Depending on the painttype parameter of begin_pattern( ) the pattern definition may or
may not include its own color specification. If painttype is 1, the pattern definition must
contain its own color specification and will always look the same; if painttype is 2, the
pattern definition must not include any color specification. Instead, the current fill or
stroke color will be applied when the pattern is used for filling or stroking.
Note Patterns can also be defined based on a smooth shading (see below).
Cookbook Full code samples can be found in the Cookbook topics graphics/fill_pattern and
images/tiling_pattern.
Smooth shadings. Smooth shadings, also called color blends or gradients, provide a
continuous transition from one color to another. Both colors must be specified in the
same color space. PDFlib supports two different kinds of geometry for smooth shadings:
> axial shadings are defined along a line;
> radial shadings are defined between two circles.
Shadings are defined as a transition between two colors. The first color is always taken
to be the current fill color; the second color is provided in the c1, c2, c3, and c4 parameters
of shading( ). These numerical values will be interpreted in the first color’s color space
according to the description of setcolor( ).
Calling shading( ) will return a handle to a shading object which can be used in two
ways:
> Fill an area with shfill( ). This method can be used when the geometry of the object to
be filled is the same as the geometry of the shading. Contrary to its name this function
will not only fill the interior of the object, but also affects the exterior. This behavior
can be modified with clip( ).
> Define a shading pattern to be used for filling more complex objects. This involves
calling shading_pattern( ) to create a pattern based on the shading, and using this pattern
to fill or stroke arbitrary objects.
80 Chapter 3: Creating PDF Documents (Edition for COM, .NET, and REALbasic)