[project @ 2004-05-31 19:56:38 by rjw]

Improved Tinct and documentation.

svn path=/import/netsurf/; revision=902

Docs/!tinct,fff

@@ -1,12 +1,5 @@
 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.
@@ -14,38 +7,35 @@ 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
+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. 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).
-
+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 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 (*):
+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 (must be 0)
-	[+28] *	Last bit used (must be 31)
+	[+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 &301680B5)
+	[+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
@@ -56,6 +46,14 @@ 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
 ¯¯¯¯¯¯¯¯¯¯¯¯¯
@@ -66,7 +64,9 @@ current OS clipping rectangle is used.
 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.
-
+ The only error returned by the SWIs is 0x71e (Unrecognised sprite data) that
+comes from supplying Tinct with a sprite that does not fit the required
+characteristics as specified earlier.
 
 Tinct_PlotAlpha (0x57240)
 ¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨
@@ -118,23 +118,77 @@ 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  Forcably read the screen base (only use if hardware scrolling)
+	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+ Reserved (must be 0)
+	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.