summaryrefslogtreecommitdiff
path: root/Docs/!tinct,fff
blob: 9826919dc08962e8f59b96bb342adb50455f6338 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
Tinct
=====
This module provides the necessary functionality to display alpha-blended
sprites both scaled and otherwise. It also provides functions for dithering
and performing bi-linear filtering to improve their appearance.


Technical information
ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
To ensure future compatibility, this module does not patch the OS in any way
and works in a totally legal way. It also does not write to itself in any
way, so is suitable for running from ROM.
 Redirection to sprites is supported, although due to the overheads involved
with caching the colour translation tables it is not recommended that this is
done frequently. There are some exceptions to this, however, as redirecting to
a 16bpp or 32bpp mode sprite does not require any translation tables, and
redirecting to a sprite that has the same mode and palette as the previous
destination that Tinct was used for causes a minimum overhead as the
translation tables are checked and cached values are used if possible.

Format of a sprite with 8-bit alpha channel
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
The sprite format used by Tinct differs from those used by RISC OS Select,
and whilst facilities are supplied to convert sprites into the required format,
no facilities are provided to manipulate them.
 All sprites used by Tinct must be 32bpp, and cannot have a standard RISC OS
mask specified. The basic format of the sprite is shown below, with the
restrictions to the standard sprite format marked with an asterisk (*):

	[+0]	Offset to next sprite
	[+4]	Sprite name, up to 12 characters with trailing zeroes
	[+16]	Width in words - 1
	[+20]	Height in scan lines - 1
	[+24] 	First bit used
	[+28] 	Last bit used
	[+32]	Offset to sprite image
	[+36] *	Offset to sprite image (no mask allowed)
	[+40] *	Sprite type (must be 0x301680B5)

Whereas for normal sprites the sprite image would be a series of colour words
of the format RrGgBb00, alpha-blended sprites use the empty byte to specify
the alpha value, ie RrGgBbAa.
 The alpha values represent the blending level on a linear scale where 0x00
represents that the source pixel is totally transparent and 0xff that it is
totally opaque. It should be noted that as a standard 32bpp sprite (eg as
created with !Paint) will have the alpha channel set to 0x00 by default no
output will be visible when plotting as an alpha-blended sprite.

Error handling
¨¨¨¨¨¨¨¨¨¨¨¨¨¨
If an incorrect sprite is attempted to be used, Tinct currently always returns
error number 0x700 (SBadSpriteFile) rather than the specific cause of the
problem (eg. BadDPI, BadMSFlags or BadPixelDepth) as OS_SpriteOp would do.
There are several technical reasons for this behaviour, and future versions of
Tinct may return different error numbers.


SWIs provided
ŻŻŻŻŻŻŻŻŻŻŻŻŻ
Tinct provides four SWIs to plot sprites and one to convert sprites to their
32bpp equivalent. All values supplied to Tinct must be in OS units, and the
current OS clipping rectangle is used.
 The sprite pointers provided are equivalent to calling OS_SpriteOp with
bit 9 of the reason code set. To plot a sprite by name, the sprite should
first be found by using OS_SpriteOp with reason code 0x18 and using the
returned sprite address.

Tinct_PlotAlpha (0x57240)
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Plots an alpha-blended sprite at the specified coordinates.

->	R2	Sprite pointer
	R3	X coordinate
	R4	Y coordinate
	R7	Flag word


Tinct_PlotScaledAlpha (0x57241)
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Plots a scaled alpha-blended sprite at the specified coordinates.

->	R2	Sprite pointer
	R3	X coordinate
	R4	Y coordinate
	R5	Scaled sprite width
	R6	Scaled sprite height
	R7	Flag word


Tinct_Plot (0x57242)
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Plots a sprite at the specified coordinates with a constant 0xff value for
the alpha channel, ie without a mask.

->	R2	Sprite pointer
	R3	X coordinate
	R4	Y coordinate
	R7	Flag word


Tinct_PlotScaled (0x57243)
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Plots a scaled sprite at the specified coordinates with a constant 0xff value
for the alpha channel, ie without a mask.

->	R2	Sprite pointer
	R3	X coordinate
	R4	Y coordinate
	R5	Scaled sprite width
	R6	Scaled sprite height
	R7	Flag word


Tinct_ConvertSprite (0x57244)
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Converts a paletted sprite into its 32bpp equivalent. Sufficient memory must
have previously been allocated for the sprite (44 + width * height * 4).
 As sprites with 16bpp or 32bpp do not have palettes, conversion cannot be
performed on these variants. All sprites must be supplied with a full palette, 
eg 8bpp must have 256 palette entries.

->	R2	Source sprite pointer
	R3	Destination sprite pointer


Tinct_AvailableFeatures (0x57245)
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Returns the features available to the caller by specifying bits in the flag
word. The features available are unique for each mode, although the current
version of Tinct supports the same subset of features for all modes.

->	R0	Feature to test for, or 0 for all features
<-	R0	Features available



Flag word
ŻŻŻŻŻŻŻŻŻ
All the SWIs provided by Tinct for plotting use a common flag word to
describe the manner in which the plot is performed. Each bit controls a
particular characteristic of the plotting:

	0  Forcibly read the screen base (only use if hardware scrolling)
	1  Use bi-linear filtering when scaling sprites
	2  Dither colours in 16bpp and below
	3  Invert dither pattern
	4  Horizontally fill the current graphics window with the sprite
	5  Vertically fill the current graphics window with the sprite
	6+ Reserved (must be 0)

If a bit is set in the flag word that cannot be honoured by the current
version of Tinct then it is ignored. Tinct_AvailableFeatures can be used
to test in advance what flags will be honoured.

Bilinear filtering
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Although bi-linear filtering is only relevant during scaled plotting, this
situation occurs when the EigFactors of the mode are not equal. As such, an
application should always set their preferred flags to ensure consistency.

Sprite filling
¨¨¨¨¨¨¨¨¨¨¨¨¨¨
If filling is specified, then the supplied co-ordinate is the offset of the
pattern relative to (0, 0) used for the fill. For example, a 64x64 sprite that
is plotted with bits 4 and 5 set and a position of (32, 16) would fill the
current graphics window with multiple copies of the image stating with the
first image plotted at (-32, -48).


Contact details
ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
If you would like to report a problem relating to Tinct, provide feedback, or
request a licence for a commercial product, please use the details below:

Address: 5 Queens Close, East Markham, Newark, Nottinghamshire, NG22 0QY. UK
E-mail: info@tinct.net
Website: www.tinct.net


Copyright and licence details
ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
Tinct is İ copyright Richard Wilson, 2004.

Distribution and usage
¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
Unrestricted use of Tinct is hereby granted for any non-commercial product. Any
use as part of a commercial product requires written consent from the author.
No charge may be made relating to the distribution of this software, and this
file should be included in all copies of the software.
 Modified versions of this program may not be distributed without the authors
consent, nor may modified versions of the source code or relating files.