The "kcmap" Package

These routines are meant to provide a high level mechanism to create and manipulate colourmaps, complete with colourmap sharing, dynamic allocation and event management.

Library: karma
Link With: -lkarma

Functions

kcmap_va_create	Create a high level colourmap.
kcmap_add_RGB_func	Register a new colourmap function.
kcmap_register_resize_func	Register a colourmap resize function.
kcmap_change	Change active colourmap function.
kcmap_modify	Change colours in a colourmap.
kcmap_modify_direct_type	Change colours in a colourmap.
kcmap_list_funcs	Get list of colourmap functions.
kcmap_get_funcs_for_cmap	Get list of colourmap functions compatible with a colourmap.
kcmap_get_active_func	Get active colourmap function.
kcmap_get_pixels	Get pixel values in a colourmap.
kcmap_notify_pixels_changed	Notify that pixel values have been changed.
kcmap_get_pixel	This routine will get a numbered pixel value from a colourmap.
kcmap_prepare_for_slavery	Allow colourmap to be slaved.
kcmap_copy_to_struct	Copy colour data from a colourmap.
kcmap_copy_from_struct	Copy colour data into a colourmap.
kcmap_get_rgb_values	Get colour data from a colourmap.
kcmap_get_attributes	This routine will get the attributes for a colourmap.
kcmap_set_attributes	This routine will set the attributes for a colourmap.

Prototype Functions

KCMAP_PROTO_alloc_func	Allocate colourcells.
KCMAP_PROTO_free_func	Free colourcells.
KCMAP_PROTO_store_func	This routine will store colours into a low level colourmap.
KCMAP_PROTO_location_func	Get location of display.
KCMAP_PROTO_colour_func	Modify colour values.
KCMAP_PROTO_grey_func	Modify greyscale colour values.
KCMAP_PROTO_resize_func	This routine registers a change in the size of a colourmap.

Tables

KCMAP_ATTRIBUTES

List of attributes for Kcolourmap objects

Functions

Kcolourmap kcmap_va_create (CONST char *name, unsigned int num_cells, flag tolerant, Kdisplay dpy_handle, unsigned int (*alloc_func) (), void (*free_func) (), void (*store_func) (), void (*location_func) (), ...)

This routine will create a high level colourmap. The colourmap may be associated with a hardware colourmap, or it may be a software-only colourmap. In either case, storage for an array of pixel values and arrays of colour components is maintained within the colourmap object.

Parameters:

name : The name of the function used to initialise the colour values. If this is NULL, the default "Greyscale1" function is used.
num_cells : The initial number of colourcells to allocate. This must not be less than 2.
tolerant : If TRUE the routine will try to allocate as many colourcells as possible (up to num_cells), else it will fail if it could not allocate all required colourcells.
dpy_handle : The low level display handle. The meaning of this value depends on the lower level graphics library used.
alloc_func : The function which must be called in order to allocate colourcells. See the xc routines for examples. The prototype function is KCMAP_PROTO_alloc_func.
free_func : The function which must be called to free colourcells. The The prototype function is KCMAP_PROTO_free_func.
store_func : The function which is used to store colours into a low level colourmap. The prototype function is KCMAP_PROTO_store_func.
location_func : The function which is used to determine the location of a display. The prototype function is KCMAP_PROTO_location_func.
... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value KCMAP_ATT_END. See KCMAP_ATTRIBUTES for a list of defined attributes.

Returns: A colourmap on success, else NULL.
Multithreading Level: Unsafe
Note:

If the above routines are NULL, the colourmap created is assumed to be a software colourmap, otherwise it is considered to be a hardware/virtual colourmap. A software colourmap, while maintaining storage for an array of pixel values, does not generate the pixel values. The kcmap_get_pixels routine may be used to modify the array of pixel values in a software colourmap.

void kcmap_add_RGB_func (CONST char *name, void (*func) (), unsigned int min_cells, unsigned int max_cells)

This routine will register a named function which will compute RGB intensity values for a colourmap. This function is typically called in response to a call to kcmap_modify.

Parameters:

name : The name of the colourmap function.
func : The function which is used to compute the RGB values. The prototype function is KCMAP_PROTO_colour_func.
min_cells : The minimum number of colourcells that must be allocated for this function to work. If this is less than 2, no minimum is defined.
max_cells : The maximum number of colourcells that may be allocated for this function to work. If this is less than 2, no maximum is defined.

Returns: Nothing.
Multithreading Level: Unsafe

KCallbackFunc kcmap_register_resize_func (Kcolourmap cmap, void (*resize_func) (), void *info)

This routine will register a resize function for a high level colourmap. The resize function will be called whenever the colourmap is resized. If the colourmap is a software colourmap, the resize function is called whenever the colour values change. Many resize functions may be registered per colourmap. The first function registered is the first function called upon resize.

Parameters:

cmap : The colourmap.
resize_func : The function which is called when the colourmap is resized. The prototype function is KCMAP_PROTO_resize_func.
info : The initial arbitrary colourmap information pointer.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

flag kcmap_change (Kcolourmap cmap, CONST char *new_name, unsigned int num_cells, flag tolerant)

This routine will change the active function (algorithm) used to calculate the colours in a colourmap and the size of the colourmap.

Parameters:

cmap : The colourmap object.
new_name : The new function name. If this is NULL then the active function is not changed.
num_cells : The number of colourcells required for the colourmap. If this is less then 2 the number of cells is not changed.
tolerant : If TRUE, then the routine will try to allocate as many colourcells as possible (up to num_cells ), else it will fail if it could not allocatate all required colourcells.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

void kcmap_modify (Kcolourmap cmap, double x, double y, void *var_param)

This routine will call the active colour compute function to change the colourmap colours in a colourmap.

Parameters:

cmap : The colourmap object.
x : A parameter used to compute the colour values.
y : A parameter used to compute the colour values.
var_param : A parameter used to compute the colour values.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

If the REVERSE attribute for the colourmap is set, the colourmap is reversed.

void kcmap_modify_direct_type (Kcolourmap cmap, double red_x, double red_y, void *red_var_param, double green_x, double green_y, void *green_var_param, double blue_x, double blue_y, void *blue_var_param)

This routine will call the active colour compute function to change the colourmap colours in a colourmap.

Parameters:

cmap : The colourmap object.
red_x : A parameter used to compute the red component colour values.
red_y : A parameter used to compute the red component colour values.
red_var_param : A parameter used to compute the red component colour values.
green_x : A parameter used to compute the green component colour values.
green_y : A parameter used to compute the green component colour values.
green_var_param : A parameter used to compute the green component colour values.
blue_x : A parameter used to compute the blue component colour values.
blue_y : A parameter used to compute the blue component colour values.
blue_var_param : A parameter used to compute the blue component colour values.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

If the REVERSE attribute for the colourmap is set, the colourmap is reversed.

CONST char ** kcmap_list_funcs ()

This routine will get the array of supported colour function names. This array is dynamically allocated, and should be freed using m_free. The array is terminated with a NULL pointer.

Parameters:

Returns: A pointer to the array.
Multithreading Level: Unsafe
Note:

The names in the array are statically allocated.

CONST char ** kcmap_get_funcs_for_cmap (Kcolourmap cmap)

This routine will get the array of supported colour function names. This array is dynamically allocated, and should be freed using m_free. The array is terminated with a NULL pointer. Only functions which are compatible with the colourmap are returned.

Parameters:

cmap : The colourmap object.

Returns: A pointer to the array.
Multithreading Level: Unsafe
Note:

The names in the array are statically allocated.

CONST char * kcmap_get_active_func (Kcolourmap cmap)

This routine will get the name of the active colour function for a colourmap.

Parameters:

cmap : The colourmap object.

Returns: A pointer to the name of the colour function. This name must not be freed.
Multithreading Level: Unsafe

unsigned int kcmap_get_pixels (Kcolourmap cmap, unsigned long **pixel_values)

This routine will determine the number of colourcells in a colourmap and the pixel values allocated.

Parameters:

cmap : The colourmap object.
pixel_values : A pointer to the array of pixel values will be written here. If this is NULL, nothing is written here. The pixel values may be modified if the colourmap is a software colourmap. If the pixel values are changed, the kcmap_notify_pixels_changed routine should be called.

Returns: The number of colourcells allocated.
Multithreading Level: Unsafe

void kcmap_notify_pixels_changed (Kcolourmap cmap)

This routine posts a notification that the pixel values in a software colourmap have changed. The resize functions registered with kcmap_register_resize_func are usually called.

Parameters:

cmap : The colourmap object. This must be a software colourmap.

Returns: Nothing.
Multithreading Level: Unsafe

unsigned long kcmap_get_pixel (Kcolourmap cmap, unsigned int index)

This routine will get a numbered pixel value from a colourmap.

Parameters:

cmap : The colourmap object.
index : The index of the pixel.

Returns: The pixel value.
Multithreading Level: Unsafe

void kcmap_prepare_for_slavery (Kcolourmap cmap)

This routine will register a colourmap to be the choosen colourmap for subsequent attempts to open a slave colourmap connection. In order to make the colourmap a slave, a subsequent call to conn_attempt_connection must be made.

Parameters:

cmap : The colourmap object.

Returns: Nothing.
Multithreading Level: Unsafe

flag kcmap_copy_to_struct (Kcolourmap cmap, packet_desc **top_pack_desc, char **top_packet)

This routine will copy the colour data in a colourmap into a newly allocated Karma data structure. This data structure may be subsequently deallocated.

Parameters:

cmap : The colourmap object.
top_pack_desc : The pointer to the top level packet descriptor that is allocated will be written here.
top_packet : The pointer to the top level packet that is allocated will be written here.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

flag kcmap_copy_from_struct (Kcolourmap cmap, packet_desc *top_pack_desc, char *top_packet)

This routine will copy the colour data in a Karma data structure into a colourmap. If the colourmap changes size, then the resize_func registered is called.

Parameters:

cmap : The colourmap object.
top_pack_desc : The top level packet descriptor.
top_packet : The top level packet.

Returns: TRUE on success, else FALSE.
Multithreading Level: Unsafe

unsigned short * kcmap_get_rgb_values (Kcolourmap cmap, unsigned int *size)

This routine will return the RGB values in a colourmap. The colour values are arranged in packets of Red, Green and Blue values.

Parameters:

cmap : The colourmap object.
size : The routine will write the size of the colourmap here.

Returns: A pointer to a dynamically allocated array. This must be freed with m_free. On failure it returns NULL.
Multithreading Level: Unsafe

void kcmap_get_attributes (Kcolourmap cmap, ...)

This routine will get the attributes for a colourmap.

Parameters:

cmap : The colourmap.
... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value KCMAP_ATT_END. See KCMAP_ATTRIBUTES for a list of defined attributes.

Returns: Nothing.
Multithreading Level: Unsafe

void kcmap_set_attributes (Kcolourmap cmap, ...)

This routine will set the attributes for a colourmap.

Parameters:

cmap : The colourmap.
... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value KCMAP_ATT_END. See KCMAP_ATTRIBUTES for a list of defined attributes.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The colourmap is not recomputed: the effect is delayed.

Prototype Functions

unsigned int KCMAP_PROTO_alloc_func (unsigned int num_cells, unsigned long *pixel_values, unsigned int min_cells, Kdisplay dpy_handle)

This routine will allocate a number of colourcells in a low level colourmap (e.g. using the Xlib routine XAllocColorCells).

Parameters:

num_cells : The number of colourcells to allocate.
pixel_values : The array ofpixel values allocated will be written here.
min_cells : The minimum number of colourcells to allocate. The routine will try to allocate at least this number of colourcells.
dpy_handle : The low level display handle. The meaning of this value depends on the lower level graphics library used.

Returns: The number of colourcells allocated.
Multithreading Level: Unsafe

void KCMAP_PROTO_free_func (unsigned int num_cells, unsigned long *pixel_values, Kdisplay dpy_handle)

This routine will free a number of colourcells in a low level colourmap.

Parameters:

num_cells : The number of colourcells to free.
pixel_values : The array of pixel values (colourcells) to free.
dpy_handle : The low level display handle. The meaning of this value depends on the lower level graphics library used.

Returns: Nothing.
Multithreading Level: Unsafe

void KCMAP_PROTO_store_func (unsigned int num_cells, unsigned long *pixel_values, unsigned short *reds, unsigned short *greens, unsigned short *blues, unsigned int stride, Kdisplay dpy_handle)

This routine will store colours into a low level colourmap.

Parameters:

num_cells : The number of colourcells to store.
pixel_values : The array of pixel values.
reds : The array of red intensity values.
greens : The array of green intensity values.
blues : The array of blue intensity values.
stride : The stride (in unsigned shorts) between intensity values in each array.
dpy_handle : The low level display handle. The meaning of this value depends on the lower level graphics library used.

Returns: Nothing.
Multithreading Level: Unsafe

void KCMAP_PROTO_location_func (Kdisplay dpy_handle, unsigned long *serv_hostaddr, unsigned long *serv_display_num)

This routine will determine the location of the graphics display being used.

Parameters:

dpy_handle : The low level display handle. The meaning of this value depends on the lower level graphics library used.
serv_hostaddr : The Internet address of the host to which the display is connected will be written here.
serv_display_num : The number of the display will be written here.

Returns: Nothing.
Multithreading Level: Unsafe

void KCMAP_PROTO_colour_func (unsigned int num_cells, unsigned short *reds, unsigned short *greens, unsigned short *blues, unsigned int stride, double x, double y, void *var_param)

This routine will write RGB colour intensity values to a number of colourcells. This routine is called in response to a call to kcmap_modify.

Parameters:

num_cells : The number of colour cells to modify.
reds : The array of red intensity values.
greens : The array of green intensity values.
blues : The array of blue intensity values.
stride : The stride (in unsigned shorts) between intensity values in each array.
x : A parameter used to compute the colour values.
y : A parameter used to compute the colour values.
max_cells : A parameter used to compute the colour values.

Returns: Nothing.
Multithreading Level: Unsafe

void KCMAP_PROTO_grey_func (unsigned int num_cells, unsigned short *reds, unsigned short *greens, unsigned short *blues, unsigned int stride, double x, double y, void *var_param)

This routine will write greyscale intensity values to a number of colourcells. This routine is called in response to a call to kcmap_modify.

Parameters:

num_cells : The number of colour cells to modify.
reds : The array of red intensity values. This may be NULL.
greens : The array of green intensity values. This may be NULL.
blues : The array of blue intensity values. This may be NULL.
stride : The stride (in unsigned shorts) between intensity values in the array.
x : A parameter used to compute the colour values.
y : A parameter used to compute the colour values.
max_cells : A parameter used to compute the colour values.

Returns: Nothing.
Multithreading Level: Unsafe

void KCMAP_PROTO_resize_func (Kcolourmap cmap, void **info)

This routine registers a change in the size of a colourmap.

Parameters:

cmap : The colourmap.
info : A pointer to the arbitrary colourmap information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Tables

KCMAP_ATTRIBUTES

Name Get Type Set Type Meaning

KCMAP_ATT_END End of varargs list
KCMAP_ATT_REVERSE flag * flag Reverse pixel order
KCMAP_ATT_INVERT flag * flag Invert intensities
KCMAP_ATT_SOFTWARE flag * Test if software colourmap
KCMAP_ATT_DPY_HANDLE Kdisplay * Get display handle
KCMAP_ATT_DIRECT_VISUAL flag * flag Handle colourmap as for a direct visual type
KCMAP_ATT_RED_SCALE unsigned short * unsigned short Red scale
KCMAP_ATT_GREEN_SCALE unsigned short * unsigned short Green scale
KCMAP_ATT_BLUE_SCALE unsigned short * unsigned short Blue scale

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Get Type	Set Type	Meaning

KCMAP_ATT_END			End of varargs list
KCMAP_ATT_REVERSE	flag *	flag	Reverse pixel order
KCMAP_ATT_INVERT	flag *	flag	Invert intensities
KCMAP_ATT_SOFTWARE	flag *		Test if software colourmap
KCMAP_ATT_DPY_HANDLE	Kdisplay *		Get display handle
KCMAP_ATT_DIRECT_VISUAL	flag *	flag	Handle colourmap as for a direct visual type
KCMAP_ATT_RED_SCALE	unsigned short *	unsigned short	Red scale
KCMAP_ATT_GREEN_SCALE	unsigned short *	unsigned short	Green scale
KCMAP_ATT_BLUE_SCALE	unsigned short *	unsigned short	Blue scale