mirror of
https://github.com/netsurf-browser/netsurf
synced 2024-12-26 22:09:43 +03:00
191 lines
7.1 KiB
Plaintext
191 lines
7.1 KiB
Plaintext
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. |