2ee739cc |
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] |