This function allows applications to supply their own alpha-levels (more commonly called gray values or grayscale) to be utilized by the Rasterizer when rasterizing output primitives (shapes, glyphs, characters).
When D-Type Engine is initialized, the default grayscale is supplied to the Rasterizer via one of the external .gsl files (see the Initialization Files section of this manual for details). If, however, the .gsl file is not available or not utilized, the Rasterizer will use a trivial (or ideal) grayscale (see below for details). In a typical scenario, there is no need for applications to call this function directly. However, this function may be suitable to applications that whish to change the active grayscale during run-time (e.g. in interactive programs that allow end-users to customize the grayscale).
Parameter | Description |
---|---|
gsv |
An array of custom gray values. This array must satisfy the following conditions:
For sample implementations of this array, refer to the gs002.gsl, gs004.gsl, gs006.gsl, gs016.gsl, gs256.gsl and gssqrt.gsl files that ship with D-Type Engine. The array in which the gray value of each element equals its index is called the trivial (or ideal) grayscale. The gs256.gsl file is a sample implementation of this array. All elements in the gsv array are copied to the Rasterizer's internal memory. Thus, this array can be discarded once the function returns. |
Note: Certain types of output primitives (e.g. glyphs) may be cached by the higher level API components (e.g. Typesetter) in their bitmap cache. This function does not have any impact on already cached output primitives. You may want to clear the respective cache when calling this function to ensure that all output primitives are affected in the same way.
If successful, the return value is 1. Otherwise, the function returns 0.
The grayscale defines the output intensity (alpha or gray value) of a rendered pixel depending on how much of its area is covered by an output primitive. Pixels that are completely inside the interior region of an output primitive are called "fully opaque" or "black" pixels, while pixels that are completely outside the interior region of an output primitive are called "fully transparent" or "white" pixels. Pixels that are partially covered by the interior region of an output primitive will have an alpha (gray) value that is defined by the current grayscale. D-Type Rasterizer distinguishes 256 different pixel coverages and, therefore, can support up to 256 alpha (gray) intensities.
Note that the commonly used terms "grayscale", "gray value", "black" or "white" are somewhat misleading. Rather than to indicate any specific color (i.e. shade of gray), they are meant to describe the transparency or opacity of a pixel (i.e. its alpha intensity). Thus, this function will have an impact on all rendered pixels regardless of their color (and not just black, white or gray pixels). With this understanding in mind, the above terms describe the intensity of a color rather than a mere shade of gray.
The actual color of an output primitive is specified by calling the OutputSetStyleAttribs function. On a pixel level, this translates into a whole range of color intensities (up to 256) which D-Type Rasterizer utilizes depending on how much of the pixel area is covered by the interior region of the output primitive. This is what gives pixels their anti-aliased appearance and/or the alpha blending effect when they are rendered by the Rasterizer.
The RasterizerSetGrayscale function can be used to reduce the total number of resulting color intensities or to compensate for the monitor gamma factor. For example, by utilizing only 8 or 16 different alpha intensities, the 256-color display systems will use colors in a more effective way. Or, by shifting alpha intensities towards "white", display systems with a high gamma factor will display colors and shades of gray more accurately. The full discussion of this topic, however, is far beyond the scope of this manual.
DT_SLONG i; DT_UBYTE gsv[256] for (i = 0; i < 256; i++) { gsv[i] = (DT_UBYTE)(16 * sqrt(i)); } dtRasterizerSetGrayscale(engine, gsv);