GFX Module

The GFX module provides an API for graphics-related tasks. With the GFX module, it is possible to support multiple display adapters in an abstract manner. The purpose of this module is to relieve the burden on the programmer of with having to directly interface with the hardware.

Rationale

Most multimedia applications will require graphical output of some kind. The DOS runtime environment lacks a unified, high-level interface for performing graphics tasks, however. Often, programmers are expected to directly to display adapters; this can be error prone, may require significant code investment, and may understand a fundamental understanding of how each adapter works. By providing an abstract interface for manipulating display adapters, it is hoped that this take will become much easier to deal with.

Concepts

Display

A display abstracts a single display adapter or other rendering output. A display offers a range of display specifications, which are graphics modes that the display supports. By choosing a display specification for the display, it becomes possible to interact with it, primary through its framebuffer surface.

A display specification does not always refer to an actual mode explicitly supported by the graphics adapter. For instance, CGA 160x100 16-color mode is simply a clever hack of mode 3h which has reduced the height of each character to 2 pixels; there is no single display mode within CGA that actually corresponds to this specification. Additionally, CGA mode 4h supports four different palettes (all equally garish) plus composite mode. For the purposes of simplicity, these are implemented as additional display specifications, even though they all correspond to the same graphics mode.

The list of available display specifications on the primary adapter is automatically detected by WDMF whenever the list of display modes is first requested. This
happens whenever a call to wdmf_gfx_dpySpecList() or a similar function is made. On success, this will return a circular linked list (tail first) which can be traversed to obtain a list of available display specifications. Once the first call is made, this list is cached to prevent need to redo adapter detection. Code to traverse the display specification list is found below:

#include <wdmf/gfx/display.h>
#include <stdio.h>
#include <stddef.h>

void availModes() {
    const wdmf_gfx_dpyspec_list_t* list, cur;
    size_t i = 0;

    tail = wdmf_gfx_dpySpecList();

    printf("Available display modes:\n");
    if (!tail)
        return;

    do {
        cur = cur->next;
        printf("  %zu - %s (%u x %u)\n", ++i, tail->spec->name, tail->spec->width, tail->spec->height);
    } while (cur != tail);
}

Surface

A surface is a raster or pixelbuffer which is laid out in a specified format. This removes the need to manipulate the raster directly (thought you can certainly do that if you'd like; but beware protected mode. It wraps several low-level operations such as plotting pixels, performing colorspace management, or copying regions to and from the image.

Graphics Context

A graphics context is a limited-lifetime, lightweight strategy object for performing high-level drawing operations such as drawing lines, shapes, and images. This
prevents the need for the surface to track a global rendering state, which might lead to unexpected bugs. By separated this into a separate context, this reduces the probability that rendering will occur when the surface's state is indeterminate.

Constituents

The following header files make up the GFX module:

• gfx/color.h - For color manipulation.
• gfx/display.h - For abstract display devices.
• gfx/surface.h - For abstract raster surfaces.
• gfx/vector.h - For vector types (like points and dimensions).
• gfx/vga.h - Low-level access to VGA and related interfaces.

Usage

To use the GFX module, include the appropriate headers (wdmf/gfx/*.h) during compilation and link against wdmfg. During the link phase, you must also
include the [CORE module]. For example, the following command will link an executable with the GFX module using DJGPP:

> gcc -o foo.exe foo.o -Lpath\to\wdmf\lib -lwdmf -lwdmf

Every API symbol exported by the GFX module is prefixed with wdmf_gfx. This is to prevent name collision and to make it clear that the symbol is related to this module.

See Also

• [CORE Module] for basic functionality provided by WDMF.
• [INPUT Module] for input management.
• [SOUND Module] for sound and music management.