diff options
Diffstat (limited to 'frontends/riscos/distribution/3rdParty/Tinct/!Help')
| -rw-r--r-- | frontends/riscos/distribution/3rdParty/Tinct/!Help | 304 |
1 files changed, 304 insertions, 0 deletions
diff --git a/frontends/riscos/distribution/3rdParty/Tinct/!Help b/frontends/riscos/distribution/3rdParty/Tinct/!Help new file mode 100644 index 000000000..2e27e354f --- /dev/null +++ b/frontends/riscos/distribution/3rdParty/Tinct/!Help @@ -0,0 +1,304 @@ +Tinct +===== +This module provides the necessary functionality to display alpha-blended +sprites both scaled and otherwise. It also provides functions for dithering, +error diffusion 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 more descriptive errors depending on the cause. + + +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 + + +Tinct_Compress (0x57246) +¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ +Compresses an image using a fast algorithm. Sufficient memory must have been +previously allocated for the maximum possible compressed size. This value is +equal to 28 + (width * height * 4) * 33 / 32. + +-> R0 Source sprite pointer + R2 Output data buffer + R3 Output bytes available + R7 Flag word +<- R0 Size of compressed data + + +Tinct_Decompress (0x57247) +¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ +Decompresses an image previously compressed. Sufficient memory must have been +previously allocated for the decompressed data (44 + width * height * 4) where +width and height are available at +0 and +4 of the compressed data respectively. + +-> R0 Input data buffer + R2 Output data buffer + R7 Flag word (currently 0) +<- R0 Size of decompressed data + + +Flag word (plotting) +ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ +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 Perform error diffusion if bit 2 clear, invert dither pattern if set + 4 Horizontally fill the current graphics window with the sprite + 5 Vertically fill the current graphics window with the sprite + 6 Forcibly read the palette (only use if changing palette outside of + the WIMP) + 7 Use OS_SpriteOp to perform final plotting (see note) + 8+ Reserved (must be 0) if bit 7 is clear, background colour to + blend the alpha channel to otherwise + +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. + +Bi-linear 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. The +case of XEig * 2 = YEig (rectangular pixel modes) for even height sprites is a +special case and has optimised code implemented. + There is an upper limit to the size of sprite that can be bi-linear filtered. +The checks that are currently made are: + + scaled_width / sprite_width < 256 + scaled_height / sprite_height < 256 + scaled_width * max(sprite_height, scaled_height) < 32,768 + + It should be noted that as bi-linear filtering is performed as a pre-filter, +it carries a sizable overhead. However, as all scaling calculations are +performed during this filter, tiled plotting (bits 4 and 5) are affected by +a smaller margin (in certain cases a speed gain can be achieved). + As bi-linear filtering is performed using a pre-filter, it can be used in +association with OS_SpriteOp rendering. + +Error diffusion and dithering +¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ +If both error diffusion and dithering are enabled then the image is plotted +using only dithering, but with the dither pattern inverted. This enables an +application to provide the user with what appears to be a higher quality image +by redrawing every frame with the flag toggled. + There is a significant speed difference between dithering and error diffusion, +and Tinct does not support error diffusion in all colour depths. If error +diffusion is requested, but cannot be performed by Tinct then dithering with +an inverted pattern is used (as if bits 2 and 3 were set). + There is an upper limit to the size of sprite that Tinct can perform error +diffusion on. This is currently set to a display width of 2047 pixels wide with +an unlimited height. Any attempt to use a higher resolution will result in +dithered rendering with an inverted pattern (ie bits 2 and 3 set). + As error diffusion and dithering are implemented during the plot cycle, it is +not possible to use them in association with OS_SpriteOp rendering. However, +the bits should be set as future versions of Tinct may respect them for users +of RISC OS 3.1 where true colour sprites are not supported. + +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). + The caller should not concern itself with the size of the image being tiled +as small images are internally optimised where possible to maximise the +plotting speed. + +Rendering using OS_SpriteOp +¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ +It can be useful to use Tinct to perform the rendering to using OS_SpriteOp. +There are two general situations where this may be useful: + + 1) To output to a printer driver + 2) To allow hardware acceleraton (such as a ViewFinder card) + +By using Tinct rather than a direct OS_SpriteOp call, it allows the caller to +retain certain features Tinct provides (such as sprite filling and a limited +version of the standard alpha blending) and allows the caller to have a common +plotting interface. + When using this feature for alpha-blended sprites, the background colour +specified in the top 24-bits of the flag word is used for blending with any +pixels that are not transparent. This requires that Tinct requires a second +copy of the sprite in memory to modify which may present a significant overhead +in some situations. Plotting opaquely does not have any such overheads. + Using OS_SpriteOp rendering does not currently work on RISC OS 3.1 or earlier +due to the lack of support for true colour sprites. Future versions of Tinct +may remove this restriction. + + +Flag word (compression) +ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ +The flag word used by Tinct_Compress can be used to improve the compression +ratio by performing pre-filtering on the data. The flags below relate only to +compression and should not be passed to Tinct_Decompress. + + 0 Image is opaque, remove the alpha channel prior to compression + +All unspecified bits are reserved for future expansion and as such should be +set to 0. + +Compressed data format +¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨¨ +Certain aspects of the compressed data format are guaranteed to remain constant, +so may be used by applications. + + +0 Sprite width + +4 Sprite height + +8 Sprite name (12 chars) + +20 Compression flags + +24 Number of bytes of data following + +The method of compression is not guaranteed to remain constant over future +revisions of Tinct, but subsequent versions will decompress data compressed +with previous versions. + + +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 +copyright information 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.
\ No newline at end of file |