DynaPDF Manual - Page 297

Previous Page 296   Index   Next Page 298

Function Reference
Page 297 of 839
device. When such a space is the current color space, the current color is a single-component value,
called a tint, that controls the application of the given colorant or color components only.
The parameter Colorant specifies the colorant name which this Separation color space is intended to
represent. The special colorant name All refers collectively to all colorants available on an output
device, including those for the standard process colorants. When a Separation space with this
colorant name is the current color space, painting operators apply tint values to all available
colorants at once. This is useful for purposes such as painting registration targets in the same place
on every separation.
Such marks are typically painted as the last step in composing a page to ensure that they are not
overwritten by subsequent painting operations.
The special colorant name None never produces any visible output. Painting operations in a
Separation space with this colorant name have no effect on the current page.
The parameter Alternate specifies the alternate color space in which the color should be rendered if
the device does not support the specified colorant. The alternate color space can be any Device or
CIE based color space but not in turn a special color space like Separation, Indexed, or DeviceN.
The parameter Handle specifies the handle of the alternate color space if a CIE based color space
should be used. If the alternate color space is a device color space the parameter Handle is ignored.
The parameter Color specifies the alternate color value, defined in the alternate color space, which is
used if the device does not support the colorant.
A color value in a Separation color space consists of a single tint component in the range 0 to 255.
The value 0 represents the minimum amount of colorant that can be applied; 255 represent the
maximum. Tints are always treated as subtractive colors, even if the device produces output for the
designated component by an additive method. Thus, a tint value of 0 denotes the lightest color that
can be achieved with the given colorant, and 255 is the darkest. This convention is the same as for
DeviceCMYK color components but opposite to the one for DeviceGray and DeviceRGB.
Encoding of Colorant Names
Colorant names are interpreted in the code page 1252 (WinAnsi) by default. Because colorant names
are stored in UTF-8 Unicode format in PDF, it is also possible to pass UTF-8 encoded Unicode
strings to the function. However, the function must be able to distinguish between both string
formats. To achieve this, the parameter Handle accepts the special flag 0x10000000 that specifies that
the parameter Colorant contains a UTF-8 encoded string. The flag must be combined with the handle
as follows:
handle |= 0x10000000;
// C/C++, C#
handle
= handle Or &H10000000 // Visual Basic
handle := handle or $10000000
// Delphi
If the alternate color space is a device color space, simply set the parameter to 0x10000000 to specify
that the colorant name is a UTF-8 string.
 

Previous topic: CreateResetAction, CreateSeparationCS

Next topic: CreateSetOCGStateAction