home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
C!T ROM 2
/
ctrom_ii_b.zip
/
ctrom_ii_b
/
PROGRAM
/
C
/
CBGRX102
/
INTERNAL.DOC
< prev
next >
Wrap
Text File
|
1992-08-12
|
7KB
|
171 lines
Abstract
========
This document describes contains information necessary for rebuilding
the LIBGRX graphics library. Additionally, it describes some internal
details of the library associated with way it accesses the video RAM. This
info might be useful for adding support for new graphics adapter types.
How to rebuild the library
==========================
The LIBGRX library is built using the Turbo C MAKE. (TC++ 1.01
professional was used.) If an other MAKE has to be used it has to provide
some method for generating response files from long command lines. The
makefiles may have to be changed from the Turbo C MAKE response file
syntax to the syntax of the new MAKE. Additionally, the Turbo C MAKE
provides a C preprocessor-like conditional syntax. If the new MAKE utility
does not support this, the desired option has to be hard-coded.
The makefile in the base directory of the package (typically it is
....djgpp\contrib\libgrx) can be invoked as follows:
1) make build DJGPP libraries, and the drivers
2) make turboc build Turbo C libraries
3) make test (1+) build DJGPP test programs
4) make turbotst (2+) build Turbo C test programs
5) make install copy .h and .a files into DJGPP dirs
6) make clean clean up after recompiling
All graphics library sources are in the 'src' directory. The makefile
in that directory can also be used to build a customized version of the
library. Customized libraries (and the executable built using them) can be
smaller, because they don't include support for all video RAM access
methods. (see later) The makefile in the src directory can be used as
follows:
make -DPLANES=<value>
-- or --
make -DPLANES=<value> [-DMODEL=<memory model>] turboc
The value of the PLANES macro determines the included video RAM access
methods. This is a number obtained by OR-ing together the following
values:
1 monochrome (Hercules)
4 16 color EGA/VGA/SVGA
8 256 color VGA/SVGA
16 32768 color SVGA
32 256 color plane mode (mode X)
For example:
make -DPLANES=12
will build a DJGPP library which only includes support for 16 and 256
color video modes.
To rebuild the Turbo C version of the library a copy of TASM is also
needed, as the library contains a significant amount of in-line assembly
code.
Compiling the test programs
===========================
The makefile in the test directory accepts the following arguments:
1) make build all DJGPP test programs
2) make turboc build all Turbo C test programs
3) make <prog>. build a single DJGPP test program
4) make <prog>.exe build a single Turbo C test program
See the accompanying document "tests.doc" on how to run the test programs.
Low-level video RAM access support
==================================
When 'GrSetMode' is called it finally ends up making a call to the mode
set routine of the graphics driver which knows about the capabilities of
the card, and how to put the card into the desired mode. (This is card
dependent -- that's why there are so many drivers.)
Having done this, the driver returns a status word to the library
which specifies the MEMORY ORGANIZATION of the selected graphics mode.
There are MUCH FEWER possible memory organizations than video drivers. The
currently supported memory organizations in LIBGRX are the following:
256 color VGA
16 color EGA/VGA/SVGA
32768 color SVGA
8514/A and S3 hardware accelerated video RAM access
The following two memory organizations are not supported yet, but stubs
have been included for them in the library:
monochrome (Hercules, CGA 640x200 mode, EGA, VGA)
VGA 256 color plane-oriented (Mode X, Y...)
The driver status word is used to set up some global variables
describing the layout of the video memory, the number of colors, etc.. The
library contains different low-level video RAM access routines for the
different video RAM organizations. These low-level video RAM access
routines are called indirectly via function pointers. These function
pointers are set up when a graphics primitive first attempts to use them.
This means that an attempt to draw anything before the first call to
'GrSetMode' will fail miserably as the library will has no idea about the
video access method to be used.
The library source files containing the memory mode specific functions
are named as follows:
p1*.c - monochrome (currently dummies only)
p4*.c - EGA/VGA 16 color modes
p8*.c - VGA 256 color modes
ph*.c - VGA 32768 color mode
px*.c - VGA 256 color mode X (currently dummies only)
pi*.c - 8514/A and S3 256 color mode
ps*.c - a few additional S3 routines where its programming
differs from the 8514/A
Each memory mode access group contains ten files (one function in each)
which do the following:
p?init.c - global data and possibly an init function
p?pixset.c - set a single pixel
p?pixrd.c - read a single pixel
p?pixrow.c - set a pixel row
p?pixcol.c - set a pixel column
p?pixblk.c - set a rectangular pixel block
p?bitblt.c - copy a rectangular pixel block
p?line.c - draw a line
p?char.c - draw a character
p?fillp.c - fill a pixel row with a pattern
The library does all mode-specific video RAM access through these nine
functions. There is a small amount of mode specific code related to
setup and color management in the files "setmode.c", "layout.c",
"context.c" and "colors.c", other than these the rest of the library
(drawing functions, etc..) is video RAM organization independent.
If the library was built to support only a single memory organization
then the calls to the appropriate low-level functions are hard-coded into
the code (via preprocessor macros in "libgrx.h"). Additionally, in 256 and
32768 color modes some trivial pixel manipulations (read and set a single
pixel) are expanded in-line.
If the library supports more than one video RAM model then this
in-line expansion is not done, and all low-level access functions are
called via pointers. There is a dispatch routine for every low-level
service (in the files "sw*.c"). The pointers initially point to these
dispatch routines. When a dispatch routine is first called it puts the
address of the appropriate (i.e. corresponding to the current video mode)
low-level access function into the pointer and then calls it. This way the
dispatch routine gets called only the first time a video RAM access
function is used. A call to 'GrSetMode' resets the pointers to point to
the dispatch routines.
NOTE: The Turbo C low-level video RAM access routines do not support
paging. (Actually, the 32 bit routines do not support it either because it
is handled transparently by the 386's page fault mechanism and the DOS
extender.) For this reason the Turbo C version has a resolution
limitation: 320x200 in 256 color mode and 800x600 in 16 color mode. For
the same reason there is no support for the 32768 color modes in the
Turbo C version of the library. HOWEVER: the 8514/A and S3 accelerators
do not need direct video RAM access and paging. For this reason the
full resolution of these boards (1024x768x256) can be supported even in the
Turbo C version of the library.