docs/README.DJ

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