-Unnamed Mindlapse DOS demo for Pentium 133
-------------------------------------------
-The demo requires VESA Bios Extensions (VBE) 2.0. If your graphics card doesn't
-support VBE 2.0 or greater, then make sure to load the `univbe` TSR first.
+Unnamed Mindlapse DOS demo for Pentium-era PCs
+----------------------------------------------
+The demo uses VBE 320x240 16bpp. Some VBE implementations do not expose
+double-scan video modes (240 lines), but can be made to work with a third-party
+VBE TSR like `univbe` or `s3vbe`. Linear framebuffer (VBE 2.0) support is
+recommended, but not necessary. The demo will fallback to VBE 1.2 banked modes
+if LFB modes are not available.
Source structure
----------------
- src/ cross-platform demo framework and miscellaneous utility code
- src/scr/ demo screens (parts) and effects support code
- src/dos/ DOS platform code
+ - src/glut/ GLUT platform code (windows/UNIX version)
- src/sdl/ SDL 1.x platform code (windows/UNIX version)
- libs/cgmath/ math library, header-file only
- libs/imago/ image loading library (includes libpng, zlib, libjpeg)
- libs/anim/ keyframe animation library
+Coding style conventions
+------------------------
+Very few style issues are mandated:
+
+ - All filenames should be lowercase unless convention says otherwise
+ (`Makefile`, `README`, etc).
+ - All filenames under `src/` and of any tools necessary to build from MS-DOS
+ will have to use maximum 8.3 characters.
+ - Source code should be C89-compliant. Any compiler-specific features beyond
+ that will have to be ifdefed.
+ - Use tabs for indentation, where each tab is equivalent to 4 spaces.
+
+Everything else is left to the discretion of each individual, but also if
+you're editing an existing file, try to match the style of the surrounding code.
+
+Some general style suggestions, which will not be enforced:
+
+ - Don't use overly long names, abbreviate wherever it makes sense.
+ - Don't cast the return value of malloc. `void*` are converted implicitly, and
+ the cast hides forgetting to include `stdlib.h`.
+ - Preferably use lowercase with underscores for everything.
+ - Preferably use the K&R brace style if possible.
+
+This section will be expanded as necessary.
+
Building on DOS with Watcom
---------------------------
-NOTE: Don't. Watcom produces significantly worse code than GCC, and at the
-moment watcom-compiled version of the demo crashes on 3D scenes for some reason
-which I need to investigate at some point. Suspect either inline assembly with
-missing "modify" part, or more likely some FPU optimization which fucks up the
-clipper.
-
Make sure you have Watcom or OpenWatcom installed, and the appropriate env-vars
set (the watcom installer automatically adds them to autoexec.bat by default).
- adc, sbb
- shr, sar, shl, sal with immediate
- ror, rol, rcr, rcl with immediate=1
+
+Notes about DJGPP & CWSDPMI
+---------------------------
+Can't use the `hlt` instruction for waiting for interrupts, because we're
+running in ring3 by default. I surrounded all the `hlt` instructions with a
+`USE_HLT` conditional, which is undefined when building with DJGPP.
+
+It's possible to arrange for our code to run on ring0 by changing the DPMI
+provider from `cwsdpmi.exe` to `cwsdpr0.exe` by running:
+`stubedit demo.exe dpmi=cwsdpr0.exe`, but I haven't tested under win9x to see if
+it still works if we do that.
+
+Our fucking segments don't start at 0 ... to access arbitrary parts of physical
+memory we need to call `__djgpp_nearptr_enable()` and use the following macros I
+defined in `cdpmi.h`:
+
+ #define virt_to_phys(v) ((v) + __djgpp_base_address)
+ #define phys_to_virt(p) ((p) - __djgpp_base_address)
+
+Notes about moving code to/from a DOS computer
+----------------------------------------------
+The easiest way to move code back and forth to a DOS computer, is to connect it
+to the local network. For this you need a DOS packet driver for your NIC, which
+thankfully most NIC vendors seem to provide, and a number of useful network
+utilities which come with their own TCP/IP stack (mTCP and WATTCP). The
+following are recommended:
+
+ - mTCP: http://www.brutman.com/mTCP
+ - WATTCP: http://www.watt-32.net
+ - ssh2dos: http://sshdos.sourceforge.net
+ - rsync: http://www.2net.co.uk/rsync.html
+
+Here's an example batch file I'm using to set up the network:
+
+ @echo off
+ c:\net\rtspkt\rtspkt 0x61
+ set MTCPCFG=c:\net\mtcp\mtcp.cfg
+ set WATT_ROOT=c:\net\watt
+ set WATTCP.CFG=c:\net\watt\bin
+ set ETC=c:\net\watt\bin
+ set PATH=%PATH%;c:\net\mtcp;c:\net\watt\bin
+
+The rtspkt program is the packet driver for my realtek NIC, and I'm instructing
+it to use interrupt 61h. The rest are environment variables needed by mTCP and
+WATTCP. If you run out of environment space you might need to increase it with
+`SHELL=C:\DOS\COMMAND.COM /e:1024 /p` in `config.sys`, or just put all binaries
+in a single place instead of adding multiple directories to the `PATH`.
+
+### mTCP configuration
+The `mtcp.cfg` file configures the mTCP TCP/IP stack. Go through the file, which
+comes with mTCP, and make any necessary changes. For instance I've set
+`packetint 0x61` to match the packet driver interrupt, and I'm using static IP
+assignments, so I've set it up like this:
+
+ ipaddr 192.168.0.21
+ netmask 255.255.0.0
+ gateway 192.168.1.1
+ nameserver 1.1.1.1
+
+### WATTCP configuration
+The `wattcp.cfg` file is in the wattcp bin directory, and includes similar
+configuration options:
+
+ my_ip = 192.168.0.21
+ hostname = "retrop1"
+ netmask = 255.255.0.0
+ nameserver = 1.1.1.1
+ gateway = 192.168.1.1
+ domain.suffix = localdomain
+ pkt.vector = 0x61
+ hosts = $(ETC)\hosts
+
+### Server-side configuration
+The `pull.bat` file in the demo repo uses rsync to get the source code from the
+git repo on my main GNU/Linux computer. To avoid having to type passwords all
+the time, I've configures rsyncd to allow access to the demo directory in the
+`/etc/rsyncd.conf` file:
+
+ [dosdemo]
+ path = /home/nuclear/code/demoscene/dosdemo
+ comment = DOS demo project
+
+Since the DOS rsync utility is unfortunately read-only, the `push.bat` relies on
+ssh2dos instead, which does require a password. The sshd on the server might
+need to be configured to allow older encryption algorithms, depending on your
+current setup.
projects / dosdemo / blobdiff