4 The Sculptrix 2.00 project provided an opportunity to radically redesign
5 and restructure the Sculptrix module, including some much-needed new
6 functionality. The original version wasn't particularly well-written, and
7 the 15 revisions made to it since left us with a program which was extremely
10 The new version is split into ten source files, each with fairly clearly
11 defined responsibilities:
13 bbox.s -- calculates bounding boxes for Sculptrix icons. Implements the
14 Sculptrix_BoundingBox SWI.
16 border.s -- interprets the border description bytecode commands to draw
19 colours.s -- handles icon colour reading and changing, including icons with
20 anti-aliased fonts (reads colour from the validation string). Used
23 config.s -- handles reading and changing of border styles.
25 plot.s -- handles plotting of borders given a border type word, by passing
26 a border definition to border.s.
28 redraw.s -- high-level interface to redrawing borders. Implements the
29 various Sculptrix SWIs concerning screen redraw, by calling plot.s.
31 rule.s -- implements the low-level drawing primitives for 3D borders.
33 sculptrix.s -- defines the module header and other external interfaces to
36 slab.s -- handles slabbing of icons.
38 utils.s -- contains various utility functions which don't fit anywhere else.
40 vString.s -- parses validation strings, and places the information into a
41 border type word, which is used by other routines.
45 The two main advances in the design of Sculptrix are border type words,
46 and border definitions.
49 Border type words encode all the information read from a validation string,
50 except for the text field for group box icons, which is read into a temporary
51 buffer. This allows support for the old style Sculptrix validation commands
52 to be local to the validation string parser -- the rest of the code only sees
53 border type words. The compatibility support can be removed easily, to make
54 upgrading templates easy: when support is removed, only icons with new-style
55 validation string commands have visible borders. This was used to upgrade
59 A border definition describes how to draw a border. Drawing borders in
60 pure ARM assembler proved to be cumbersome, and prone to error.
61 Sculptrix 2.00 solves the problem by defining a new bytecode language for
62 drawing borders. The language can be thought of as a `machine code' for a
63 border-drawing processor.
65 This fictional `processor' has one accumulator and two `rectangles' (the
66 `icon' and `current' rectangles). A rectangle consists of four integers
67 labelled x0, y0, x1 and y1. These values cannot be modified directly; they
68 must be loaded into the accumulator, updated, and stored back. The icon
69 rectangle is read-only.
71 There are instructions for transferring data between the rectangles and the
72 accumulator, for setting the current colours, and for plotting `rules' and
73 group titles. A rule is generally a horizontal or vertical line (although
74 in one special case, it's actually a rectangle), which may be mitred at the
75 end. The position of the rule is determined by the rule-plotting routine
76 (written in ARM code), relative to the current rectangle position. A group
77 title is plotted using Wimp_PlotIcon using the current rectangle position
78 and an icon flags word.
80 The instruction set is descibed in the source file border.s.
82 Note that there is no noticeable performance degredation as a result of using
83 this technique. I've tested the relative performance on some complex
84 dialogue boxes with the cache off, with no significant differences. It's
85 possible that the new code is faster, since the interpreter probably fits
86 in cache. This means that Sculptrix is probably still the fastest 3D border
90 An advance has been made in the support of text+sprite icons, originally
91 included in version 1.04. Sculptrix now supports all positions of the text
92 within the bounding box, and will call Wimp_ForceRedraw, when necessary, to
93 redraw the text. In older versions of Sculptrix, `xs'-type icons could not
94 be shaded, since the Wimp did not remove all of the correct anti-aliasing
95 pixels. The new version will detect whether the icon text is being anti-
96 aliased (whether by its icon flags or due to the Wimp$Font setting under
97 later versions of the Wimp) and if so force a redraw of the text to ensure
98 that the background is correctly rendered.
101 The validation string syntax for 3D borders has been redesigned. The old
102 syntax is still supported for compatibility, although its use is now
107 `xb' <type> [<flag>...] [`,'<text>]
109 (Spaces in the above indicate where spaces are ignored in the syntax.)
111 The <type> is one of the following letters:
113 a == action button (standard plinth, may be slabbed)
114 d == default button (surrounded by highlighted `moat', may be slabbed)
115 i == information display (pressed in area)
116 p == partition bar (pressed in, same colour as group boxes)
118 c == pressed-in channel
119 o == `offset' pressed-in area, used for sliders
120 w == writable border, with solid line around it
121 g == group box border
123 The flags are as follows:
125 f == use group-box colours for the border
128 There are many ways of duplicating effects: for example `xbif' means the
129 same as `xbp', and `xbc' means the same as `xbri'. The idea is that the
130 letters indicate the purpose of the icon, rather than its visual style.
131 The mapping of letters onto visual effects may change in future, to match
132 changes in user interface styles.
134 Note that borders are inverted when the type codes are in uppercase: this
135 is for the benefit of the Sculptrix module, though -- you should use the
136 `i' flag to invert icons.
138 Group box borders may or may not contain text. The presence of text is
139 determined by the presence of the comma in the validation string command:
140 `xbg' means no text, while `xbg,' mrans that the text is an empty string.
141 If there is no text, no title icon is drawn, so the effect given is a ridge
142 or channel in the correct style. This use of borders for grouping is
143 occasionally found in CC applications, and may be of use.
146 The new version of Sculptrix has a different user interface for
147 configuration. Colour and style information can be stored in a (binary)
148 file, and loaded via the *Sculptrix_LoadConfig command, for example during
149 boot-up. These files can be built using the Setrix application (provided)
150 which allows easy configuration using a dialogue box. Setrix currently
151 needs a 64K wimpslot, since it is statically linked to Sapphire, although
152 once a dynamically linkable Sapphire is available, this will be reduced.
153 A wimpslot of 64K is fairly acceptable, though, considering that it supports
154 the full data transfer protocol, the Choices system for storing
155 configuration, and full error handling. It is arguable that not all of these
156 features are necessary in such an application, though.
158 When it starts up, Setrix will try to find a `Config' file in Choices:Setrix,
159 or in its application directory. If it finds the file, it loads it, and
160 sets the Sculptrix configuration from it. If the file is not present,
161 it reads the configuration from the Sculptrix module. Thus, RiscPC owners
162 are recommended to store a configuration file in Choices:Setrix, and
163 place an obey file of the form
165 RMLoad <xyz$Dir>.Sculptrix
166 Sculptrix_LoadConfig Choices:Setrix.Config
168 in their Choices:Boot.PreDesk directory.
170 The file format for Sculptrix configuration files is very simple, and I
171 can't be bothered to explain it here. It's all in the Setrix source,
~mdw / ssr / blob