RISC OS Documentation - ColourMapping of deep sprites

Sprites

ColourMapping of deep sprites

Deep sprites - those of 16bpp or 24bpp depths - cannot be operated on using standard pixel translation tables. The tables necessary to operate on such sprites would be 2<<16 bytes (128k), or 4<<24 bytes (64M). Since such tables would be impractical at best, and the range of operations that are possible on such images is large, a manner in which these images can be manipulated has been implemented.

For non-deep sprites pixel translation tables are generated using ColourTrans (q.v. ColourTrans_SelectTable, ColourTrans_GenerateTable) or manually. This initial scheme was suitable for paletted images. It was later extended to encompass more accurate plotting of paletted images in deep modes, and to allow the translation tables to be transformed through a transfer function. The transfer function allows arbitrary translation of an RGB value to another RGB value before that value is used in calculations.

For deep sprites a similar method has been adopted. As before, a transfer function provides a conversion between one source RGB value and a destination RGB value. This allows any deep sprite to be colour transformed. Since this transformation must be performed on every pixel plotted the additional processing required for the colour transformation (henceforth called 'colour mapping', or more simply 'mapping' to distinguish it from a spatial transformations) may be much greater than a plain plot of the same graphic.

API changes

The interface for rendering colour mapped sprites is an extension of that used for plain plotting. Sprite operations PutSpriteScaled and PutSpriteTransformed, and JPEG operations JPEG_PlotScaled, JPEG_PlotFileScaled, JPEG_PlotTransformed and JPEG_PlotFileTransformed have updated APIs to handle the new form of colour mapping.

Colour mapping functions only apply to deep sprites. Using the functions on non-deep sprites will generate an error. Such sprites should use pixel translation tables if they wish to be colour mapped.

OS_SpriteOp 52 (PutSpriteScaled)

On entry

   R0 = 52 + operation type (refer to documentation)
   R1 = pointer to sprite area
   R2 = pointer to sprite name, or sprite pointer.
   R3 = x coordinate
   R4 = y coordinate
   R5 = plot action; valid bits :
         3 = use mask
         6 = dithering on
         7 = use colour mapping (new flag for this call) all other values will
             be ignored, and may be explicitly faulted.
   R6 = pointer to scale factors (refer to documentation)
   R7 = pointer to colour mapping descriptor

This operation will plot a deep sprite using the colour mapping supplied.

OS_SpriteOp 56 (PutSpriteTransformed)

On entry

   R0 = 56 + operation type (refer to documentation)
   R1 = pointer to sprite area
   R2 = pointer to sprite name, or sprite pointer.
   R3 = flags (refer to documentation)
   R4 = pointer to source rectangle within sprite
   R5 = plot action; valid bits :
               3 = use mask
               7 = use colour mapping (new flag for this call), all other values
                   will be ignored, and may be explicitly faulted.
   R6 = pointer to transformation matrix, or destination co-ords (refer to documentation)
   R7 = pointer to colour mapping descriptor

This operation will plot a deep sprite using the colour mapping supplied.

JPEG_PlotScaled

On entry

   R0 = pointer to JPEG
   R1 = x coordinate
   R2 = y coordinate
   R3 = pointer to scale factors (refer to documentation)
   R4 = length of image
   R5 = plot flag bits :
               0 = dither output when plotting 24bit JPEG at 16bpp or below
               1 = invalid
               3 = use colourmap (new flag for this call)
   R6 = pointer to colour mapping descriptor

This operation plots a JPEG using the colour mapping supplied.

JPEG_PlotFileScaled

On entry

   R0 = pointer to filename of JPEG file
   R1 = x coordinate
   R2 = y coordinate
   R3 = pointer to scale factors (refer to documentation)
   R4 = plot flag bits :
               0 = dither output when plotting 24bit JPEG at 16bpp or below
               1 = invalid
               3 = use colourmap (new flag for this call)
   R5 = pointer to colour mapping descriptor

This operation plots a JPEG using the colour mapping supplied.

JPEG_PlotTransformed

On entry

   R0 = pointer to JPEG R1 = transformation flag bits :
               0 = R2 = pointer to destination coordinate block, rather than matrix
               1 = dither output when plotting 24bit JPEG at 16bpp or below
               2 = invalid
               4 = use colourmap (new flag for this call)
   R2 = pointer to transformation matrix, or destination co-ords (refer to documentation)
   R3 = length of image
   R4 = pointer to colour mapping descriptor

This operation plots a JPEG using the colour mapping supplied.

JPEG_PlotFileTransformed

On entry

   R0 = pointer to filename of JPEG file R1 = transformation flag bits :
               0 = R2 = pointer to destination coordinate block, rather than matrix
               1 = dither output when plotting 24bit JPEG at 16bpp or below
               2 = invalid
               4 = use colourmap (new flag for this call)
   R2 = pointer to transformation matrix, or destination co-ords (refer to documentation)
   R3 = pointer to colour mapping descriptor

This operation plots a JPEG using the colour mapping supplied.

Colour mapping descriptor and transfer function

The colour mapping descriptor is a small structure containing the workspace and transfer function pointer. The structure has the following layout :

+0 = workspace to pass in R12 to transfer function
+4 = pointer to transfer function

The transfer function used by these operations is exactly the same as that used by the ColourTrans_SelectTable calls (PRM 3-346). The function will be called in SVC mode with the usual supervisor stack limits.

On entry

   R0 = palette entry (&BBGGRR00)
   R12 = workspace value passed when call made
   R13 = supervisor stack
   R14 = return address

On exit

   R0 = palette entry (&BBGGRR00)
   R12 may be corrupt
   R14 may be corrupt

The transfer function should perform whatever processing is required on the palette entry passed to it. The routine may not change mode, perform any operation which might cause SpriteExtend to be threaded out of (eg VDU output) or cause the machine to block. You should return with MOV pc,lr. The transfer function will not be called for masked pixels.

Errors

JPEG handling within SpriteExtend has been improved to provide greater feedback on errors relating to JPEG which cannot be rendered. This should provide better programmer feedback as to why rendering cannot be performed, and allow the user to decide what course of action to take.

Other errors have been added to provide feedback on other faults within SpriteExtend.

Error_Sprite_BadColourMap (&720)

This error is generated when the 'ColourMap' flag is set for a depth for which it is unsuitable, for example a 256 colour sprite. Colour mapping for shallow sprites should be performed through translation tables which are more efficient.

Error_Sprite_BadJPEGUnsupported (&721)

This error is generated for JPEGs whose format is not supported. Examples of such JPEGs are those with sample factors which are not supporting, for example JPEGs with U or V sampling factors other than 1x1.

Error_Sprite_BadJPEGProgressive (&722)

This error is generated when a progressive JPEG cannot be rendered by SpriteExtend.

Error_Sprite_BadType (&723)

This error is generated when a call is made to SpriteExtend to render a sprite of a type which is not understood.

Sprite Plot Actions

The sprite plot action is a bit field allowing the caller to specify the manner of the sprite plotting. It is used on a number of OS_SpriteOp calls, in particular :

Put sprite (28)
Put sprite at user co-ords (32)
Paint sprite scaled (52)
Plot sprite transformed (56)
Tile sprite scaled (65)

The following bits are used within the plot action :

   bit 0-2 = Plot action:
               0 = Overwrite
               1 = OR
               2 = AND
               3 = EOR
               4 = Invert
               5 = No-effect
               6 = AND-NOT
               7 = OR-NOT
               See PRM 1-753.
   bit 3 = Use mask if set, otherwise ignore mask data if present, See PRM 1-753
   bit 4 = Use palette entries rather than translation table if suitable. See PRM 5a-117.
   bit 5 = Wide Translation Table has been used if set, otherwise 8 bit translation 
           is present. See PRM 5a-118.
   bit 6 = Use dithering to more accurately match colours if set, otherwise the fastest
           rendering method will be used. See PRM 5a-118.
   bit 7 = Colour-mapping function is provided rather than a translation table if set.
            See Sprites - ColourMap section
   bit 8-15 = Translucency level :
         0 = Solid image
         255 = No effect, or close to no effect, other values linearly represent
               translucency levels between these extremes, but may be quantised by the
               rendering implementation in SpriteExtend or other acceleration systems.
               See Sprites - Translucency section.
   bit 16-31 = Reserved, must be 0.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015