# 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_initialise | This routine will initialise the package.
kcmap_va_create | Create a high level colourmap.
kcmap_destroy | Destroy a colourmap.
kcmap_register_destroy_func | Register destroy callback.
kcmap_add_RGB_func | Register a new colourmap function.
kcmap_add_grey_func | Register a new colourmap function.
kcmap_register_resize_func | Register a colourmap resize function.
kcmap_register_modify_func | Register a colourmap modify 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_prepare_for_mastery | 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_value | Get colour data from a colourmap.
kcmap_get_rgb_values | Get colour data from a colourmap.
kcmap_read_rgb_values | Get RGB values in a colourmap.
kcmap_write_rgb_values | Write RGB values to 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.
kcmap_register_att_notify_func | Register an attribute change function.
kcmap_get_dpy_handle | Get the Kdisplay object 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_destroy_func | Process a destroy event for an object.
kcmap_PROTO_modify_func | This routine registers a change in the colourmap values.
kcmap_PROTO_att_notify_func | This routine registers a change in the attributes of a colourmap.

#### Tables

kcmap_ATTRIBUTES | List of attributes for Kcolourmap objects

## Functions

#### EXPERIMENTAL FUNCTION: subject to change without notice

void kcmap_initialise ()

This routine will initialise the package.

Parameters:

This function takes no parameters

Returns: Nothing.
Multithreading Level: Unsafe

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.

#### EXPERIMENTAL FUNCTION: subject to change without notice

void kcmap_destroy (Kcolourmap cmap)

Destroy a colourmap.

Parameters:

- cmap : The colourmap.

Returns: Nothing.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc kcmap_register_destroy_func (Kcolourmap cmap, void (*func) (), void *info)

This routine will register a destroy function for a colourmap. This is called when kcmap_destroy is called. Many destroy functions may be registered per colourmap. The first function registered is the first function called upon destruction.

Parameters:

- cmap : The colourmap.
- func : The function that is called when the colourmap is destroyed. The prototype function is kcmap_PROTO_destroy_func.
- info : The arbitrary function information pointer.

Returns: A KCallbackFunc object. On failure, the process aborts.
Multithreading Level: Unsafe

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

#### EXPERIMENTAL FUNCTION: subject to change without notice

void kcmap_add_grey_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_grey_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 callback function for a high level colourmap. The function will be called whenever the colourmap is resized. If the colourmap is a software colourmap, the function is called whenever the colour values change. Many resize callbacks 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_modify_func.
- info : The initial arbitrary colourmap information pointer.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc kcmap_register_modify_func (Kcolourmap cmap, void (*modify_func) (), void *info)

This routine will register a modify callback function for a high level colourmap. The function will be called whenever the colourmap is modified. Many modify callbacks may be registered per colourmap. The first function registered is the first function called upon modify.

Parameters:

- cmap : The colourmap.
- modify_func : The function which is called when the colourmap is modified. The prototype function is kcmap_PROTO_modify_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:

This function takes no 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

#### EXPERIMENTAL FUNCTION: subject to change without notice

void kcmap_prepare_for_mastery (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

#### EXPERIMENTAL FUNCTION: subject to change without notice

void kcmap_get_rgb_value (Kcolourmap cmap, unsigned int index, unsigned short *red, unsigned short *green, unsigned short *blue)

This routine will return an RGB value in a colourmap.

Parameters:

- cmap : The colourmap object.
- index : The index into the colourmap.
- red : The red component colour value is written here.
- green : The green component colour value is written here.
- blue : The blue component colour value is written here.

Returns: Nothing.
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. This may be NULL.

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

unsigned int kcmap_read_rgb_values (Kcolourmap cmap, unsigned int num, unsigned short *red, unsigned short *green, unsigned short *blue, unsigned int stride)

Get RGB values in a colourmap.

Parameters:

- cmap : The colourmap object.
- num : The maximum number of colours to read.
- red : The red values are written here.
- green : The green values are written here.
- blue : The blue values are written here.
- stride : The stride (in shorts) between values in the arrays.

Returns: The number of RGB values written.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

flag kcmap_write_rgb_values (Kcolourmap cmap, unsigned int num_values, CONST unsigned short *reds, CONST unsigned short *greens, CONST unsigned short *blues, unsigned int stride)

This routine will write ther data into a colourmap. If the colourmap changes size, then the resize_func registered is called.

Parameters:

- cmap : The colourmap object.
- num_values : The maximum number of colours to write.
- red : The red values.
- green : The green values.
- blue : The blue values.
- stride : The stride (in shorts) between values in the arrays.

Returns: TRUE on success, else FALSE.
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.

#### EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc kcmap_register_att_notify_func (Kcolourmap cmap, void (*func) (), void *info)

This routine will register an attribute notify function for a high level colourmap. The attribute notify function will be called whenever the colourmap attributes are changed (see kcmap_set_attributes). Many attribute notify functions may be registered per colourmap. The first function registered is the first function called upon attribute changes.

Parameters:

- cmap : The colourmap.
- func : The function which is called when the attributes are changed. The prototype function is kcmap_PROTO_att_notify_func.
- info : The initial arbitrary colourmap information pointer.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

#### EXPERIMENTAL FUNCTION: subject to change without notice

Kdisplay kcmap_get_dpy_handle (Kcolourmap cmap)

Get the Kdisplay object for a colourmap.

Parameters:

- cmap : The colourmap.

Returns: A Kdisplay object.
Multithreading Level: Unsafe

## 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, unsigned long *cmap_id)

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.
- cmap_id : The ID of the hardware colourmap is 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

flag kcmap_PROTO_destroy_func (void *info)

Process a destroy event for an object.

Parameters:

- info : An arbitrary function information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

void kcmap_PROTO_modify_func (Kcolourmap cmap, void **info)

This routine registers a change in the colourmap values.

Parameters:

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

Returns: Nothing.
Multithreading Level: Unsafe

void kcmap_PROTO_att_notify_func (Kcolourmap cmap, void **info)

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

Parameters:

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

Returns: Nothing.
Multithreading Level: Unsafe

## Tables

kcmap_ATTRIBUTES List of attributes for Kcolourmap objects

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 int * | unsigned int | Red scale
KCMAP_ATT_GREEN_SCALE | unsigned int * | unsigned int | Green scale
KCMAP_ATT_BLUE_SCALE | unsigned int * | unsigned int | Blue scale
KCMAP_ATT_STEAL_COLOURS_FROM | unsigned int * | unsigned int | Colourmap to steal colours from

Back to Karma Home Page