diff options
Diffstat (limited to 'riscos/distribution/3rdParty/Tinct/!Help')
| -rw-r--r-- | riscos/distribution/3rdParty/Tinct/!Help | 304 |
1 files changed, 0 insertions, 304 deletions
diff --git a/riscos/distribution/3rdParty/Tinct/!Help b/riscos/distribution/3rdParty/Tinct/!Help deleted file mode 100644 index 2e27e354f..000000000 --- a/riscos/distribution/3rdParty/Tinct/!Help +++ /dev/null @@ -1,304 +0,0 @@ -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 |