You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
304 lines
12 KiB
304 lines
12 KiB
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. |