X-Git-Url: http://git.mutantstargoat.com/user/nuclear/?p=dosdemo;a=blobdiff_plain;f=README.md;h=b3a41a1e2e394608b01c718de18a05340b331d35;hp=102090e24e0ec3dc198f7e7bcb14f90990a5b17f;hb=HEAD;hpb=c1029b14c3fde9c98d524f17201364c695b6b117 diff --git a/README.md b/README.md index 102090e..6d34b63 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,49 @@ -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 run the `univbe` TSR first, or -the demo will fail to find a usable LFB video mode. +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). @@ -120,3 +152,89 @@ U-only pairable instructions: - 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.