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
Tables
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:
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
Contact: Richard Gooch
Web Development: Ariel Internet Services