Initial revision

[ssr] / StraySrc / Sculptrix / README

SCULPTRIX
~~~~~~~~~


There's some Real documentation for Sculptrix, so I'll just say some
words about the internals, and some historical ramblings.


Wy does the world need another 3D button module?  Quite honestly, it
doesn't.

I was preparing to release the first version of SDLS when I realised
that there was a complication.  Up until that point, we'd always used
Simon Huntingdon's Interface module for our 3D bits.  SDLS only needed
Interface for one component, the DLLMerge tool, but I wanted the world's
first view of a Straylight Wimp program to be positive, and I wanted a
sexy looking 3D interface.

The problem was that SDLS had extremely permissive licensing.  We
allowed SDLS to be included free of charge with any software, whether
free or proprietary.  And I didn't think Mr Huntingdon was going to like
that happening to his module.  I couldn't find the documentation for
Interface, and Simon didn't appear to be a comp.sys.acorn regular, so I
decided that the quickest way to resolve the problem was to write a 3D
border module of my own.

Some quick prototyping in BASIC (now lost forever) provided me with a
good way of drawing corners in a mode-independent way.  The border
plotting primitives were the first bits of Sculptrix 1.  I then wrote
the code to fit these together, a bit of validation string parsing, and
the module header, all in a fairly adhoc sort of way.  The result was
Sculptrix 1.00.  It took a couple of days to get this far.  I'd not paid
much attention to making the code tidy or readable.

Sculptrix isn't the name I originally chose for the module.  I'd seen 3D
boxes being called `sculpted' before, and I thought that sounded fairly
reasonable.  I originally came up with the name `Skulptor', which I
wasn't really happy with for two reasons; partly because it looked
slightly too `k00l', but mainly because it was really difficult to type
quickly.  For the curious, I intended the name `Sculptrix' as a fake
feminine form of `Sculptor'.

A major headache I was having at the time involved positioning group box
titles.  I knew that everyone else was having this problem too, but I'm
a bit perfectionist about my templates, and this problem vexed me
greatly.  I decided that adding group box borders as a Sculptrix
operation was an obvious solution.

Other changes followed.  After fourteen revisions, the Sculptrix source
code had stopped looking a mess and was approaching a disaster.  I
decided that something drastic had to be done.

There were two big sources of mess in the original Sculptrix:

  * The border drawing routines were horrible.  Manipulating several
    boxes, each using four registers, makes for some horrific ARM code.
    The group box drawing code was particularly nasty.

  * The validation string parsing was a total loss.  It was mostly adhoc
    stuff.  Dispatching to the border operations was done in the code,
    which became a royal pain.

I dealt with the first problem by using a simple `border description
language'.  By writing a pile of macros, I persuaded objasm to assemble
a simple bytecode language which would draw borders.  The language
called ARM routines to draw the sides of the border, but did all the
necessary arithmetic using the bytecodes, which I'd designed fairly
carefully to be able to do the jobs which needed to be done with minimum
of fuss.  This made the job of writing borders easier; it made the code
more readable; and it reduced the code size.  (Remarkably, Sculptrix 2
is smaller than Sculptrix 1.)

The border machine has a single register, a rectangle store, and a
(read-only) icon rectangle store.  It can load values from either
store, perform simple arithmetic (adding and subtracting immediate
constants) and write back to the rectangle store.  The machine can also
perform operations like selecting colours, finding the centre of an
icon, and calling another piece of border code as a subroutine.

The problems with validation string parsing were solved by introducing a
concept of a `border type', which is a bitfield identifying the basic
border shape and various optional flags to be applied to it.  Validation
string parsing was centralised, and made table driven; I took the
opportunity to rationalise the syntax at the same time.  The rest of the
code happily passes border type codes around.

Another major change with version 2 was the user configuration.  The
initial version didn't have any configuration at all.  A later
modification added some star-commands, which required understanding of
hex notation and a strong stomach.  It was all most unsatisfactory.  The
new version lost the star-commands, and provided a (binary)
configuration file which could be edited using a natty GUI application.
This made me feel much happier.


Setrix is the first Sapphire application in the source release.
Interested people should be able to learn a lot from its source code.
Of particular interest are:

  * The colour buttons in the dialogue box are all custom controls
    handled entirely by Sapphire.

  * The data transfer code, and how easy the ram transfer stuff is.
    (It still amazes me that a RAM save routine is often three lines of
    assembler, and that a RAM load is handled more-or-less entirely by
    Sapphire.)

I also like the way that the `load-from-file' routine used during Wimp
loading of a file is just as useful for loading the initial config file.


I'm rather proud of the job I made of Sculptrix in the end.  I hope you
agree that my time was well spent.
--
[mdw]