Index

C/C++ Functions

dtRasterizerSetGrayscale

DT_SWORD dtRasterizerSetGrayscale(DT_DTENGINE engine, const DT_UBYTE gsv[])

Short Description: Set Rasterizer's alpha levels (grayscale)

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).

Parameters

ParameterDescription

engine

Handle of the previously created Standard Engine instance.

gsv

An array of custom gray values. This array must satisfy the following conditions:

  • It must contain exactly 256 elements.

  • Each element in the array represents the output alpha (gray) value for the corresponding pixel coverage and must be in the 0 - 255 range.

  • The first element in the array (element whose index is 0) must be set to 0 and means "fully opaque" or "black". This value is reserved for pixels that are completely inside the interior region of an output primitive.

  • The last element in the array (element whose index is 255) must be set to 255 and means "fully transparent" or "white". This value is reserved for pixels that are completely outside the interior region of an output primitive.

  • The array must be non-descending. In other words, the alpha (gray) values in the array must not decrease as the element index increases. The actual distribution of gray values in this array to the remaining pixel coverages is up to your application.

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.

Return Value

If successful, the return value is 1. Otherwise, the function returns 0.

Comments

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 dtOutputSetStyleAttribs 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 dtRasterizerSetGrayscale 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.

Example

DT_SLONG i;
DT_UBYTE gsv[256]

for (i = 0; i < 256; i++)
{
    gsv[i] = (DT_UBYTE)(16 * sqrt(i));
}

dtRasterizerSetGrayscale(engine, gsv);
 

Index