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.
For details of how to use the colour maps with deep sprites, consult the Sprite colour mapping document.
For details of how to use the colour maps with paletted sprites, consult PRM 3-346 (transfer functions).
For details of how to use the colour maps with Draw Files, consult the ColourMapping in Drawfiles document.
For details of how to use the colour maps with ImageFileRender, consult the The Image File Renderer document.
Technical Details
Using the module
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 be applied. 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 SWI 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 SWI ColourMap_Start, passing the workspace pointer and the size of the workspace.
- Call SWI 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 SWI ColourMap_ApplyMapping again. If the size was positive still, report an error in the mapping.
- Repeat applying additional mappings as necessary.
- Call SWI 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 SWI 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 SWI 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 SWI 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.
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 the CMYK sprites document) 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.
SWI Calls
| 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 |
| 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 SWI ColourMap_ApplyMapping calls.
| R0 | = | Flag bits:
| |||||||||
| R1 | = | Pointer to workspace | |||||||||
| R2 | = | Size of workspace | |||||||||
| R3... | = | Parameters for mapping | |||||||||
| R2 | = | Negative 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 :
| Type | Name | Parameters and meaning |
|---|---|---|
| 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 Sprite colour mapping 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. |
| R0 | = | Flag bits (reserved, must be 0) |
| R1 | = | Pointer to workspace |
| R2 | = | Size of workspace |
| 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.