docs/README.DJ

   1                         Mesa 6.3 DOS/DJGPP Port v1.7
   2                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4
   5
   6 Description:
   7 ~~~~~~~~~~~~
   8
   9 Well, guess what... this is the DOS port of Mesa 6.3, for DJGPP fans... Whoa!
  10 The driver has its origins in ddsample.c, written by Brian Paul and found by me
  11 in Mesa 3.4.2.
  12
  13
  14
  15 Legal:
  16 ~~~~~~
  17
  18 Mesa copyright applies, provided this package is used within Mesa. For anything
  19 else, see GPL.
  20
  21
  22
  23 Installation:
  24 ~~~~~~~~~~~~~
  25
  26 Unzip and type:
  27
  28         make -f Makefile.DJ [OPTIONS...]
  29
  30 Available options:
  31
  32      Environment variables:
  33         CPU             optimize for the given processor.
  34                         default = pentium
  35         GLU=[mesa|sgi]  specify GLU directory; can be `sgi' (requires GNU/C++)
  36                         or `mesa'.
  37                         default = mesa
  38         GLIDE           path to Glide3 SDK; used with FX.
  39                         default = $(TOP)/glide3
  40         FX=1            build for 3dfx Glide3. Note that this disables
  41                         compilation of most DMesa code and requires fxMesa.
  42                         As a consequence, you'll need the DJGPP Glide3
  43                         library to build any application.
  44                         default = no
  45         X86=1           optimize for x86 (if possible, use MMX, SSE, 3DNow).
  46                         default = no
  47
  48      Targets:
  49         all:            build everything
  50         libgl:          build GL
  51         libglu:         build GLU
  52         libglut:        build GLUT
  53         clean:          remove object files
  54         realclean:      remove all generated files
  55
  56
  57
  58 Tested on:
  59         CPU:            AMD Athlon XP 1800+
  60         Mainboard:      GA-7VTXE w/ 512 MB DDRAM
  61         Video card:     Voodoo5 6000 AGP w/ 128 MB SDRAM
  62         DJGPP:          djdev 2.04 + gcc v3.4.3 + make v3.80
  63         OS:             DOS and Win98SE
  64
  65
  66
  67 FAQ:
  68 ~~~~
  69
  70 1. Compilation
  71
  72    Q) `make' barfs and exits because it cannot find some stupid file.
  73    A) You need LFN support.
  74    A) When compiling for Glide (FX=1), pay attention to Glide path.
  75
  76    Q) Libraries built OK, but linker complains about `vsnprintf' every time I
  77       compile some demo.
  78    A) Upgrade to DJGPP 2.04.
  79    A) Add `vsnprintf.c' to the CORE_SOURCES in `src/Makefile.DJ' (untested!).
  80    A) Patch `src/mesa/main/imports.c' with the following line:
  81         #define vsnprintf(buf, max, fmt, arg) vsprintf(buf, fmt, arg)
  82       This hack should be safe in 90% of the cases, but if anything goes wrong,
  83       don't come back to me crying.
  84
  85    Q) `make' complains about DXE3 or something, yet it builds the libraries.
  86    A) DXE3 refers to the DJGPP dynamic modules. You'll need either the latest
  87       DJGPP distro, or download the separate package from my web page. Read the
  88       DXE3 documentation on how to use them.
  89    A) When compiling for Glide (FX=1), make sure `glide3x.dxe' can be found in
  90       LD_LIBRARY_PATH (or top `lib' directory).
  91
  92 2. Using Mesa for DJGPP
  93
  94    Q) Every test I tried crashes badly.
  95    A) If you have compiled with SSE and you're running under plain DOS, you
  96       have to disable SSE at run-time. See environment variables below.
  97
  98    Q) DMesa is so SLOOOW! The Win32 OpenGL performs so much better...
  99    A) Is that a question? If you have a 3dfx Voodoo (any model), you're
 100       lucky (check http://sourceforge.net/projects/glide for the DJGPP port).
 101       If you haven't, sorry; everything is done in software. Suggestions?
 102
 103    Q) I tried to set refresh rate w/ DMesa, but without success.
 104    A) Refresh rate control works only for VESA 3.0 and the 3dfx driver (in
 105       which case FX_GLIDE_REFRESH will be overwritten if it is defined and
 106       is not 0).
 107
 108    Q) I made a simple application and it does nothing. It exits right away. Not
 109       even a blank screen.
 110    A) Pure software drivers (VESA/VGA/NUL) support only double-buffered modes.
 111    A) Another weird "feature" is that buffer width must be multiple of 8 (I'm a
 112       lazy programmer and I found that the easiest way to keep buffer handling
 113       at peak performance ;-).
 114
 115    Q) I'm getting a "bad font!" fatal error.
 116    A) Always use GLUT_STROKE_* and GLUT_BITMAP_* constants when dealing with
 117       GLUT fonts. If you're using `glut.dxe', then make sure GLUT_STROKE_* and
 118       GLUT_BITMAP_* are mapped to integer constants, not to the actual font
 119       address (same mechanism used for Win32 _DLL).
 120
 121    Q) What is NUL driver good for, if I don't get any output at all?
 122    A) For debugging. The NUL driver is very much like OSMesa. Everything is
 123       done just the same as VESA/VGA drivers, only it doesn't touch your video
 124       hardware. You can query the actual buffer by issuing:
 125         DMesaGetIntegerv(DMESA_GET_BUFFER_ADDR, &buffer);
 126       and dump it to a file.
 127
 128    Q) How do I query for a list of available video modes to choose as a visual?
 129    A) This is an ugly hack, for which I'm sure I'll burn in hell.
 130       First, query for a list of modes:
 131         n = DMesaGetIntegerv(DMESA_GET_VIDEO_MODES, NULL);
 132       If `n' is strictly positive, you allocate an array of pointers to a given
 133       struct (which is guaranteed to be extended only - not changed in future):
 134         struct {
 135                 int xres, yres;
 136                 int bpp;
 137         } **l = malloc(n * sizeof(void *));
 138       Now pass the newly allocated buffer to fill in:
 139         DMesaGetIntegerv(DMESA_GET_VIDEO_MODES, (GLint *)l);
 140       And collect the info:
 141         for (i = 0; i < n; i++) {
 142             printf("%dx%d:%d\n", l[i]->xres, l[i]->yres, l[i]->bpp);
 143         }
 144
 145    Q) The GLUT is incomplete.
 146    A) See below.
 147
 148
 149
 150 libGLUT (the toolkit):
 151 ~~~~~~~~~~~~~~~~~~~~~~
 152
 153 Well, this "skeletal" GLUT implementation was taken from AllegGL project and
 154 heavily changed. Thanks should go to Bernhard Tschirren, Mark Kilgard, Brian
 155 Paul and probably others (or probably not ;-). GLUT functionality will be
 156 extended only on an "as needed" basis.
 157
 158 GLUT talks to hardware via PC_HW package which was put together from various
 159 pieces I wrote long time ago. It consists from the keyboard, mouse and timer
 160 drivers.
 161
 162 My keyboard driver used only scancodes; as GLUT requires ASCII values for keys,
 163 I borrowed the translation tables (and maybe more) from Allegro -- many thanks
 164 to Shawn Hargreaves et co. Ctrl-Alt-Del (plus Ctrl-Alt-End, for Windows users)
 165 will shut down the GLUT engine unconditionally: it will raise SIGINT, which in
 166 turn will (hopefully) call the destructors, thus cleaning up your/my mess ;-)
 167 NB: since the DJGPP guys ensured signal handlers won't go beyond program's
 168 space (and since dynamic modules shall) the SIGINT can't be hooked (well, it
 169 can, but it is useless), therefore you must live with the 'Exiting due to
 170 signal SIGINT' message...
 171
 172 The mouse driver is far from complete (lack of drawing, etc), but is enough to
 173 make almost all the demos work. Supports the CuteMouse WheelAPI.
 174
 175 The timer is pretty versatile for it supports multiple timers with different
 176 frequencies. While not being the most accurate timer in the known universe, I
 177 think it's OK. Take this example: you have timer A with a very high rate, and
 178 then you have timer B with very low rate compared to A; now, A ticks OK, but
 179 timer B will probably loose precision!
 180
 181 As an addition, stdout and stderr are redirected and dumped upon exit. This
 182 means that `printf' can be safely called during graphics. A bit of a hack, I
 183 know, because all messages come in bulk, but I think it's better than nothing.
 184 "Borrowed" from LIBRHUTI (Robert Hoehne).
 185
 186 Window creating defaults: (0, 0, 300, 300), 16bpp. However, the video mode is
 187 chosen in such a way that first window will fit. If you need high resolution
 188 with small windows, set initial position far to the right (or way down); then
 189 you can move them back to any position right before the main loop.
 190
 191
 192
 193 Environment variables:
 194 ~~~~~~~~~~~~~~~~~~~~~~
 195         DMESA_NULDRV            - (any value) force NUL driver
 196         GLUT_FPS                - print frames/second statistics to stderr
 197         MESA_NO_SSE             - (any value) safe option under pure DOS
 198         DMESA_GLUT_REFRESH      - set vertical screen refresh rate (VESA3)
 199         DMESA_GLUT_BPP          - set default bits per pixel (VGA needs 8)
 200         DMESA_GLUT_ALPHA        - set default alpha bits (8)
 201         DMESA_GLUT_DEPTH        - set default depth bits (16)
 202         DMESA_GLUT_STENCIL      - set default stencil bits (8)
 203         DMESA_GLUT_ACCUM        - set default accum bits (16)
 204
 205
 206
 207 History:
 208 ~~~~~~~~
 209
 210 v1.0 (mar-2002)
 211         initial release
 212
 213 v1.1 (sep-2002)
 214         + added 3dfx Glide3 support
 215         + added refresh rate control
 216         + added fonts in GLUT
 217         * lots of minor changes
 218
 219 v1.2 (nov-2002)
 220         * synced w/ Mesa-4.1
 221         - removed dmesadxe.h
 222
 223 v1.3 (mar-2003)
 224         + enabled OpenGL 1.4 support
 225         + added MMX clear/blit routines
 226         + enabled SGI's GLU compilation
 227         + added samples makefile
 228         + added new GLUT functions
 229         + added color-index modes
 230         + added Matrox Millennium MGA2064W driver
 231         + added 8bit FakeColor (thanks to Neil Funk)
 232         + added VGA support (to keep Ben Decker happy)
 233         ! fixed some compilation errors (reported by Chan Kar Heng)
 234         * optimized driver for faster callback access... yeah, right :)
 235         * overhauled virtual buffer and internal video drivers
 236         * better fxMesa integration
 237         * revamped GLUT
 238         * switched to DXE3
 239
 240 v1.4 (dec-2003)
 241         + enabled GLUT fonts with DXE
 242         + truly added multi-window support in GLUT (for Adrian Woodward)
 243         * accomodated makefiles with the new sourcetree
 244         * fixed some ALPHA issues
 245         * minor changes to PC_HW/timer interface
 246         x hacked and slashed the 3dfx driver (w/ help from Hiroshi Morii)
 247
 248 v1.5 (jan-2004)
 249         + added interface to query available "visuals" (GLFW - Marcus Geelnard)
 250         + added GLUT timer callback
 251         - removed Matrox Millennium MGA2064W driver
 252         x more changes to the 3dfx driver
 253
 254 v1.6 (aug-2004)
 255         + implemented NUL driver
 256         + added DMesaGetProcAddress and glutGetProcAddress
 257         * reorganized fxMesa wrapper to handle multiple contexts
 258         ! fixed a horrible bug in VGA initialization routine
 259         ! fixed partial clears
 260
 261 v1.7 (???-2005)
 262         + enabled OpenGL 2.0 support
 263         + added support for sw texture compression
 264         + added FreeGLUT specific functions
 265         * no more GLX sources in DOS GLUT
 266         * made GLUT timer callbacks less accurate but safer
 267
 268
 269
 270 Contact:
 271 ~~~~~~~~
 272
 273 Name:   Daniel Borca
 274 E-mail: dborca@users.sourceforge.net
 275 WWW:    http://www.geocities.com/dborca/