docs/README.DJ

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