workbench/libs/mesa/docs/README.DJ

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