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' [...] [`,'] (Spaces in the above indicate where spaces are ignored in the syntax.) The 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 .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]