NAME

intro − introduction to Direct Graphics Interface

INTRODUCTION

This man-page describes an extension to the C interface to the X+ window system for performing high speed graphics operations within a window.  Through this extension an application directly drives the graphics hardware rather than making output requests to the X+ window system. 

The output functions defined by this layer include: rasterops, vectors, triangles, lists of vectors, polylines, and triangle lists.  A vector or triangle may be shaded and/or z buffered. 

Clients wishing to make use of this library should include the standard include file <X11/Xdirect.h>.  Both System V and BSD versions of the library are available. 

COOPERATING WITH X+

The X+ window system provides an environment in which several applications (or clients) can share the graphics hardware.  Typical clients of the X+ window system are: terminal emulators, mail programs, a system clock, performance meters, and application specific clients.  A window manager client is responsible for interacting with the user to allocate scarce system resources (such as screen real estate and color map space), and for running new applications (or other commands) based on user input. 

The direct mode graphics library provides a mechanism by which an application requiring very high speed graphics performance can coexist with other applications simultaneously using the display.  A client of the direct mode graphics library can also make use of other features of the X+ window system including:

a)Creating and manipulating windows

b)Performing the standard 2d raster graphics operations

c)Creating and modifying color maps

d)Double buffering

e)Using one of the standard X user interface toolkits

DRAWING DIRECTLY INTO AN X WINDOW

Before performing any of the direct graphics operations defined in this document you must first use XdCreateWindowHandle to initialize the window for direct graphics. 

CREATING AN ERROR HANDLER

Use XdSetErrorHandler to specify a function to be called whenever the low level graphics library detects that the screen geometry has changed.  Your own application takes responsibility for redrawing the graphics in all windows open for direct graphics to match the new screen geometry. 

RESPONDING TO AN EXPOSURE/CONFIGURE EVENT

Use XdReset when your program gets an exposure or configure event from the X server. 

This function refetches the clipping information for all windows which have currently been opened for direct graphics using XdCreateWindowHandle.  Calling this function helps to minimize the number of times an application draws something using this library only to find out that the screen geometry has changed. 

GETTING RID OF A WINDOW HANDLE

Use XdDestroyWindowHandle when you have finished performing direct graphics to a window. 

COORDINATES, POINTS and COLORS

In order to provide accurate shading information this library generalizes the standard X coordinate system by providing for subpixel positioning.  The x, y and z coordinates used in defining points, lines and triangles are floating point numbers.  The integer portion specifying the pixel position and the fractional portion providing subpixel resolution.  As usual all positions are specified relative to an origin at the top left hand corner of the window. We use the following structure to provide position information:

 typedef struct {
   double x, y, z ;
} XdPoint ;
 

Similarly we specify colors of points, lines and triangles using rgb floating point values in the range 0 to 1 using the following data structure:

 typedef struct {
   double r, g, b;
} XdColor ;
 

FILLING A RECTANGLE.

Use XdFillRectangle to fill a specified rectangle within a window. 

WRITING IMAGE DATA

This section describes three functions for writing pixel data to a window, namely XdWriteBitmap, XdWriteRectangle, and XdWriteRectangleRGB. 

Use XdWriteBitmap to output a rectangle of 1 bit deep pixels.  All scanlines must be of the same width and this width must be a multiple of 32.  The XdWriteBitmap function allows some sub-rectangle of the total image specified to be written to the screen.  Where in the image a 1 is specified the foreground color fg is used and where in the image a 0 is specified the background color bg is used.  The format of fg and bg is the same as for other standard Xlib calls: namely in a pseudo color window it is a color index, in a direct color window it has the form 0x00rrggbb, where rr, gg and bb specify the red, green, and blue indices in the color map. 

Use XdWriteRectangle to output a rectangle of 8 bit deep pixels.  Use XdWriteRectangleRGB to output a rectangle of 24 bit deep pixels.  The XdWriteRectangle functions allows some sub-rectangle of the total image specified to be written to the screen. 

READING IMAGE DATA

Use XdReadRectangle to read a rectangle of 8 bit deep pixels.  The XdReadRectangle functions reads a rectangular array of pixel data from the frame buffer into some sub-rectangle of the total memory image array. 

GEOMETRIC OUTPUT

Several functions are provided for geometric output, namely:

For drawing points:
      XdDrawPoint − single point, current base color
      XdDrawPointRGB − single point, specified color
      XdDrawPointList − list of points, base color
      XdDrawPointRGBList − list of points, specified colors
 For drawing lines:
      XdDrawLine − single line, current base color
      XdDrawLineRGB − single line, specified color
      XdDrawLineList − list of lines, base color
      XdDrawLineRGBList − list of lines, specified colors
 For drawing filled triangles:
      XdFillTriangle − single triangle, constant shade, base color
      XdFillTriangleRGB − single triangle, specified vertex colors
      XdFillTriangleList − list of triangles, current base color
      XdFillTriangleRGBList − list of triangles, specified vertex colors

SPECIFYING THE DRAW BUFFER

Use XdSetDrawBuffer to specify which buffer to draw into in a multiple buffered window. 

FLUSHING THE OUTPUT BUFFER

Use XdFlush to flush any pending output requests. 

SETTING ATTRIBUTES

Use XdSetZFunction to specify the current Z function. 

SETTING THE COLOR VALUES

Use XdSetBaseColor to specify the color for drawing geometric primitives without vertex colors.  Use XdSetShadeRange to specify the weights and min and max entries in the color map for mapping RGB values to color indices using shade range color approximation. Use XdSetPseudoBitfields to specify the weights and masks for mapping RGB values to color indices using ’bitfield compression’ color approximation.
 

SEE ALSO

There are separate man-pages provided for each of these functions.  The manpage names have been shortened so that each fits within the 14 character file name limit under System V.  The following man-page names correspond to the functions listed above.   

September 29, 2021