BlendTable
==========

The BlendTable module is new to RISC OS 4.31. It supplies facilities for
merging paletted colours at arbitrary ratios. This is required for
SpriteExtend to provide support for translucent sprite rendering.

BlendTable_GenerateTable
=> R0 = flags :
          b0   source sprite is a pointer to a sprite, not a pointer to a name
          b1   destination sprite is a pointer to a sprite, not a pointer to
               a name
          b2   lock table after creation
        others reserved, must be 0
   R1 = source mode, or pointer to source sprite area
   R2 = 0, or pointer to source sprite/sprite name
   R3 = destination mode, or pointer to destination sprite area
   R4 = 0, or pointer to destination sprite/sprite name
   R5 = translucency factor (0-255)
        0 for opaque sprites
        255 for transparent sprites
        that is, increasing values reduce the opacity of source (or, in
        converse terms, increase the translucency of the source)
   R6 = pointer to buffer for table, or 0 to return size required (may
        be omitted if locking area)
<= R0 = number of colours in source
   R1 = number of colours in destination
   R2 = size of buffer required (if R6 = 0 on entry), or size of buffer used
        (if R6 was a pointer on entry)
   R6 preserved (if R0 bit 2 clear), or pointer to cached data buffer (if R0
      bit 2 set).

This SWI is used to generate a table of 'blended' palette entries for
SpriteExtend (and other clients). The tables generated will be the product
of the sizes of the palettes in the source and destination. The terms
'source' and 'destination' merely refer to the palettes in use. The 'source'
is the palette which is being overlaid on to the 'destination'. The palettes
will be blended in the ratio <translucency factor>:(255-<translucency
factor>).

By setting bit 2, it is possible to lock the area in BlendTable's workspace,
preventing the cached copy from being flushed by other clients. This ensures
that the space can be used until the area is unlocked.

The palettes are laid out in the form destination by source. That is, given
a source palette value (src) and a destination palette value (dst), for a
destination palette of dstcols colours, the blended palette value - in the
destination palette - is to be found at (dst*dstcols + src).


BlendTable_UnlockTable
=> R0 = pointer to cached data buffer to unlock

This SWI is used to unlock a table previously locked by setting bit 2 on
entry to BlendTable_GenerateTable.
