docs/README.DJ

   1                         Mesa 5.0.1 DOS/DJGPP Port v1.3
   2                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4
   5
   6 Description:
   7 ~~~~~~~~~~~~
   8
   9 Well, guess what... this is the DOS port of Mesa 5.0.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 = k6
  35         GLU=[src|si]    specify GLU directory; can be `src' (src-glu = Mesa)
  36                         or `si' (si-glu = SGI's GLU -- requires GNU/C++).
  37                         default = src
  38         GLIDE           path to Glide3 SDK include files; used with FX.
  39                         default = $(TOP)/include/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         MATROX=1        build for Matrox Millennium I (MGA2064W) cards.
  46                         This is experimental and not intensively tested.
  47                         default = no
  48         HAVE_X86=1      optimize for i386.
  49                         default = no
  50         HAVE_MMX=1      allow MMX specializations, provided your assembler
  51                         supports MMX instruction set. However, the true CPU
  52                         capabilities are checked at run-time to avoid crashes.
  53                         default = no
  54         HAVE_SSE=1      (see HAVE_MMX)
  55                         default = no
  56         HAVE_3DNOW=1    (see HAVE_MMX)
  57                         default = no
  58
  59      Targets:
  60         all:            build everything
  61         libgl:          build GL
  62         libglu:         build GLU
  63         libglut:        build GLUT
  64         clean:          remove object files
  65         realclean:      remove all generated files
  66
  67
  68
  69 Tested on:
  70         CPU:            K6-2 (CXT) @500(412.5) MHz
  71         Mainboard:      ViA Apollo VP2/97 w/ 128 MB SDRAM
  72         Video card:     PowerColor EvilKing3 (Voodoo3 3000 PCI) w/ 16 MB SDRAM
  73         DJGPP:          djdev 2.04 + gcc v3.2.2 + make v3.79.1
  74         OS:             DOS and Win9x
  75
  76
  77
  78 FAQ:
  79 ~~~~
  80
  81 1. Compilation
  82
  83    Q) I tried to run `make' and it exits because `gcc' complains it cannot find
  84       some stupid file.
  85    A) You need LFN support.
  86    A) When compiling for Glide (FX=1), pay attention to Glide path.
  87
  88    Q) Libraries built OK, but linker complains about `vsnprintf' every time I
  89       compile some demo.
  90    A) Upgrade to DJGPP 2.04.
  91    A) Add `vsnprintf.c' to the CORE_SOURCES in `src/Makefile.DJ' (untested!).
  92    A) The following hack should be safe in 90% of the cases, but if anything
  93       goes wrong, don't come back to me crying. Anyway, patch `src/imports.c'
  94       with the following line:
  95         #define vsnprintf(buf, max, fmt, arg) vsprintf(buf, fmt, arg)
  96
  97    Q) `make' complains about DXE3 or something, yet it builds the libraries.
  98    A) DXE3 refers to the DJGPP dynamic modules. You'll need either the latest
  99       DJGPP distro, or download the separate package from my web page. Read the
 100       DXE3 documentation on how to use them. Hint: build your export object
 101       file; then link it with your application. For example:
 102         dxe3res -o dxe3tbl.c gl.dxe glu.dxe glut.dxe
 103         gcc -o dxe3tbl.o -c dxe3tbl.c
 104         gcc -o OUT.exe dxe3tbl.o IN.c -liglut -liglu -ligl -ldl
 105
 106 2. Using Mesa for DJGPP
 107
 108    Q) DMesa is so SLOOOW! The Win32 OpenGL performs so much better...
 109    A) Is that a question? If you have a Voodoo3/Banshee card, you're lucky (the
 110       Glide port is on my web page). If you have a Matrox Millennium I card,
 111       you just MIGHT be lucky... If you haven't, sorry; everything is done in
 112       software. Suggestions?
 113
 114    Q) I tried to set refresh rate w/ DMesa, but without success.
 115    A) Refresh rate control works only for VESA 3.0. If you were compiling for
 116       Glide, see Glide info. If not, sorry!
 117
 118    Q) I made a simple application and it does nothing. It exits right away. Not
 119       even a blank screen.
 120    A) The pure software drivers (VESA/VGA) support only double-buffered modes.
 121    A) Another weird "feature" is that buffer width must be multiple of 8 (I'm a
 122       lazy programmer and I found that the easiest way to keep buffer handling
 123       at peak performance ;-).
 124
 125    Q) My demo doesn't display text. I know I used the GLUT font routines!
 126    A) Then you probably use GLUT as a DXE. Well, there is no direct access to
 127       variables due to the way DXE works. Read the documentation. The author of
 128       GLUT took this into account for _WIN32 DLL's only; I don't want to modify
 129       his headers. The only workaround is to link GLUT the old way :-(
 130
 131    Q) The GLUT is incomplete.
 132    A) See below.
 133
 134
 135
 136 libGLUT (the toolkit):
 137 ~~~~~~~~~~~~~~~~~~~~~~
 138
 139 Well, this "skeletal" GLUT implementation was taken from AllegGL project and
 140 heavily changed. Thanks should go to Bernhard Tschirren, Mark Kilgard, Brian
 141 Paul and probably others (or probably not ;-). GLUT functionality will be
 142 extended only on an "as needed" basis.
 143
 144 GLUT talks to hardware via PC_HW package which was put together from various
 145 pieces I wrote long time ago. It consists from the keyboard, mouse and timer
 146 drivers.
 147
 148 My keyboard driver used only scancodes; as GLUT requires ASCII values for keys,
 149 I borrowed the translation tables (and maybe more) from Allegro -- many thanks
 150 to Shawn Hargreaves et co. Ctrl-Alt-Del (plus Ctrl-Alt-End, for Windows users)
 151 will shut down the GLUT engine unconditionally: it will raise SIGINT, which in
 152 turn will (hopefully) call the destructors, thus cleaning up your/my mess ;-)
 153 NB: since the DJGPP guys ensured signal handlers won't go beyond program's
 154 space (and since dynamic modules shall) the SIGINT can't be hooked (well, it
 155 can, but it is useless), therefore you must live with the 'Exiting due to
 156 signal SIGINT' message...
 157
 158 The mouse driver is far from complete (lack of drawing, etc), but is enough to
 159 make almost all the demos work. Supports the CuteMouse WheelAPI.
 160
 161 The timer is pretty versatile for it supports multiple timers with different
 162 frequencies. While not being the most accurate timer in the known universe, I
 163 think it's OK. Take this example: you have timer A with a very high rate, and
 164 then you have timer B with very low rate compared to A; now, A ticks OK, but
 165 timer B will probably loose precision!
 166
 167 As an addition, stdout and stderr are redirected and dumped upon exit. This
 168 means that `printf' can be safely called during graphics. A bit of a hack, I
 169 know, because all messages come in bulk, but I think it's better than nothing.
 170 "Borrowed" from LIBRHUTI (Robert Hoehne).
 171
 172 Window creating defaults: 300x300x16 at (0,0), 16-bit depth, 16-bit accum,
 173 8-bit stencil. However, the video mode is chosen in such a way that first
 174 window will fit. If you need high resolution with small windows, set initial
 175 position far to the right (or way down); then you can move them back to any
 176 position right before the main loop.
 177
 178 The following environment variables can customize GLUT behaviour:
 179         DMESA_GLUT_REFRESH      - set vertical screen refresh rate (VESA3)
 180         DMESA_GLUT_BPP          - set default bits per pixel (VGA needs 8)
 181         GLUT_FPS                - print frames/second statistics to stderr
 182
 183
 184
 185 History:
 186 ~~~~~~~~
 187
 188 v1.0 (mar-2002)
 189         initial release
 190
 191 v1.1 (sep-2002)
 192         + added 3dfx Glide3 support
 193         + added refresh rate control
 194         + added fonts in GLUT
 195         * lots of minor changes
 196
 197 v1.2 (nov-2002)
 198         * synced w/ Mesa-4.1
 199         - removed dmesadxe.h
 200
 201 v1.3 (mar-2003)
 202         + enabled OpenGL 1.4 support
 203         + added MMX clear/blit routines
 204         + enabled SGI's GLU compilation
 205         + added samples makefile
 206         + added new GLUT functions
 207         + added color-index modes
 208         + added Matrox Millennium MGA2064W driver
 209         + added 8bit FakeColor (thanks to Neil Funk)
 210         + added VGA support (to keep Ben Decker happy)
 211         ! fixed some compilation errors (reported by Chan Kar Heng)
 212         * optimized driver for faster callback access... yeah, right :)
 213         * overhauled virtual buffer and internal video drivers
 214         * better fxMesa integration
 215         * revamped GLUT
 216         * switched to DXE3
 217
 218
 219
 220 Contact:
 221 ~~~~~~~~
 222
 223 Name:   Borca Daniel
 224 E-mail: dborca@yahoo.com
 225 WWW:    http://www.geocities.com/dborca/