From 26670e2e8ad013592f9171077c3fdf94afd90094 Mon Sep 17 00:00:00 2001 From: Richard Wilson Date: Mon, 15 Mar 2004 21:46:02 +0000 Subject: [project @ 2004-03-15 21:46:02 by rjw] Complete Tinct documentation. svn path=/import/netsurf/; revision=625 --- Docs/!tinct,fff | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 Docs/!tinct,fff (limited to 'Docs') diff --git a/Docs/!tinct,fff b/Docs/!tinct,fff new file mode 100644 index 000000000..1b1703d4d --- /dev/null +++ b/Docs/!tinct,fff @@ -0,0 +1,140 @@ +Tinct +===== +The ability to plot alpha-blended sprites is only provided by certain +versions of RISC OS provided by RISC OS Ltd (ie RISC OS Select), and +currently not by the latest versions provided by Castle (ie RISC OS 5) + There is currently no separate module available from RISC OS Ltd, nor a +version of Select that will function on an Iyonix. As such, users of machines +that will not run RISC OS 4 (and thus Select) cannot display images with +variable transparency (eg PNGs). + 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 compatibilty, 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. There are some exceptions to this, however, as output to a 32bpp mode +does not cause the tables to be re-calculated, and redirecting to a sprite +that has the same characteristics as the current mode and palette has a +minimal overhead. + Tinct comes in two different variants - one that is slightly faster and +only suitable for memory architectures that support LDRH and STRH (denoted by +a '_h' filename suffix), and one that is suitable for all machines (denoted +by a '_b' filename suffix). + + +Format of a sprite with 8-bit alpha channel +ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ +The sprite format used by Tinct differs from those used by RISC OS Select, +and no facilities to manipulate or create the required format is provided. + All sprites used by Tinct must be 32bpp, and cannot have a mask. + 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 (must be 0) + [+28] * Last bit used (must be 31) + [+32] Offset to sprite image + [+36] * Offset to sprite image (no mask allowed) + [+40] * Sprite type (must be &301680B5) + +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. + + +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 +¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ +Converts a paletted sprite into its 32bpp equivalent. Sufficient memory must +have previously been allocated for the sprite (44 + width * height * 4). + +-> R2 Source sprite pointer + R3 Destination sprite pointer + + +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 Forcably 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+ Reserved (must be 0) + +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. \ No newline at end of file -- cgit v1.2.3