Dithered Rectangles

The process of alternating different color pixels across a region of a virtual buffer is called dithering. This technique is especially useful when using a 16-color display driver because you can simulate additional colors through effective uses of dithering. Fastgraph includes two functions for drawing dithered rectangles, one for screen space and one for world space. Neither function observes the clipping limits, nor do they affect the graphics cursor position. Dithered rectangles are not supported for direct color virtual buffers.

The fg_drect() function draws a dithered rectangle in screen space. Like the fg_rect() function, fg_drect() requires four integer parameters that respectively define the minimum x, maximum x, minimum y, and maximum y screen space coordinates of the rectangle. The minimum coordinates must be less than or equal to the maximum coordinates, or else the results are unpredictable. However, fg_drect() also requires a fifth parameter that defines the dithering matrix, which determines the pixel pattern used to build the dithered rectangle. The world space version of the dithered rectangle drawing function is fg_drectw(). Like fg_drect(), it requires four parameters that define the extremes of the rectangle, and a fifth parameter that defines the dithering matrix.

The dithering matrix is an eight-byte array containing a 4x2 pixel pattern that fg_drect() or fg_drectw() replicates across the rectangle's area. Suppose we would like to produce a "checkerboard" of light blue and white pixels. That is, in a given row of a rectangle, consecutive pixels will alternate between these two colors. Additionally, the pattern for adjacent rows will be shifted so there will always be a white pixel above and below a light blue pixel, and vice versa. Hence this pixel pattern would look something like

B W B W
W B W B
B W B W
W B W B

where each B represents a light blue pixel, and each W represents a white pixel. The pixel representation of the dithering matrix would appear as shown on the left; its translation to numeric values appears on the right.

The B pixels translate to color value 19 (light blue, assuming we're using the default logical palette), and the W pixels translate to color value 25 (white). The following code will draw a 50x50 rectangle, dithered with our blue and white checkerboard pattern, in the upper left corner of the active virtual buffer:

C/C++:

char matrix[8] = {25,19,19,25,25,19,19,25};
fg_drect(0,49,0,49,matrix);

Delphi:

const
  matrix : array [1..8] of byte = (25,19,19,25,25,19,19,25);
begin
  fg_drect(0,49,0,49,matrix);

Visual Basic:

Dim Matrix(8) As Byte
Matrix(0)=25: Matrix(1)=19: Matrix(2)=19: Matrix(3)=25
Matrix(4)=25: Matrix(5)=19: Matrix(6)=19: Matrix(7)=25
Call fg_drect(0, 49, 0, 49, Matrix(0))

There are two other important items pertaining to fg_drect() and fg_drectw(). First, the dithering matrix may not contain virtual color values. That is, the values stored in the dithering matrix always represent actual color numbers. Second, Fastgraph aligns the dithering matrix to specific pixel rows. If we let r represent the pixel row corresponding to the rectangle's minimum y coordinate, then the first row used in the dithering matrix is r modulo 4 (assuming the dithering matrix rows are numbered 0 to 3). This alignment enables you to use the same dithering matrix in multiple calls to fg_drect() and fg_drectw() for building an object of adjacent dithered rectangles (for example, an L-shaped area) and still have the dither pattern match where the rectangles intersect.