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_listCreate a managed overlay object list.
overlay_prepare_for_slaveryAllow an overlay list to be slaved.
overlay_specify_iarray_2dExtract specifications from an Intelligent Array.
overlay_specify_canvasExtract specification from a world canvas.
overlay_associate_display_canvasAssociate display canvas with overlay list.
overlay_unassociate_display_canvasDissassociate a world canvas to display overlay objects.
overlay_redraw_on_canvasRedraw an overlay list onto a world canvas.
overlay_lineAdd a line to an overlay object list. See also overlay_lines.
overlay_linesAdd many lines to an overlay list.
overlay_textAdd a text string to an overlay object list.
overlay_ellipseAdd an ellipse to an overlay list. See also overlay_ellipses
overlay_arcAdd a rotated ellipse to an overlay list.
overlay_filled_polygonAdd a filled polygon to an overlay object list.
overlay_vectorAdd a vector to an overlay list.
overlay_ellipsesAdd many ellipses to an overlay list.
overlay_segmentsAdd many segments to an overlay list.
overlay_vectorsAdd many vectors to an overlay list.
overlay_remove_objectsRemove objects from the end of an overlay object list.
overlay_remove_objectRemove one object from an overlay object list.
overlay_move_objectMove a object in an overlay object list.
overlay_get_num_coordsGet the number of co-ordinates in an overlay object.
overlay_get_coordsGet the co-ordinates for an overlay object.
overlay_have_tokenTest if an overay list has the token.
overlay_release_tokenRelease the token to the master.
overlay_read_asciiRead overlay instructions from an ASCII file.

Tables

overlay_ATTRIBUTESList of attributes for KOverlayList objects
overlay_COORDINATE_TYPESList of co-ordinate types


Functions


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

Create a managed overlay object list.

Parameters:

Returns: A KOverlayList object on success, else NULL.
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:

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:

Returns: Nothing.
Multithreading Level: Unsafe


flag overlay_associate_display_canvas (KOverlayList olist, KWorldCanvas canvas)

This routine will register a world canvas to display overlay objects on when overlay objects received (either by overlay_* function calls within the application or over a "2D_overlay" connection). Multiple canvases may be associated with an overlay list.

Parameters:

Returns: TRUE on success, else FALSE (indicating that an error occurred refreshing the canvas).
Multithreading Level: Unsafe


flag overlay_unassociate_display_canvas (KOverlayList olist, KWorldCanvas canvas)

Dissassociate a world canvas to display overlay objects.

Parameters:

Returns: TRUE if the canvas was associated, else FALSE.
Multithreading Level: Unsafe


flag overlay_redraw_on_canvas (KOverlayList olist, KWorldCanvas canvas)

Redraw an overlay list onto a world canvas.

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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


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:

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


Tables


overlay_ATTRIBUTES

Name Get Type Set Type Meaning
OVERLAY_ATT_END End of varargs list


overlay_COORDINATE_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