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 uses for colour mapping include highlighting or fading graphical elements,
as used within the Window Manager. The colour mapping is performed through a colour
mapping descriptor -- a function pointer and workspace pair which are used to
translate colours. The ColourMap module provides descriptors for commonly used
colour operations, allowing clients to perform mappings without needing to provide
their own implementations.
Multiple colour mapping operations may be chained together: each operation in the
chain is applied in turn to produce the final result.
The normal sequence of operations to create and use a colour mapping descriptor is:
- Call , passing R1 = 0, to read
the initial size of the workspace required.
- Allocate a workspace block of at least the size returned.
- Call again, passing the workspace
pointer and its size in R1 and R2, to initialise the workspace.
- Call with the desired
mapping type and parameters.
- If an error occurs and R2 is returned as a negative value, the workspace was too
small. Reallocate the workspace to the size indicated (negated), reinitialise it
with , and re-apply all mappings.
If R2 is positive on error, the error relates to the mapping itself.
- Repeat calling to add
further mappings, as needed.
- Call to obtain a colour mapping
descriptor suitable for use with DrawFile, SpriteExtend, or other clients.
- Release the workspace once colour mapping is no longer required.
The workspace block is provided by the client. Its required size can be determined by
calling with R1 = 0. Providing a larger
workspace than the minimum will reduce the likelihood of reallocation requests being
returned from subsequent calls.
During the construction phase (between
and ), the workspace may be freely relocated
in memory by the client, as the ColourMap module holds no direct references to it during
this phase. However, once has been called,
the workspace must remain at a fixed address. The descriptor returned contains a direct
pointer into the workspace; relocating the workspace after this point will invalidate the
descriptor.
If the workspace must be moved after has
been called, call again at the new location
to obtain a fresh, valid descriptor.
The client may release the workspace memory once the colour mappings it provides are no
longer required. The ColourMap module holds no references to the workspace after use.
Multiple independent clients may use the ColourMap module simultaneously.
If the ColourMap module is killed or reinitialised, any descriptors previously returned
by may become invalid.
The workspace requirement for any given set of mappings remains constant regardless of
the parameters supplied to those mappings. This allows clients to reuse workspace blocks
for similar mappings without relocation.
The workspace format may change between versions of the module. Workspace blocks must
not be stored in persistent storage, such as data files or embedded within applications.
No executable code is placed within the workspace, so it may be located outside the
26-bit executable address range.
The internal layout of the workspace is shown below. Clients should treat the workspace
as opaque and must not modify it directly.
Magic word (&hex;9072340E), used to validate the workspace
Size of workspace currently used, in bytes
Colour mapping descriptor: workspace pointer (or 0 if not yet valid)
Colour mapping descriptor: function pointer (or 0 if not yet valid)
First mapping entry (see below); further entries follow contiguously
Each mapping entry within the workspace has the following layout:
Mapping type (a value), or -1 to mark the end of the list
Size of the mapping's workspace data, in bytes
Function pointer for this mapping (filled in by )
Mapping-specific workspace data
The colour mapping descriptor is a two-word block returned by
. It may be passed directly to interfaces
such as SpriteExtend and DrawFile which accept a colour mapping descriptor pointer.
Pointer to the workspace for this mapping
Pointer to the function that applies this mapping
The descriptor is valid only while the workspace remains at its current address and the
ColourMap module remains loaded.
The following mapping types are recognised by ColourMap_ApplyMapping. The type value is
supplied in bits 0-7 of R0.
Colours supplied to ColourMap SWIs and returned by them use the RISC OS 32-bit colour
word format:
Blue component (bits 24-31 of word, i.e. bits 7-0 at byte offset 3)
Green component
Red component
Always 0 (unused)
In hexadecimal notation this is written as &hex;BBGGRR00.
The following example in C illustrates the typical usage sequence to create a
descriptor that blends towards a red colour at 50% and then desaturates the result
to greyscale.
#include "modhead.h" /* For SWI definitions */
_kernel_oserror *apply_blend_and_mono(void **desc_out)
{
_kernel_swi_regs r;
_kernel_oserror *err;
char *workspace = NULL;
int wssize;
/* Step 1: query the minimum workspace size */
r.r[0] = 0;
r.r[1] = 0;
r.r[2] = 0;
err = _kernel_swi(ColourMap_Start, &r, &r);
if (err) return err;
wssize = -r.r[2]; /* returned as negative on size query */
/* Step 2: allocate the workspace */
workspace = malloc(wssize);
if (!workspace) return /* out of memory error */;
retry:
/* Step 3: initialise the workspace */
r.r[0] = 0;
r.r[1] = (int)workspace;
r.r[2] = wssize;
err = _kernel_swi(ColourMap_Start, &r, &r);
if (err) goto fail;
/* Step 4: apply a 50% blend towards red (&000000FF = red in BBGGRR00) */
r.r[0] = 0; /* type = Blend */
r.r[1] = (int)workspace;
r.r[2] = wssize;
r.r[3] = 0x000000FF; /* red */
r.r[4] = 0x80; /* 50% blend */
err = _kernel_swi(ColourMap_ApplyMapping, &r, &r);
if (err)
{
if (r.r[2] < 0)
{
/* workspace too small: grow and retry */
wssize = -r.r[2];
free(workspace);
workspace = malloc(wssize);
if (!workspace) return /* out of memory error */;
goto retry;
}
goto fail;
}
/* Step 5: apply a monochrome conversion */
r.r[0] = 4; /* type = Monochrome */
r.r[1] = (int)workspace;
r.r[2] = wssize;
err = _kernel_swi(ColourMap_ApplyMapping, &r, &r);
if (err) goto fail;
/* Step 6: obtain the colour mapping descriptor */
r.r[0] = 0;
r.r[1] = (int)workspace;
r.r[2] = wssize;
err = _kernel_swi(ColourMap_End, &r, &r);
if (err) goto fail;
*desc_out = (void *)r.r[0];
return NULL;
fail:
free(workspace);
return err;
}