Intro
-----

'WOUM' is a collection of reusable GNU C and assembler code I've been working on over the past few months. The majority of the code is concerned with 3D graphics, but most files should operate stand alone. The name 'WOUM' is actually an acronym, Write Once Use Many. I could have used WORM (i.e. Write Once Read Many), but obviously decided that something with a an obvious icon would be too obvious. Or something like that.

This manual aims to provide full documentation of the code, in addition to the documentation that can be found in each header file. The root page for each code module gives a general overview, the header pages describe the function APIs and how to use them, and the code pages give implementation notes.

All code and binaries should be 26/32bit neutral. The code in this release has only been tested with under GCC 3.4.6 release 3, and operation under other compilers isn't guaranteed.

Once the filer has 'seen' !WOUM, the variables <Woum$Dir>, <Woum$Path>, and <WoumInclude$Path> will be set up ready for use. To include header files in your code use a directive such as:

#include "/WoumInclude:lib/foo.h"

Note that double-clicking !WOUM will open the directory Woum:lib, allowing you to see the code contained in it.

Build configurations
--------------------

The WOUM makefile (at Woum:lib.makefile) currently supports two configurations: The 'default' configuration, compiling to the libwoum library, and the 'armv3m' configuration, compiling to the libwoumv3m library. (For GCC) the 'default' configuration produces code for machines that support the ARMV3 architecture - i.e. RiscPC, A7000, etc. and above. The 'armv3m' configuration produces code that targets machines with the ARMV3M archictecture - i.e. anything that supports the SMULL and UMULL 64-bit multiply instructions (StrongARM RiscPC and above). Apart from the changes the C compiler automatically makes to use the 64bit multiply instructions, the only other code that currently uses it is the assembler fixed point math code in <fixmath>.

Running 'make' with no parameters will build both versions of the library. To build a specific version, either specify a/libwoum or a/libwoumv3m as the file for make to build.

If a program uses libwoumv3m and needs to check whether it's running on a compatible machine, the <sasm_getcapabilities()=>sasm.h> function can be used to check for the SASM_M flag.

GnarlPlot
---------

GnarlPlot currently only supports one build target, for ARMV3 (i.e. the GCC default). The GnarlPlot makefile is at Woum:lib.gp.makefile.

Example files and other stuff
-----------------------------

DTime, DTime_Src

  A small module to provide a millisecond timer. It relies on the HALTimer module (available at ). This module is only used for testing, and as such is using an unregistered SWI chunk. 

spantest3.c, mkst3

  A 3D spinning cube in Mode 28. It can be poked around a bit to produce various bits of debugging/profiling output, and left/right mouse buttons change the distance to the cube. Additionally, the middle mouse button will reset the timers to allow timings at particular distances to be taken. Chances are it'll run too fast on a fast computer. Shouldn't crash at all - if you manage to make it, let me know!

The mkst3 obey file can be used to compile a copy of the program.

spheretest.c, mkst4

  A 3D spinning sphere, in a 16 bit 640x480 mode. Left/right mouse buttons change the distance to the sphere, and the middle mouse button changes the detail level it is drawn at.

sss.c, mksss

  A 'simple span singlestepper', used while debugging the span code. You are unlikely to need it yourself.

ed.c, mked

  A very un-user-friendly program aiming to become a 3D model editor, but at the moment just displays premade models. Usage is:

ed [-dfm/-an8] infile [outfile]

Where -dfm denotes that the input file is in dfm format (As used by the 'Darkness Falls' Elite remake/clone thingy. Included are the dfm files from an early demo of the game). Alternatively, -an8 can be used to denote that the input files are in the anim8or format, as used by the 3D editor anim8or; see anim8or.com. If neither is given, the input format is one of my own devising, which is outlined in ed.c.

If outfile is specified then the input file will be rewritten as a file in my own format (whether it originated as one or not), and the program will exit straight away.

Otherwise, it will show the chosen file in 3D and allow you to use the arrow keys and page up/down to move round it. It'll complain if it can't find the file you want to load, but apart from that there isn't any error checking, so don't mess up the command line parameters! Currently it doesn't use screen banking, since early versions tended to crash and so errors were hard to see (You should be able to enable it by defining SCREENBANKING though). If you load a large model such as dfm.coriolis, you'll actually start inside it and so have to back up a bit in order to see the model. Also note that since dfms are meant to be textured, the colours the program uses when loading them are arbitrary. an8's should be OK, but the program relies on a depreciated colour field so only simple colour effects may show up.

The mked obey file can be used to compile a copy of the program. When running the program, ensure the current directory is set OK if you are using relative paths. The file 'ObeyFile' can be used to set the current directory to the directory the obey file is placed in.

License/copyright/etc.
----------------------

WOUM is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
WOUM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with WOUM.  If not, see <http://www.gnu.org/licenses/>.


Jeffrey Lee, 26/2/08
me@phlamethrower.co.uk
http://www.quote-egnufeb-quote-greaterthan-colon-hash-comma-underscore-at.info/
