docs/README.DJ

   1                         Mesa 4.0 DOS/DJGPP Port v1.1
   2                         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4
   5
   6 Description:
   7 ~~~~~~~~~~~~
   8
   9 Well, guess what... this is the DOS port of Mesa 4.0.4, 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         BIG_OPT=1       crazy optimizations; not very useful, though...
  36                         default = no
  37         GLIDE           absolute path to Glide library; used with FX.
  38                         default = $(TOP)/include/glide3
  39         FX=1            build for 3dfx Glide3; use it if you have the Glide
  40                         SDK (designed for your platform), and, of course, a
  41                         3dfx card... Note that this disables compilation of
  42                         actual DMesa code, as Glide does all the stuff!
  43                         default = no
  44         HAVE_X86=1      optimize for i386.
  45                         default = no
  46         HAVE_MMX=1      MMX instructions; use only if you assembler/compiler
  47                         supports MMX instruction set; backwards compatibility
  48                         with older processors is still preserved.
  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 Evil King3 (Voodoo3 3000) w/ 16384 kB SDRAM
  69         DJGPP:          djdev 2.03 + gcc v3.1 + make v3.79.1
  70
  71
  72
  73 FAQ:
  74 ~~~~
  75
  76 1. Compilation
  77
  78    Q) I tried to run `make' and it exits because `gcc' complains it cannot find
  79       some stupid file.
  80    A) You need LFN support.
  81    A) When compiling for Glide (FX=1), pay attention to Glide path.
  82
  83 2. Dynamic modules
  84
  85    Q) What are you mumbling about dynamic modules?
  86    A) You must have the DXE2 package (available on SimTel.Net, courtesy of
  87       Andrew Zabolotny) installed in order to build the dynamic modules.
  88
  89    Q) I have DXE2, but I couln'd build the `dxe2gen.exe'.
  90    Q) I built `dxe2gen.exe', but it doesn't do the job right.
  91    A) There is a patched version on my web page.
  92
  93    Q) DXE2 modules give me headaches...
  94    A) The DXE2 modules are not compulsory. The static libraries are still built
  95       and you can use them in the old-fashioned, classic way. For example:
  96         gcc -o OUT.exe IN.c -lglut -lglu -lgl
  97
  98    Q) Okay, DXE2 modules are built. How can I use them?
  99    A) Usage of the dynamic modules requires three things:
 100         - include DMESADXE.H in one of the sources, so references inside
 101           dynamic modules will get resolved (or use `-include' directive).
 102         - link against import libraries (libI*.a) and LIBDL.A, which will do
 103           the dynamic linkage job for you
 104         - put the DXEs somewhere along the library path (LD_LIBRARY_PATH) or
 105           in the current directory
 106       For example:
 107         gcc -o OUT.exe -include dmesadxe.h IN.c -ligl -liglu -liglut -ldl
 108
 109    Q) The application dies with "Abort!" due to unresolved symbols.
 110    A) This is bad! Extract the unresolved symbol list from this module. For
 111       example:
 112         dxe2gen --show-unres gl.dxe > u
 113       Check DMESADXE.H; the symbols in `u' must either be present here or be
 114       exported from another module that has to be loaded before your faulting
 115       one. Then recompile.
 116
 117 3. Using Mesa for DJGPP
 118
 119    Q) Does this build work in Win9x?
 120    A) Yes.
 121
 122    Q) Does it work under NT (W2k, XP) core?
 123    A) Uh... probably not!
 124
 125    Q) I made a simple application and it does nothing. It exits right away. Not
 126       even a blank screen.
 127    A) The current version supports only RGB[A] modes, for it made no sense to
 128       me to endorse color-index (aka palette) modes.
 129    A) Single-buffered is not allowed at all. Until I can find a way to use
 130       *REAL* hardware acceleration, it won't get implemented.
 131    A) Another weird "feature" is that buffer width must be multiple of 4 (I'm a
 132       lazy programmer and I found that the easiest way to keep buffer handling
 133       at peak performance ;-).
 134
 135    Q) My demo doesn't display text. I know I used the glut font routines!
 136    A) Then you probably use GLUT as a DXE. Well, there is no direct access to
 137       variables due to the way DXE works. Read the documentation. The author of
 138       GLUT took this into account for _WIN32 DLL's only; I don't want to modify
 139       his headers. The only workaround is to link GLUT the old way :-(
 140
 141    Q) The DJGPP port of Mesa is so SLOOOW! The Win32 OpenGL performs so much
 142       better...
 143    A) Is that a question? If you have a Voodoo3/Banshee card, you're lucky. The
 144       Glide port is on my web page. If you haven't, sorry; everything is done
 145       in software. Suggestions?
 146
 147    Q) I have a super/mega/ultra monitor and all you can do is 60Hz? My eyes are
 148       leaking from the orbits...
 149    A) If you were compiling for Glide, see Glide info. If not, be aware that
 150       refresh rate control works only for VESA 3.0. The environment variable
 151       DMESA_REFRESH sets the default screen refresh. For example:
 152         set DMESA_REFRESH=75
 153
 154
 155
 156 libGLUT (the toolkit):
 157 ~~~~~~~~~~~~~~~~~~~~~~
 158
 159 Well, this "skeletal" GLUT implementation is not mine. Thanks should go to
 160 Bernhard Tschirren, Mark Kilgard, Brian Paul and probably others (or probably
 161 not ;-). I only changed it to be self-standing (Allegro-free). The keyboard,
 162 mouse and timer drivers were inspired from an old project of mine (D3Xl) and
 163 fixed with many Allegro "infusions"; I deeply thank to Shawn Hargreaves et co.
 164
 165 My keyboard driver used only scancodes, but since GLUT requires ASCII values
 166 for keys, I borrowed the translation tables (and maybe more) from Allegro.
 167 Ctrl-Alt-Del (plus Ctrl-Alt-End, for Windows users) will shut down the GLUT
 168 engine unconditionally: it will raise SIGINT, which in turn will call the
 169 destructors (let's hope), thus cleaning up your/my mess ;-) NB: since the
 170 DJGPP guys ensured signal handlers won't go beyond program's space (and since
 171 dynamic modules shall) the SIGINT can't be hooked (well, it can, but it is
 172 useless), therefore you must live with the 'Exiting due to signal SIGINT'
 173 message...
 174
 175 The mouse driver is far from complete (lack of positioning, drawing, etc),
 176 but is enough to make almost all the demos work.
 177
 178 The timer is pretty versatile for it supports multiple timers with different
 179 frequencies. It may not be the most accurate timer in the known universe, but
 180 I think it's OK. Take this example: you have timer A with a very high rate,
 181 and then you have timer B with very low rate compared to A; now, A ticks OK,
 182 but timer B will probably loose precision!
 183
 184 As an addition, stdout and stderr are redirected and dumped upon exit. This
 185 means that printf can be safely called during graphics, but all messages come
 186 in bulk! A bit of a hack, I know, but I think it's better than to miss them
 187 at all. "Borrowed" from RHIDE (Robert Hoehne) or SETEDIT (Salvador Eduardo
 188 Tropea)... I'm not sure.
 189
 190 Window creating defaults: 640x480x16 at (0,0), 8-bit stencil, 16-bit accum.
 191 However, the video mode is chosen in such a way that first window will fit.
 192
 193
 194
 195 History:
 196 ~~~~~~~~
 197
 198 v1.0    mar-2002        initial release
 199 v1.1    sep-2002        + added 3dfx Glide3 support
 200                         + added refresh rate control
 201                         + added fonts in glut
 202                         * lots of minor changes
 203
 204
 205
 206 Contact:
 207 ~~~~~~~~
 208
 209 Name:   Borca Daniel
 210 E-mail: dborca@yahoo.com
 211 WWW:    http://www.geocities.com/dborca/