Initial revision

[ssr] / StraySrc / Sculptrix / NewVersion

Sculptrix 2.00 changes


The Sculptrix 2.00 project provided an opportunity to radically redesign
and restructure the Sculptrix module, including some much-needed new
functionality.  The original version wasn't particularly well-written, and
the 15 revisions made to it since left us with a program which was extremely
hard to maintain.

The new version is split into ten source files, each with fairly clearly
defined responsibilities:

bbox.s -- calculates bounding boxes for Sculptrix icons.  Implements the
    Sculptrix_BoundingBox SWI.

border.s -- interprets the border description bytecode commands to draw
    borders.

colours.s -- handles icon colour reading and changing, including icons with
    anti-aliased fonts (reads colour from the validation string).  Used
    during slabbing.

config.s -- handles reading and changing of border styles.

plot.s -- handles plotting of borders given a border type word, by passing
    a border definition to border.s.

redraw.s -- high-level interface to redrawing borders.  Implements the
    various Sculptrix SWIs concerning screen redraw, by calling plot.s.

rule.s -- implements the low-level drawing primitives for 3D borders.

sculptrix.s -- defines the module header and other external interfaces to
    the operating system.

slab.s -- handles slabbing of icons.

utils.s -- contains various utility functions which don't fit anywhere else.

vString.s -- parses validation strings, and places the information into a
    border type word, which is used by other routines.



The two main advances in the design of Sculptrix are border type words,
and border definitions.


Border type words encode all the information read from a validation string,
except for the text field for group box icons, which is read into a temporary
buffer.  This allows support for the old style Sculptrix validation commands
to be local to the validation string parser -- the rest of the code only sees
border type words.  The compatibility support can be removed easily, to make
upgrading templates easy: when support is removed, only icons with new-style
validation string commands have visible borders.  This was used to upgrade
the Glass templates.


A border definition describes how to draw a border.  Drawing borders in
pure ARM assembler proved to be cumbersome, and prone to error.
Sculptrix 2.00 solves the problem by defining a new bytecode language for
drawing borders.  The language can be thought of as a `machine code' for a
border-drawing processor.

This fictional `processor' has one accumulator and two `rectangles' (the
`icon' and `current' rectangles).  A rectangle consists of four integers
labelled x0, y0, x1 and y1.  These values cannot be modified directly; they
must be loaded into the accumulator, updated, and stored back.  The icon
rectangle is read-only.

There are instructions for transferring data between the rectangles and the
accumulator, for setting the current colours, and for plotting `rules' and
group titles.  A rule is generally a horizontal or vertical line (although
in one special case, it's actually a rectangle), which may be mitred at the
end.  The position of the rule is determined by the rule-plotting routine
(written in ARM code), relative to the current rectangle position.  A group
title is plotted using Wimp_PlotIcon using the current rectangle position
and an icon flags word.

The instruction set is descibed in the source file border.s.

Note that there is no noticeable performance degredation as a result of using
this technique.  I've tested the relative performance on some complex
dialogue boxes with the cache off, with no significant differences.  It's
possible that the new code is faster, since the interpreter probably fits
in cache.  This means that Sculptrix is probably still the fastest 3D border
renderer for RISC OS.


An advance has been made in the support of text+sprite icons, originally
included in version 1.04.  Sculptrix now supports all positions of the text
within the bounding box, and will call Wimp_ForceRedraw, when necessary, to
redraw the text.  In older versions of Sculptrix, `xs'-type icons could not
be shaded, since the Wimp did not remove all of the correct anti-aliasing
pixels.  The new version will detect whether the icon text is being anti-
aliased (whether by its icon flags or due to the Wimp$Font setting under
later versions of the Wimp) and if so force a redraw of the text to ensure
that the background is correctly rendered.


The validation string syntax for 3D borders has been redesigned.  The old
syntax is still supported for compatibility, although its use is now
deprecated.

The new syntax is:

  `xb' <type> [<flag>...] [`,'<text>]

(Spaces in the above indicate where spaces are ignored in the syntax.)

The <type> is one of the following letters:

  a == action button (standard plinth, may be slabbed)
  d == default button (surrounded by highlighted `moat', may be slabbed)
  i == information display (pressed in area)
  p == partition bar (pressed in, same colour as group boxes)
  r == raised-up ridge
  c == pressed-in channel
  o == `offset' pressed-in area, used for sliders
  w == writable border, with solid line around it
  g == group box border

The flags are as follows:

  f == use group-box colours for the border
  i == invert the icon

There are many ways of duplicating effects: for example `xbif' means the
same as `xbp', and `xbc' means the same as `xbri'.  The idea is that the
letters indicate the purpose of the icon, rather than its visual style.
The mapping of letters onto visual effects may change in future, to match
changes in user interface styles.

Note that borders are inverted when the type codes are in uppercase: this
is for the benefit of the Sculptrix module, though -- you should use the
`i' flag to invert icons.

Group box borders may or may not contain text.  The presence of text is
determined by the presence of the comma in the validation string command:
`xbg' means no text, while `xbg,' mrans that the text is an empty string.
If there is no text, no title icon is drawn, so the effect given is a ridge
or channel in the correct style.  This use of borders for grouping is
occasionally found in CC applications, and may be of use.


The new version of Sculptrix has a different user interface for
configuration.  Colour and style information can be stored in a (binary)
file, and loaded via the *Sculptrix_LoadConfig command, for example during
boot-up.  These files can be built using the Setrix application (provided)
which allows easy configuration using a dialogue box.  Setrix currently
needs a 64K wimpslot, since it is statically linked to Sapphire, although
once a dynamically linkable Sapphire is available, this will be reduced.
A wimpslot of 64K is fairly acceptable, though, considering that it supports
the full data transfer protocol, the Choices system for storing
configuration, and full error handling.  It is arguable that not all of these
features are necessary in such an application, though.

When it starts up, Setrix will try to find a `Config' file in Choices:Setrix,
or in its application directory.  If it finds the file, it loads it, and
sets the Sculptrix configuration from it.  If the file is not present,
it reads the configuration from the Sculptrix module.  Thus, RiscPC owners
are recommended to store a configuration file in Choices:Setrix, and
place an obey file of the form

  RMLoad <xyz$Dir>.Sculptrix
  Sculptrix_LoadConfig Choices:Setrix.Config

in their Choices:Boot.PreDesk directory.

The file format for Sculptrix configuration files is very simple, and I
can't be bothered to explain it here.  It's all in the Setrix source,
anyway.


Enjoy

  [mdw]