|
Colour Map Module
Introduction
The ColourMap module provides an interface for constructing combinations of colour mapping functions as used by SpriteExtend, DrawFile and others. These functions allow colours within images to be manipulated to affect their rendering. Typical examples of colour mapping functions are to highlight or to fade elements (as used within the WindowManager). The colour mapping is performed through a colour mapping descriptor - a function pointer and workspace pair which are used to translate the colours.
The ColourMap module can provide descriptors for commonly used colour operations allowing clients to perform mappings without recourse to repeatedly providing their own implementations.
Technical details
In order to provide a colour mapping descriptor the ColourMap module must be given a block of workspace for its own use and informed of the mappings which the users wishes to apply. The workspace block is provided by the client and its size can be determined through calls to the module. Should more space be required within the workspace block this will be indicated through errors from the ColourMap module in a similar manner to other RISC OS interfaces (returning the size field as negative to indicate the size).
The normal sequence of operations to create and use the ColourMap module would be :
- Call ColourMap_Start, requesting the initial size of the workspace. This will return the size of the workspace necessary to hold the standard information about the mappings requested and to hold at least one of the more common mapping functions (blend to colour).
- Allocate workspace of size requested.
- Call ColourMap_Start, passing the workspace pointer and the size of the workspace.
- Call ColourMap_ApplyMapping, passing details of the workspace and the mapping required.
- If an error occurred, and the size returned is negative resize the workspace appropriately and call ColourMap_ApplyMapping again. If the size was positive still, report an error in the mapping.
- Repeat applying additional mappings as necessary.
- Call ColourMap_End to obtain a colourmap descriptor which may be used with DrawFile, SpriteExtend or other clients.
- Release workspace if colourmapping is no longer required.
Workspace properties
The workspace provided by the client may be freely relocated during the construction of the mappings. The workspace contents should be considered private and should not be modified by the client. The ColourMap module will not provide direct references during the construction of the mapping. Once ColourMap_End has been called the workspace should remain static. The descriptor returned will contain references to the current location of the workspace and relocating the workspace will make this invalid.
If the workspace must be moved in memory the ColourMap_End call should be made once more to obtain a new colourmap descriptor. Clients may release the memory used by the workspace once the colour mappings it provides are no longer required. No references are made from the ColourMap module to the workspace. Multiple clients may use the ColourMap module.
Clients should be aware that if the ColourMap module is killed or reinitialised the colourmap descriptor may be invalid.
Although the workspace may be relocated in memory by the client during construction of the mappings and between calls to ColourMap_End. It should not be assumed that the format of the workspace will remain constant between updates of the module. Because of this, workspace blocks should not be stored in persistent storage (eg in data files, or embedded in applications). The workspace requirement for any given mapping will remain constant regardless of the parameters provided. This allows clients to reuse workspace blocks for similar mappings without any relocation requirements.
Code will never be placed within the workspace, therefore it may be located outside the 26bit executable range.
ColourMap_Start (&567C0)
On entry
R0 = flags (reserved, must be 0)
R1 = pointer to workspace, or 0 to read initial size of workspace
R2 = size of workspace if not reading initial size
On exit
R2 = size of workspace used or required
This SWI is used to initialise a block of memory as use as a ColourMap module mapping workspace or to request the minimum size of the workspace. Larger workspaces than the minimum may be provided and will prevent reallocation requests on subsequent ColourMap_ApplyMapping calls.
ColourMap_ApplyMapping (&567C1)
On entry
R0 = flag bits :
bits 0-7 = Type of mapping to apply
Others reserved, must be 0
R1 = pointer to workspace
R2 = size of workspace
R3... parameters for mapping
On exit
R2 = -ve size of workspace required if an out of memory error occurred
This SWI is used to apply a new colour mapping to those already held in the workspace. The new mapping will be applied after those already held in the workspace.
Mapping types currently known to the ColourMap module are :
0 - Blend
R3 = &BBGGRR00 colour
R4 = factor (0 for solid source colour, &FF for solid blend colour)
The colour will be blended toward the colour supplied by a given
factor.
1 - User
R3 = pointer to colourmap descriptor to use (a copy will be taken)
A standard colourmap function will be invoked, allowing a number
of mapping functions to be chained together.
Refer to the section 'Colour mapping descriptor and transfer function'
in the Graphics.Sprites.ColourMap document.
2 - Identity
No parameters
The identity mapping does not affect the colour.
3 - Invert
No parameters
The colour value is inverted.
4 - Monochrome
No parameters
The colour is converted to a greyscale.
5 - Monochrome and scale
R3 = &BBGGRR00 'black' colour
R4 = &BBGGRR00 'white' colour
The colour is converted to a greyscale and then scaled to cover the
range between the colours specified.
6 - Gamma
R3 = 256 * gamma level (0-4)
The colour has gamma correction applied to it. This takes the form
of a mapping from the linear space to a logarithmic curve whose
depth is determined by the gamma level.
7 - Contrast
R3 = 256 * factor (0-4)
The colour has its contrast increased or decreased according to the
factor. Values for factor above 1 will increase the range of the
colours, effectively increasing the contrast; conversely, values of
less than 1 will decrease the range.
8 - Brightness
R3 = value to add (-256 - 256)
The colour will have the value supplied added to each of the R, G
and B components, effectively brightening or darkening the image.
ColourMap_End (&567C2)
On entry
R0 = flag bits (reserved, must be 0)
R1 = pointer to workspace
R2 = size of workspace
On exit
R0 = pointer to colourmap descriptor, or 0 if no descriptor is necessary
This SWI is used to read the colourmap descriptor which applies the mappings requested. If no mappings are held in the workspace, this will be indicated by returning a 0 value for the descriptor. Once this call has been made, the workspace should remain static. If changes are made to the workspace or it is moved in memory the descriptor returned by this call will be invalid. Calling ColourMap_End once more will return a valid descriptor.
ColourTrans changes
ColourTrans has been updated to operate faster within the standard paletted 256 colour modes where a fully specified palette is used. Under earlier versions of ColourTrans only VIDC1-compatible palettes on 256 colour modes were accelerated. A similar, but more efficient, translation function has also been added for grey scale paletted modes.
ColourTrans is aware of CMYK sprites (see Sprites - CMYK section) and will generate suitable wide or regular tables for such output.
When output is redirected to an alpha-channel mask, the palette is treated as effectively greyscale. This should allow simple plot operations to be performed.
|
![[Select]](../imgs/seldoc.png)
