# The "overlay" Package

These routines provide a simple interface to the recursive, heirarchical data structure supported in Karma, to define 2-dimensional (image) overlay objects. In addition, all the mechanics for drawing onto world canvases (see the canvas package) is supplied automatically.

Library: karmagraphics
Link With: -lkarmagraphics

#### Functions

overlay_va_create_list | Create a managed overlay object list.
overlay_destroy_list | Destroy an overlay list.
overlay_prepare_for_slavery | Allow an overlay list to be slaved.
overlay_specify_iarray_2d | Extract specifications from an Intelligent Array.
overlay_specify_canvas | Extract specification from a world canvas.
overlay_create_viewable | Create a viewable overlay list.
overlay_set_active | Set active state for a viewable overlay list controlled refresh.
overlay_set_all_inactive | Clear active state all viewable overlay lists controlled refresh.
overlay_destroy_viewable | Destroy a viewable overlay list.
overlay_redraw_on_canvas | Redraw an overlay list onto a world canvas.
overlay_set_canvas_attributes | Set the canvas attributes for overlay list display.
overlay_line | Add a line to an overlay object list. See also overlay_lines.
overlay_lines | Add many lines to an overlay list.
overlay_text | Add a text string to an overlay object list.
overlay_ellipse | Add an ellipse to an overlay list. See also overlay_ellipses
overlay_arc | Add a rotated ellipse to an overlay list.
overlay_filled_polygon | Add a filled polygon to an overlay object list.
overlay_vector | Add a vector to an overlay list.
overlay_ellipses | Add many ellipses to an overlay list.
overlay_segments | Add many segments to an overlay list.
overlay_vectors | Add many vectors to an overlay list.
overlay_remove_objects | Remove objects from the end of an overlay object list.
overlay_remove_object | Remove one object from an overlay object list.
overlay_move_object | Move a object in an overlay object list.
overlay_get_num_coords | Get the number of co-ordinates in an overlay object.
overlay_get_coords | Get the co-ordinates for an overlay object.
overlay_have_token | Test if an overay list has the token.
overlay_release_token | Release the token to the master.
overlay_read_karma | Read overlay instructions from a Karma file.
overlay_write_karma | Write overlay instructions to a Karma file.
overlay_read_ascii | Read overlay instructions from an ASCII file.

#### Tables

overlay_CANVAS_ATTRIBUTES | List of overlay attributes for KWorldCanvas objects
overlay_COORDINATE_TYPES | List of co-ordinate types

## Functions

KOverlayList overlay_va_create_list (void *info, CONST char *name, ...)

Create a managed overlay object list.

Parameters:

- info : The arbitrary information pointer for the overlay list. This may be NULL.
- name : The name to be associated with the list. If this is NULL a default name is choosen.
- ... : The optional attributes are given as pairs of attribute-key attribute-value pairs. The list must be terminated with OVERLAY_ATT_END. See overlay_ATTRIBUTES for the list of attributes.

Returns: A KOverlayList object on success, else NULL.
Multithreading Level: Unsafe

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

void overlay_destroy_list (KOverlayList olist)

Destroy an overlay list.

Parameters:

- olist : The overlay list.

Returns: Nothing.
Multithreading Level: Unsafe

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

void overlay_prepare_for_slavery (KOverlayList olist)

This routine will register an overlay list to be the choosen overlay list for subsequent attempts to open a slave "2D_overlay" connection. In order to make the overlay list a slave, a subsequent call to conn_attempt_connection must be made.

Parameters:

- cmap : The overlay list.

Returns: Nothing.
Multithreading Level: Unsafe

void overlay_specify_iarray_2d (KOverlayList olist, iarray array)

This routine will specify horizontal and vertical label matching for an overlay list based on the dimension names of a 2-dimensional Intelligent Array. No further restrictions are imposed (any existing restrictions are removed) if the Intelligent Array is a pure 2-dimensional array. If the array is an alias of a plane of a 3-dimensional (or greater) array, then further restrictions are imposed.

Parameters:

- olist : The overlay list object.
- array : The Intelligent Array.

Returns: Nothing.
Multithreading Level: Unsafe

void overlay_specify_canvas (KOverlayList olist, KWorldCanvas canvas)

This routine will register a world canvas to extract specification information from for all future overlay objects which are created with an overlay object list.

Parameters:

- olist : The overlay list object.
- canvas : The world canvas object.

Returns: Nothing.
Multithreading Level: Unsafe

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

KViewableOverlayList overlay_create_viewable (KOverlayList olist, KWorldCanvas canvas)

Create a viewable overlay list.

Parameters:

- olist : The overlay list to create the viewable object from.
- canvas : The world canvas that the overlay list is viewable on.

Returns: A KViewableOverlayList object on success, else NULL. This is automatically destroyed when either the overlay list or the world canvas are destroyed.
Multithreading Level: Unsafe

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

flag overlay_set_active (KViewableOverlayList vlist, flag active, flag force_refresh, flag refresh_if_changed, flag exclusive, uaddr key)

Set active state for a viewable overlay list controlled refresh.

Parameters:

- vlist : The viewable overlay list.
- active : If TRUE, the viewable overlist list is made active, else it is made inactive.
- force_refresh : If TRUE, the canvas is always refreshed.
- refresh_if_changed : If TRUE, the canvas is refreshed if the viewable overlay list active state changed.
- exclusive : If TRUE and active is TRUE, make this viewable overlay list the only active one for this canvas. Other viewable overlay lists for this canvas will be made inactive.
- key : The key to use for inactivation of other viewable overlay lists. If this is 0 then all other viewable overlay lists will be made inactive.

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

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

flag overlay_set_all_inactive (KWorldCanvas canvas, flag force_refresh, flag refresh_if_changed, uaddr key)

This routine will make all viewable overlay lists associated with a world canvas inactive.

Parameters:

- canvas : The world canvas.
- force_refresh : If TRUE, the canvas is always refreshed.
- refresh_if_changed : If TRUE, the canvas is refreshed if the active state of any viewable overlay list changed.
- key : The key to use for inactivation of viewable overlay lists. If this is 0 then all viewable overlay lists will be made inactive.

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

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

void overlay_destroy_viewable (KViewableOverlayList vlist)

Destroy a viewable overlay list.

Parameters:

- vlist : The KViewableOverlayList object to destroy.

Returns: Nothing.
Multithreading Level: Unsafe

flag overlay_redraw_on_canvas (KOverlayList olist, KWorldCanvas canvas)

Redraw an overlay list onto a world canvas.

Parameters:

- olist : The overlay list object.
- canvas : The world canvas object.

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

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

void overlay_set_canvas_attributes (KWorldCanvas canvas, ...)

Set the canvas attributes for overlay list display.

Parameters:

- canvas : The world canvas object.
- ... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value OVERLAY_CANVAS_ATT_END. See overlay_CANVAS_ATTRIBUTES for a list of defined attributes.

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

unsigned int overlay_line (KOverlayList olist, unsigned int type0, double x0, double y0, unsigned int type1, double x1, double y1, CONST char *colourname)

Add a line to an overlay object list. See also overlay_lines.

Parameters:

- olist : The overlay list object.
- type0 : The type of the first co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- x0 : The horizontal position of the first co-ordinate.
- y0 : The vertical position of the first co-ordinate.
- type1 : The type of the second co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- x1 : The horizontal position of the second co-ordinate.
- y1 : The vertical position of the second co-ordinate.
- colourname : The colourname.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_lines (KOverlayList olist, unsigned int num_coords, unsigned int *types, double *x_arr, double *y_arr, CONST char *colourname)

This routine will add a number of connected lines to an overlay object list. These lines will form a single object. Using this routine is far more efficient than calling overlay_line repeatedly.

Parameters:

- olist : The overlay list.
- num_coords : The number of co-ordinates. The number of lines is one less than this value.
- types : An array of co-ordinate types. If this is NULL, all co-ordinates are assumed to be world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- x_arr : The horizontal co-ordinate values.
- y_arr : The vertical co-ordinate values.
- colourname : The colourname.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_text (KOverlayList olist, char *string, unsigned int type, double x, double y, CONST char *colourname, char *fontname, flag clear_under)

Add a text string to an overlay object list.

Parameters:

- olist : The overlay list object.
- string : The text string.
- type : The type of the co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- x : The horizontal position of the co-ordinate.
- y : The vertical position of the co-ordinate.
- colourname : The colourname.
- fontname : The font name.
- clear_under : If TRUE, then both the foreground and background of the characters will be drawn.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_ellipse (KOverlayList olist, unsigned int ctype,double cx, double cy, unsigned int rtype, double rx, double ry, CONST char *colourname, flag filled)

Add an ellipse to an overlay list. See also overlay_ellipses

Parameters:

- olist : The overlay list object.
- ctype : The type of the centre co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- cx : The horizontal position of the centre co-ordinate.
- cy : The vertical position of the centre co-ordinate.
- rtype : The type of the radius co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- rx : The horizontal radius.
- ry : The vertical radius.
- colourname : The colourname.
- filled : If TRUE the ellipse will be filled.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

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

unsigned int overlay_arc (KOverlayList olist, unsigned int ctype, double cx, double cy, unsigned int rtype, double rx, double ry, double rotation, CONST char *colourname, flag filled)

Add a rotated ellipse to an overlay list.

Parameters:

- olist : The overlay list object.
- ctype : The type of the centre co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- cx : The horizontal position of the centre co-ordinate.
- cy : The vertical position of the centre co-ordinate.
- rtype : The type of the radius co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- rx : The horizontal radius.
- ry : The vertical radius.
- rotation : The rotation of the ellipse in degrees. A rotation of 0 degrees corresponds to (x > 0, y = 0). A rotation of 90 degrees corresponds to (x = 0, y > 0). In other words, the angle increases anti-clockwise from the +ve X axis (if +X is right-going).
- colourname : The colourname.
- filled : If TRUE the ellipse will be filled.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_filled_polygon (KOverlayList olist, unsigned int num_coords, unsigned int *types, double *x_arr, double *y_arr, CONST char *colourname)

Add a filled polygon to an overlay object list.

Parameters:

- olist : The overlay list object.
- num_coords : The number of co-ordinates (vertices).
- types : The array of co-ordinate type values. If this is NULL, all co-ordinates are assumed to be world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- x_arr : The array of horizontal co-ordinate values.
- y_arr : The array of vertical co-ordinate values.
- colourname : The colour name.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_vector (KOverlayList olist, unsigned int stype, double sx, double sy, unsigned int dtype, double dx, double dy, CONST char *colourname)

This routine will add a vector (directed line) to an overlay object list. See also overlay_vectors.

Parameters:

- olist : The overlay list object.
- stype : The type of the start co-ordinate. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- sx : The horizontal position of the start co-ordinate.
- sy : The vertical position of the start co-ordinate.
- dtype : The type of the vector direction. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- dx : The horizontal vector direction.
- dy : The vertical vector direction.
- colourname : The colour name.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_ellipses (KOverlayList olist, unsigned int num_ellipses, unsigned int *ctypes, double *cx, double *cy, unsigned int *rtypes, double *rx, double *ry, CONST char *colourname, flag filled)

This routine will add a number of ellipses to an overlay object list. These ellipses will form a single object. Using this routine is far more efficient than calling overlay_ellipse repeatedly.

Parameters:

- olist : The overlay list object.
- num_ellipses : The number of ellipses.
- ctypes : The types of the centre co-ordinates. If this is NULL, all co-ordinates are assumed to be world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- cx : The horizontal positions of the centre co-ordinates.
- cy : The vertical positions of the centre co-ordinates.
- rtypes : The types of the radii co-ordinates. If this is NULL, all co-ordinates are assumed to be world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- rx : The horizontal radii.
- ry : The vertical radii.
- colourname : The colour name.
- filled : If TRUE the ellipses will be filled.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_segments (KOverlayList olist, unsigned int num_segments, unsigned int *types0, double *x0, double *y0, unsigned int *types1, double *x1, double *y1, CONST char *colourname)

This routine will add a number of disjoint line segments to an overlay object list. These segments will form a single object. Using this routine is far more efficient than calling overlay_line repeatedly.

Parameters:

- olist : The overlay list object.
- num_segments : The number of segments.
- types0 : The types of the start co-ordinates. If this is NULL, all co-ordinates are assumed to be world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- x0 : The horizontal positions of the start co-ordinates.
- y0 : The vertical positions of the start co-ordinates.
- types1 : The types of the stop co-ordinates. If this is NULL, all co-ordinates are assumed to be world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- x1 : The horizontal positions of the stop co-ordinates.
- y1 : The vertical positions of the stop co-ordinates.
- colourname : The colour name.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

unsigned int overlay_vectors (KOverlayList olist, unsigned int num_vectors, unsigned int *stypes, double *sx, double *sy, unsigned int *dtypes, double *dx, double *dy, CONST char *colourname)

This routine will add a number of vectors (directed lines) to an overlay object list. These vectors will form a single object. Using this routine is far more efficient than calling overlay_vector repeatedly.

Parameters:

- olist : The overlay list object.
- num_vectors : The number of vectors.
- stypes : The types of the start co-ordinates. If this is NULL, all co-ordinates are assumed to be world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- sx : The horizontal positions of the start co-ordinates.
- sy : The vertical positions of the start co-ordinates.
- dtypes : The types of the vector directions. If this is NULL, all directions are assumed to be in world co-ordinates. See overlay_COORDINATE_TYPES for a list of supported co-ordinate types.
- dx : The horizontal vector directions.
- dy : The vertical vector directions.
- colourname : The colour name.

Returns: The objectID on success, else 0.
Multithreading Level: Unsafe

flag overlay_remove_objects (KOverlayList olist, unsigned int num_objects)

Remove objects from the end of an overlay object list.

Parameters:

- olist : The overlay list object.
- num_objects : The number of objects to remove. If this is 0, then the list is emptied.

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

flag overlay_remove_object (KOverlayList olist, unsigned int id_in_list, unsigned int list_id)

Remove one object from an overlay object list.

Parameters:

- olist : The overlay list object.
- id_in_list : The object ID. This ID refers to an object created by a particular list master or slave.
- list_id : The ID of the list which created the object. If this is 0, the list given by olist is assumed.

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

flag overlay_move_object (KOverlayList olist, unsigned int id_in_list, unsigned int list_id, double dx, double dy)

Move a object in an overlay object list.

Parameters:

- olist : The overlay list object.
- id_in_list : The object ID. This ID refers to an object created by a particular list master or slave.
- list_id : The ID of the list which created the object. If this is 0, the list given by olist is assumed.
- dx : The horizontal distance to move. This is of the same co-ordinate type as the original co-ordinates.
- dy : The vertical distance to move. This is of the same co-ordinate type as the original co-ordinates.

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

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

unsigned int overlay_get_num_coords (KOverlayList olist, unsigned int id_in_list, unsigned int list_id)

Get the number of co-ordinates in an overlay object.

Parameters:

- olist : The overlay list object.
- id_in_list : The object ID. This ID refers to an object created by a particular list master or slave.
- list_id : The ID of the list which created the object. If this is 0, the list given by olist is assumed.

Returns: The number of co-ordinates on success, else 0.
Multithreading Level: Unsafe

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

flag overlay_get_coords (KOverlayList olist, unsigned int id_in_list, unsigned int list_id, double *x, double *y, unsigned int *types)

Get the co-ordinates for an overlay object.

Parameters:

- olist : The overlay list object.
- id_in_list : The object ID. This ID refers to an object created by a particular list master or slave.
- list_id : The ID of the list which created the object. If this is 0, the list given by olist is assumed.
- x : The horizontal co-ordinates are written here. This must have enough space to contain all the values that will be written. The function overlay_get_num_coords may be used to determine the required space. If this is NULL, nothing is written here.
- y : The vertical co-ordinates are written here. This must have enough space to contain all the values that will be written. The function overlay_get_num_coords may be used to determine the required space. If this is NULL, nothing is written here.
- types : The co-ordinate types are written here. This must have enough space to contain all the values that will be written. The function overlay_get_num_coords may be used to determine the required space. If this is NULL, nothing is written here.

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

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

flag overlay_have_token (KOverlayList olist)

Test if an overay list has the token.

Parameters:

- olist : The overlay list object.

Returns: TRUE if the overlay list has the token, else FALSE.
Multithreading Level: Unsafe

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

flag overlay_release_token (KOverlayList olist)

Release the token to the master.

Parameters:

- olist : The overlay list object.

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

- If the list is not a slave and does not have the token, the process aborts with an error message.

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

flag overlay_read_karma (KOverlayList olist, CONST char *filename)

This routine will read overlay instructions from a Karma file and will add the instructions to an overlay list.

Parameters:

- olist : The KOverlayList to add instructions to.
- filename : The name of the Karma file to read instructions from.

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

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

flag overlay_write_karma (KOverlayList olist, CONST char *filename)

Write overlay instructions to a Karma file.

Parameters:

- olist : The KOverlayList to get instructions from.
- filename : The name of the Karma file to write instructions to.

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

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

flag overlay_read_ascii (KOverlayList olist, CONST char *filename)

This routine will read overlay instructions from an ASCII file and will add the instructions to an overlay list.

Parameters:

- olist : The KOverlayList to add instructions to.
- filename : The name of the ASCII file to read instructions from.

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

## Tables

overlay_CANVAS_ATTRIBUTES List of overlay attributes for KWorldCanvas objects

Name | Get Type | Set Type | Meaning
OVERLAY_CANVAS_ATT_END |  |  | End of varargs list
OVERLAY_CANVAS_ATT_CROP | flag * | flag | Crop out-of-bounds objects

overlay_COORDINATE_TYPES List of co-ordinate types

Name | Meaning
OVERLAY_COORD_PIXEL | Screen pixel co-ordinates
OVERLAY_COORD_RELATIVE | Relative to a unit canvas (0,0) to (1,1)
OVERLAY_COORD_WORLD | True world co-ordinates
OVERLAY_COORD_LAST | Use last co-ordinate instead
OVERLAY_COORD_LINEAR | Canvas linear co-ordinates

Back to Karma Home Page