Colour Map Module
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.
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 :
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.
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 ColourMap_ApplyMapping calls.
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
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.
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.
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.
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