Low-Level Graphics and Character-Font Functions

The low-level graphics and font functions are declared in the include file GRAPH.H.

The library can be divided into the eight categories listed below, which correspond to the different tasks involved in creating and manipulating graphic objects.

The following sections explain each of these categories.

Configuring Mode and Environment

Routines that configure the mode and environment establish the graphics or text mode of operation, determine the current graphics environment, and control the display of the cursor.

Setting Coordinates

The “set coordinates” routines set the current text or graphics position and convert pixel coordinates between the various graphics coordinate systems.

The Microsoft graphics functions recognize three sets of coordinates:

Fixed physical coordinates

View coordinates defined by the application

Window coordinates that can include floating-point values

The functions in this category establish window and view coordinate systems and translate between physical, view, and window coordinate systems.

The default view coordinate system is identical to the physical screen coordinate system. The physical origin (0, 0) is always in the upper-left corner of the display. The x axis extends in the positive direction left to right, while the y axis extends in the positive direction top to bottom.

The physical horizontal and vertical dimensions depend on the hardware display configuration and the selected mode. These values are accessible at run time by examining the numxpixels and numypixels fields of the _videoconfig structure returned by _getvideoconfig. (The _getvideoconfig routine is listed in the previous section.)

The _setvieworg function allows you to move the viewport origin to a new position relative to the physical screen.

Routines that refer to coordinates on the physical screen or viewport require integer values. However, in real-world graphing applications, you might wish to use floating-point values, such as stock prices or average rainfall. The window coordinate system allows you to display graphics using floating-point values instead of integers.

The _getcurrentposition and _getcurrentposition_w routines allow you to determine the location of the current graphics-output point.

The _setcliprgn function defines a restricted active display area on the screen. The _setviewport function does the same thing and also resets the viewport origin to the upper-left corner of the restricted active display area.

The physical coordinates of any view-coordinate point can be determined with the _getphyscoord function, and the view coordinates of any physical point can be determined with the _getviewcoord function.

The view coordinates of any window coordinate can be determined with the _getviewcoord_w and _getviewcoord_wxy functions. The window coordinates of any view coordinate can be determined with the _getwindowcoord function.

The _setwindow function defines the current viewport as a real-coordinate window bound by the specified floating-point values.

Setting Low-Level Graphics Palettes

Use the low-level palette routines to select or remap color palettes.

Some video modes support a “color palette,” which is a table of the color values that can be displayed together on the screen at any given time. A “color value” is a long integer representing a color that can be displayed on your system.

In CGA color graphics modes, you can use the _selectpalette routine to choose one of several predefined palettes.

On EGA, MCGA, VGA, and SVGA video systems, you can “remap” (change) the palette using the _remappalette or _remapallpalette routines. For instance, the EGA _ERESCOLOR mode offers a total of 64 color values, of which 16 can be displayed at a time. In this mode, the palette contains 16 “color indices,” or slots to which you can assign color values.

The _remappalette routine changes a single color index to a specified color value. The _remapallpalette routine changes all of the available palette entries simultaneously.

Setting Attributes

The low-level output functions that draw lines, arcs, ellipses, and other basic figures do not specify color or line-style information. Instead, the low-level graphics functions rely on a set of attributes that are set independently by the following functions:

The _getcolor and _setcolor functions get or set the current color index for graphics and font output. The _getbkcolor and _setbkcolor functions get or set the current background color. (The _getbkcolor and _setbkcolor functions are listed in “Configuring Mode and Environment”.)

The _getfillmask and _setfillmask functions get or set the current fill mask. The mask is an 8-by-8-bit template array, with each bit representing a pixel. If a bit is 0, the pixel in memory is left untouched, as the mask is transparent to that pixel. If a bit is 1, the pixel is assigned the current color value. The template is repeated as necessary over the entire fill area.

The _getlinestyle and _setlinestyle functions get or set the current line style. The line style is determined by a 16-bit template buffer with each bit corresponding to a pixel. If a bit is 1, the pixel is set to the current color. If a bit is 0, the pixel is not changed. The template is repeated for the length of the line.

The _getwritemode and _setwritemode functions get or set the logical write mode for straight-line drawing. The default mode, _GPSET, causes lines to be drawn in the current graphics color. Other modes combine the current graphics color and the original screen image using various logical operations.

Creating Graphics Output

The graphics output functions use a set of specified coordinates and draw various figures. They use the current or default attributes for line-style mask, fill mask, write mode, background color, and foreground color.

The name of each function announces its task or the figure it draws, as the following list indicates:

Most of these routines are available in several forms, which are indicated by their names. Output functions without a suffix use the view coordinate system. Functions that end with _w take double values as arguments and use the window coordinate system. Functions that end with _wxy use _wxycoord structures to define the coordinates and use the window coordinate system.

Circular figures, such as arcs and ellipses, are centered within a “bounding rectangle” specified by two points that define the diagonally opposed corners of the rectangle. The center of the rectangle becomes the center of the figure, and the rectangle's borders determine the size of the figure.

Creating Text Output

The next group of routines provides text output in both graphics and text modes. Unlike the standard console I/O library routines, these functions recognize text-window boundaries and use the current text color.

The _outtext and _outmem routines provide no formatting. If you want to output integer or floating-point values, you must convert the values into a string variable (using the sprintf function) before calling these routines.

The _outtext routine recognizes the \n (newline character) and \r (carriage return) sequences. The _outmem routine treats these sequences as printable graphics characters.

Transferring Images

The functions in this category transfer screen images between memory and the display, using a buffer allocated by the application, or determine the size in bytes of the buffer needed to store a given image.

The functions that end with _w or _wxy use window coordinates; the other functions in this set use view coordinates.

In some cases, the buffer needed to store an image with the _getimage functions must be larger than 64K (65,534) bytes. Use the _halloc routine to allocate a buffer larger than 64K.

Displaying Fonts

The functions listed in this section control the display of font-based characters on the screen.