1THIS FILE IS UNDER CONSTRUCTION!!!!! 2DON'T READ IT. IF YOU WANT TO SEE THE INTERNALS OF GRX 2.0 CONSULT THE 3SOURCE! 4 5 6 7 8 9Abstract 10======== 11 12This document describes contains information necessary for rebuilding 13the LIBGRX graphics library. Additionally, it describes some internal 14details of the library associated with way it accesses the video RAM. This 15info might be useful for adding support for new graphics adapter types. 16 17 18How to rebuild the library 19========================== 20 21The LIBGRX library is built using the Turbo C MAKE. (TC++ 1.01 22professional was used.) If an other MAKE has to be used it has to provide 23some method for generating response files from long command lines. The 24makefiles may have to be changed from the Turbo C MAKE response file 25syntax to the syntax of the new MAKE. Additionally, the Turbo C MAKE 26provides a C preprocessor-like conditional syntax. If the new MAKE utility 27does not support this, the desired option has to be hard-coded. 28 29The makefile in the base directory of the package (typically it is 30....djgpp\contrib\libgrx) can be invoked as follows: 31 32 1) make build DJGPP libraries, and the drivers 33 2) make turboc build Turbo C libraries 34 3) make test (1+) build DJGPP test programs 35 4) make turbotst (2+) build Turbo C test programs 36 5) make install copy .h and .a files into DJGPP dirs 37 6) make clean clean up after recompiling 38 39All graphics library sources are in the 'src' directory. The makefile 40in that directory can also be used to build a customized version of the 41library. Customized libraries (and the executable built using them) can be 42smaller, because they don't include support for all video RAM access 43methods. (see later) The makefile in the src directory can be used as 44follows: 45 46 make -DPLANES=<value> 47 -- or -- 48 make -DPLANES=<value> [-DMODEL=<memory model>] turboc 49 50The value of the PLANES macro determines the included video RAM access 51methods. This is a number obtained by OR-ing together the following 52values: 53 54 1 monochrome (Hercules) 55 4 16 color EGA/VGA/SVGA 56 8 256 color VGA/SVGA 57 16 32768 color SVGA 58 32 256 color plane mode (mode X) 59 60For example: 61 62 make -DPLANES=12 63 64will build a DJGPP library which only includes support for 16 and 256 65color video modes. 66 67To rebuild the Turbo C version of the library a copy of TASM is also 68needed, as the library contains a significant amount of in-line assembly 69code. 70 71 72Compiling the test programs 73=========================== 74 75The makefile in the test directory accepts the following arguments: 76 77 1) make build all DJGPP test programs 78 2) make turboc build all Turbo C test programs 79 3) make <prog>. build a single DJGPP test program 80 4) make <prog>.exe build a single Turbo C test program 81 82See the accompanying document "tests.doc" on how to run the test programs. 83 84 85Low-level video RAM access support 86================================== 87 88When 'GrSetMode' is called it finally ends up making a call to the mode 89set routine of the graphics driver which knows about the capabilities of 90the card, and how to put the card into the desired mode. (This is card 91dependent -- that's why there are so many drivers.) 92 93Having done this, the driver returns a status word to the library 94which specifies the MEMORY ORGANIZATION of the selected graphics mode. 95There are MUCH FEWER possible memory organizations than video drivers. The 96currently supported memory organizations in LIBGRX are the following: 97 98 256 color VGA 99 16 color EGA/VGA/SVGA 100 32768 color SVGA 101 8514/A and S3 hardware accelerated video RAM access 102 103The following two memory organizations are not supported yet, but stubs 104have been included for them in the library: 105 106 monochrome (Hercules, CGA 640x200 mode, EGA, VGA) 107 VGA 256 color plane-oriented (Mode X, Y...) 108 109The driver status word is used to set up some global variables 110describing the layout of the video memory, the number of colors, etc.. The 111library contains different low-level video RAM access routines for the 112different video RAM organizations. These low-level video RAM access 113routines are called indirectly via function pointers. These function 114pointers are set up when a graphics primitive first attempts to use them. 115This means that an attempt to draw anything before the first call to 116'GrSetMode' will fail miserably as the library will has no idea about the 117video access method to be used. 118 119The library source files containing the memory mode specific functions 120are named as follows: 121 122 p1*.c - monochrome (currently dummies only) 123 p4*.c - EGA/VGA 16 color modes 124 p8*.c - VGA 256 color modes 125 ph*.c - VGA 32768 color mode 126 px*.c - VGA 256 color mode X (currently dummies only) 127 pi*.c - 8514/A and S3 256 color mode 128 ps*.c - a few additional S3 routines where its programming 129 differs from the 8514/A 130 131Each memory mode access group contains ten files (one function in each) 132which do the following: 133 134 p?init.c - global data and possibly an init function 135 p?pixset.c - set a single pixel 136 p?pixrd.c - read a single pixel 137 p?pixrow.c - set a pixel row 138 p?pixcol.c - set a pixel column 139 p?pixblk.c - set a rectangular pixel block 140 p?bitblt.c - copy a rectangular pixel block 141 p?line.c - draw a line 142 p?char.c - draw a character 143 p?fillp.c - fill a pixel row with a pattern 144 145The library does all mode-specific video RAM access through these nine 146functions. There is a small amount of mode specific code related to 147setup and color management in the files "setmode.c", "layout.c", 148"context.c" and "colors.c", other than these the rest of the library 149(drawing functions, etc..) is video RAM organization independent. 150 151If the library was built to support only a single memory organization 152then the calls to the appropriate low-level functions are hard-coded into 153the code (via preprocessor macros in "libgrx.h"). Additionally, in 256 and 15432768 color modes some trivial pixel manipulations (read and set a single 155pixel) are expanded in-line. 156 157If the library supports more than one video RAM model then this 158in-line expansion is not done, and all low-level access functions are 159called via pointers. There is a dispatch routine for every low-level 160service (in the files "sw*.c"). The pointers initially point to these 161dispatch routines. When a dispatch routine is first called it puts the 162address of the appropriate (i.e. corresponding to the current video mode) 163low-level access function into the pointer and then calls it. This way the 164dispatch routine gets called only the first time a video RAM access 165function is used. A call to 'GrSetMode' resets the pointers to point to 166the dispatch routines. 167 168NOTE: The Turbo C low-level video RAM access routines do not support 169paging. (Actually, the 32 bit routines do not support it either because it 170is handled transparently by the 386's page fault mechanism and the DOS 171extender.) For this reason the Turbo C version has a resolution 172limitation: 320x200 in 256 color mode and 800x600 in 16 color mode. For 173the same reason there is no support for the 32768 color modes in the 174Turbo C version of the library. HOWEVER: the 8514/A and S3 accelerators 175do not need direct video RAM access and paging. For this reason the 176full resolution of these boards (1024x768x256) can be supported even in the 177Turbo C version of the library. 178 179 180 181 182 183 184 185 Abstract 186 187 This document describes the graphics driver format used for DJGPP and the 188 LIBGRX graphics library. It also gives hints for creating a driver for an 189 unsupported display adapter. 190 191 Introduction 192 193 The DJGPP graphics drivers do two things: 194 195 (1) Invoke the BIOS INT 10 routine for setting up the desired graphics mode. 196 Different boards support different resolutions and use different mode 197 numbers -- that's why different drivers are needed for different boards. 198 199 (2) Implement page mapping for video modes which use more than 64K of video 200 memory. This is again board dependent. 201 202 Old driver format 203 204 The following C declarations describe the header of an old format DJGPP 205 graphics driver. Of course, real drivers are coded in assembly. 206 207 typedef unsigned short u_short; 208 typedef unsigned char u_char; 209 210 struct old_driver_header { 211 u_short mode_set_routine_offset; 212 u_short paging_routine_offset; 213 u_short paging_mode_flag; /* 0 if no separate R/W, 1 if yes */ 214 u_short default_text_width; 215 u_short default_text_height; 216 u_short default_graphics_width; 217 u_short default_graphics_height; 218 }; 219 220 The mode set routine does the following: 221 222 ;-------------------------------------------------------------------------- 223 ; Entry: AX=mode selection 224 ; 0=80x25 text 225 ; 1=default text 226 ; 2=text CX cols by DX rows 227 ; 3=biggest text 228 ; 4=320x200 graphics 229 ; 5=default graphics 230 ; 6=graphics CX width by DX height 231 ; 7=biggest non-interlaced graphics 232 ; 8=biggest graphics 233 ; CX=width (in pixels or characters) (not always used -- depends on AX) 234 ; DX=height 235 ; 236 ; NOTE: This runs in real mode, but don't mess with the segment registers. 237 ; 238 ; Exit: CX=width (in pixels or characters) 239 240 241 242 243 244 ; DX=height 245 ;-------------------------------------------------------------------------- 246 247 The paging routine does the following: 248 249 ;-------------------------------------------------------------------------- 250 ; Entry: AH=read page 251 ; AL=write page 252 ; 253 ; NOTE: This runs in protected mode! Don't mess with the segment registers! 254 ; This code must be relocatable and may not reference any data! 255 ; 256 ; Exit: VGA configured. 257 ; AX,BX,CX,DX,SI,DI may be trashed 258 ;-------------------------------------------------------------------------- 259 260 The old style graphics driver structure remained unchanged for the first 16 261 color drivers developed for LIBGRX. The only difference is that the additional 262 15 bits in the third word of the header were given new meanings. (The 256 263 color DJGPP library only used one bit to encode the capability to map 264 different pages for reading and writing.) The values of these new bitfields 265 were assigned as to stay compatible with the existing 256 color drivers. (I.e. 266 the 0 value in every bitfield selects the 256 color VGA option.) The 267 definition of these bits (from "grdriver.h"): 268 269 #define GRD_NEW_DRIVER 0x0008 /* NEW FORMAT DRIVER IF THIS IS SET */ 270 271 #define GRD_PAGING_MASK 0x0007 /* mask for paging modes */ 272 #define GRD_NO_RW 0x0000 /* standard paging, no separate R/W */ 273 #define GRD_RW_64K 0x0001 /* two separate 64K R/W pages */ 274 /* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */ 275 /* THE FOLLOWING THREE OPTIONS ARE NOT SUPPORTED AT THIS TIME */ 276 #define GRD_RW_32K 0x0002 /* two separate 32Kb pages */ 277 #define GRD_MAP_128K 0x0003 /* 128Kb memory map -- some Tridents 278 can do it (1024x768x16 without 279 paging!!!) 280 #define GRD_MAP_EXTMEM 0x0004 /* Can be mapped extended, above 1M. 281 Some Tseng 4000-s can do it, NO 282 PAGING AT ALL!!!! */ 283 /* !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! */ 284 285 #define GRD_TYPE_MASK 0xf000 /* adapter type mask */ 286 #define GRD_VGA 0x0000 /* vga */ 287 #define GRD_EGA 0x1000 /* ega */ 288 #define GRD_HERC 0x2000 /* hercules */ 289 #define GRD_8514A 0x3000 /* 8514/A or compatible */ 290 #define GRD_S3 0x4000 /* S3 graphics accelerator */ 291 292 #define GRD_PLANE_MASK 0x0f00 /* bitplane number mask */ 293 #define GRD_8_PLANES 0x0000 /* 8 planes = 256 colors */ 294 #define GRD_4_PLANES 0x0100 /* 4 planes = 16 colors */ 295 #define GRD_1_PLANE 0x0200 /* 1 plane = 2 colors */ 296 #define GRD_16_PLANES 0x0300 /* VGA with 32K colors */ 297 #define GRD_8_X_PLANES 0x0400 /* VGA in mode X w/ 256 colors */ 298 299 300 301 302 303 #define GRD_MEM_MASK 0x00f0 /* memory size mask */ 304 #define GRD_64K 0x0010 /* 64K display memory */ 305 #define GRD_128K 0x0020 /* 128K display memory */ 306 #define GRD_256K 0x0030 /* 256K display memory */ 307 #define GRD_512K 0x0040 /* 512K display memory */ 308 #define GRD_1024K 0x0050 /* 1MB display memory */ 309 #define GRD_192K 0x0060 /* 192K -- some 640x480 EGA-s */ 310 #define GRD_M_NOTSPEC 0x0000 /* memory amount not specified */ 311 312 An old style driver has the 'GRD_NEW_DRIVER' bit cleared. It can work with 313 previous versions of GO32. Of course for 16 color support the application has 314 to be linked with the LIBGRX library instead of the original 256 color 315 library. 316 317 The following additional old format graphics drivers are supplied with the 318 LIBGRX graphics library: 319 320 EGA16.GRD 16 color EGA driver (640x350x16 max. resolution) 321 VGA16.GRD 16 color standard VGA driver (640x480x16 max. 322 resolution) 323 TSENG4KN.GRD same as DJGPP's Tseng ET 4000 256 color driver, but 324 with added support for the 100x40 text mode. (max: 325 1024x768x256) 326 TSENG416.GRD Tseng ET 4000 16 color driver. (max: 1024x768x16) 327 TRID89N.GRD Trident 8900 256 color driver. This driver has an 328 updated paging routine which seems to fix some 329 previous problems on boards with recent enough 330 chipsets. (max: 1024x768x256) 331 TRID8916.GRD: Trident 8900 16 color driver (max: 1024x768x16) 332 333 334 New driver format 335 336 The disadvantage of the old driver format is that the number of colors is not 337 programmable. The new driver format solves this problem and it also gives the 338 application program a way to query the driver for a list of the supported text 339 and graphics modes. For this the driver header was extended as follows: 340 341 struct new_driver_header { 342 u_short mode_set_routine_offset; 343 u_short paging_routine_offset; 344 u_short driver_mode_flag; /* flag word, see bits below */ 345 u_short default_text_width; 346 u_short default_text_height; 347 u_short default_graphics_width; 348 u_short default_graphics_height; 349 u_short default_color_number; /* NEW, may be set from environment */ 350 u_short init_routine_offset; /* NEW, call once after drvr loaded */ 351 u_short text_mode_table_offset; /* NEW, table of supported text modes */ 352 u_short graphics_mode_table_offset; /* NEW, table of supported graphics modes */ 353 }; 354 355 'text_mode_table_offset' points to a table with entries as follows: 356 357 358 359 360 361 struct text_mode_entry { 362 u_short columns; 363 u_short rows; 364 u_short number_of_colors; /* in text mode it is mainly here to make 365 GCC happy with the alignments */ 366 u_char BIOS_mode; /* BIOS mode number. Mode not available on 367 the current card if this field is 0xff. */ 368 u_char special; /* if non zero then the driver does some 369 special hacks to set it up (like 370 the 50 row mode on a standard VGA) */ 371 }; 372 373 The end of the table is marked by an all 0 entry. The table entries are sorted 374 by increasing size. The field 'graphics_mode_table_offset' points to a table 375 with entries as follows: 376 377 struct graphics_mode_entry { 378 u_short width; 379 u_short height; 380 u_short number_of_colors; 381 u_char BIOS_mode; /* BIOS mode number. Mode not available on 382 the current card if this field is 0xff. 383 (This may happen for example if the card 384 is not fully populated with RAM) */ 385 u_char special; /* if non zero then the driver does some 386 special hacks to set it up (like 387 setting up the 32768 color mode on 388 some ET4000 cards) */ 389 }; 390 391 The end of the table is marked by an all 0 entry. The table is sorted by 392 increasing color number and within the same color modes by increasing size. 393 394 If the driver is of the new type then it also supports an initialization 395 routine. This is called once after the driver is loaded. The initialization 396 routine can do one or more of the following: 397 398 (1) Check whether the video card is of the expected type 399 400 (2) Determine the amount of video memory on board. 401 402 (3) Determine which of the modes in the text and graphics mode tables are 403 actually available (due to video RAM and possibly DAC [32768 colors!!] 404 limitations) and mark the unavailable entries in the tables. 405 406 To use the new format drivers a recent version of GO32 (1.06, after the middle 407 of April 1992) has to be used. Such versions should recognize the "nc 408 <number>" option field in the GO32 environment variable which specifies the 409 default number of colors for the driver. 410 411 The following new format drivers have been included with the LIBGRX library 412 (new drivers have the ".GRN" extension): 413 414 STDEGA.GRN standard EGA 16 color driver 415 416 417 418 419 420 STDVGA.GRN standard VGA 16 and 256 color driver 421 ET4000.GRN Tseng ET 4000 16 256 and 32768 color driver 422 TR8900.GRN Trident 8900 16 and 256 color driver 423 ATIULTRA.GRN Driver for the ATI ULTRA board. This board actually 424 contains two graphics adapters: a 512 KByte SVGA board 425 and a 8514/A compatible accelerator. The driver was 426 programmed to use the VGA part for text, 16 color 427 graphics, and low resolution 256 color graphics modes 428 and the 8514/A part for high resolution 256 color 429 modes. This driver should work with any VGA+8514/A 430 (the 8514/A MUST have 1MB memory for 1024x768 431 resolution) combination as long as the ATI-specific 432 modes of the VGA part are not used. 433 STEALTH.GRN Driver for the Diamond Stealth S3 graphics accelerator 434 board. The driver was programmed to use VGA-style video RAM 435 access for text, 16 color graphics, and low resolution 256 436 color graphics modes and the S3 accelarator functions for 437 high resolution 256 color modes. Currently no 32768 color 438 modes are supported on S3 boards. This driver should work 439 with other S3-based boards which have a VESA BIOS. 440 441 442 Creating a driver for an unsupported board 443 444 You can only use EGA or VGA boards in 16 256 or 32768 color modes with the 445 graphics library. In the near future there will be support for Hercules boards 446 as well. SUPPORT IS NOT PLANNED FOR: BOARDS WITH ON-BOARD GRAPHICS PROCESSORS 447 (TIGA, 8514A, etc...) To create a driver for an unsupported EGA or VGA board 448 you will need the followings: 449 450 (1) An assembler (TASM or MASM), a linker (TLINK or LINK) and a utility to 451 convert .EXE files to the .COM format (EXE2BIN). See also the 'makefile' 452 in the 'drivers' sub-directory. 453 (2) A documentation of the board containing the supported BIOS mode numbers 454 and resolutions. 455 (3) If the driver needs to support modes which use a memory map bigger than 456 64K then you also need a piece of code which does page switching on your 457 board. (Any mode above 800x600 in 16 colors or 320x200 in 256 colors 458 DOES USE paging.) Possible sources: 459 - a working, tested 256 color original DJGPP driver (if you just 460 want to convert it to the new format). 461 - VGAKIT.ZIP (available from various archive sites, like wuarchive, 462 simtel, etc...) 463 - various books on the subject. 464 465 It is best to start with the source of a driver supporting similar resolutions 466 as your board. Use the proper format driver, i.e. if you want a new format 467 driver start with a new original, etc... Typically the driver sources are 468 relatively well commented. What you need to do is: 469 470 (1) possibly change the option word at the head of the driver to indicate 471 the number of colors (old format only), the amount of memory on board, 472 the memory mapping capabilities of the board. 473 (2) change the mode setting code to use the proper BIOS mode numbers. In the 474 475 476 477 478 479 old format drivers these are somewhat scattered throughout the code, in 480 the new format drivers you need to edit a few tables only. 481 (3) Replace the paging routine with the one suitable for your board. If your 482 driver supports 16 color resolutions beyond 800x600 then you have to 483 make sure that upon exit from the paging routine the graphics controller 484 port's (0x3ce) index register is reset to 8. (See the paging routine in 485 "TR8900.ASM".) If the paging mechanism does not use any register 486 accessed through the graphics controller port, then you don't need to 487 worry about this.