| 1 | Sculptrix 2.00 changes |
| 2 | |
| 3 | |
| 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 |
| 8 | hard to maintain. |
| 9 | |
| 10 | The new version is split into ten source files, each with fairly clearly |
| 11 | defined responsibilities: |
| 12 | |
| 13 | bbox.s -- calculates bounding boxes for Sculptrix icons. Implements the |
| 14 | Sculptrix_BoundingBox SWI. |
| 15 | |
| 16 | border.s -- interprets the border description bytecode commands to draw |
| 17 | borders. |
| 18 | |
| 19 | colours.s -- handles icon colour reading and changing, including icons with |
| 20 | anti-aliased fonts (reads colour from the validation string). Used |
| 21 | during slabbing. |
| 22 | |
| 23 | config.s -- handles reading and changing of border styles. |
| 24 | |
| 25 | plot.s -- handles plotting of borders given a border type word, by passing |
| 26 | a border definition to border.s. |
| 27 | |
| 28 | redraw.s -- high-level interface to redrawing borders. Implements the |
| 29 | various Sculptrix SWIs concerning screen redraw, by calling plot.s. |
| 30 | |
| 31 | rule.s -- implements the low-level drawing primitives for 3D borders. |
| 32 | |
| 33 | sculptrix.s -- defines the module header and other external interfaces to |
| 34 | the operating system. |
| 35 | |
| 36 | slab.s -- handles slabbing of icons. |
| 37 | |
| 38 | utils.s -- contains various utility functions which don't fit anywhere else. |
| 39 | |
| 40 | vString.s -- parses validation strings, and places the information into a |
| 41 | border type word, which is used by other routines. |
| 42 | |
| 43 | |
| 44 | |
| 45 | The two main advances in the design of Sculptrix are border type words, |
| 46 | and border definitions. |
| 47 | |
| 48 | |
| 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 |
| 56 | the Glass templates. |
| 57 | |
| 58 | |
| 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. |
| 64 | |
| 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. |
| 70 | |
| 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. |
| 79 | |
| 80 | The instruction set is descibed in the source file border.s. |
| 81 | |
| 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 |
| 87 | renderer for RISC OS. |
| 88 | |
| 89 | |
| 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. |
| 99 | |
| 100 | |
| 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 |
| 103 | deprecated. |
| 104 | |
| 105 | The new syntax is: |
| 106 | |
| 107 | `xb' <type> [<flag>...] [`,'<text>] |
| 108 | |
| 109 | (Spaces in the above indicate where spaces are ignored in the syntax.) |
| 110 | |
| 111 | The <type> is one of the following letters: |
| 112 | |
| 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) |
| 117 | r == raised-up ridge |
| 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 |
| 122 | |
| 123 | The flags are as follows: |
| 124 | |
| 125 | f == use group-box colours for the border |
| 126 | i == invert the icon |
| 127 | |
| 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. |
| 133 | |
| 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. |
| 137 | |
| 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. |
| 144 | |
| 145 | |
| 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. |
| 157 | |
| 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 |
| 164 | |
| 165 | RMLoad <xyz$Dir>.Sculptrix |
| 166 | Sculptrix_LoadConfig Choices:Setrix.Config |
| 167 | |
| 168 | in their Choices:Boot.PreDesk directory. |
| 169 | |
| 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, |
| 172 | anyway. |
| 173 | |
| 174 | |
| 175 | Enjoy |
| 176 | |
| 177 | [mdw] |