The "scatplt" Package

These routines are meant to provide a high level mechanism to create and manipulate scatter plots (2-dimensional slices of Karma data structures). These scatter plots utilise the world canvases available in the canvas package, hence the resulting code is device independent. NOTE: THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

Library: karmagraphics
Link With: -lkarmagraphics

Functions

scatplt_init	Initialise the package for a particular canvas.
scatplt_create	Create scatter plot.
scatplt_set_active	Set active state for a scatter plot controlled refresh.
scatplt_set_all_inactive	Clear active state all scatter plots controlled refresh.
scatplt_destroy	Destroy scatter plot.
scatplt_register_destroy_func	Register destroy callback.
scatplt_get_worldcanvas	Get the world canvas for a scatter plot.
scatplt_find_closest	Find the closest point to a specified position.
scatplt_find_closest_all	Find the closest point to a specified position.
scatplt_create_vv	Create a value-value scatter plot from two 2D sub-arrays.
scatplt_create_smart_cursor	Create a smart cursor.

Prototype Functions

scatplt_PROTO_destroy_func	Process a destroy event on a scatter plot.
scatplt_PROTO_cursor_func	Process a smart cursor event on a scatter plot.

Tables

scatplt_CANVAS_ATTRIBUTES

List of canvas attributes for scatter plots

Functions

EXPERIMENTAL FUNCTION: subject to change without notice

void scatplt_init (KWorldCanvas canvas, ...)

This routine will initialise the scatplt package for a particular world canvas. Calling this routine causes a number of callback routines internal to the package to be registered with the canvas (such as refresh and position event callbacks). This routine must be called before creating scatter plots.

Parameters:

canvas : The world canvas object.
... : The list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the SCATPLT_CANVAS_ATT_END. See scatplt_CANVAS_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KScatterPlot scatplt_create (KWorldCanvas canvas, unsigned int num_points, CONST double *x, CONST double *y, uaddr key)

This routine will create a scatter plot object from two arrays of values. At a later time, this scatter plot may be made visible. This routine will not cause the canvas to be refreshed.

Parameters:

canvas : The world canvas onto which the scatter plot may be drawn. Many scatter plots may be associated with a single canvas.
num_points : The number of points in this scatter plot.
x : The array of horizontal values.
y : The array of vertical values.
key : The key to associate with this scatter plot.

Returns: A KScatterPlot object on success, NULL.
Multithreading Level: Unsafe
Note:

The KScatterPlot will be automatically destroyed if the canvas is destroyed.

EXPERIMENTAL FUNCTION: subject to change without notice

flag scatplt_set_active (KScatterPlot plot, flag active, flag force_refresh, flag refresh_if_changed, flag exclusive, uaddr key)

This routine will make a scatter plot active or inactive.

Parameters:

plot : The scatter plot.
active : If TRUE, the scatter plot 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 scatter plot active state changed.
exclusive : If TRUE and active is TRUE, make this scatter plot the only active one for this canvas. Other scatter plots for this canvas will be made inactive.
key : The key to use for inactivation of other scatter plots. If this is 0 then all other scatter plots will be made inactive.

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

EXPERIMENTAL FUNCTION: subject to change without notice

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

This routine will make all scatter plots 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 scatter plot changed.
key : The key to use for inactivation of scatter plots. If this is 0 then all scatter plots will be made inactive.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void scatplt_destroy (KScatterPlot plot)

This routine will destroy a scatter plot.

Parameters:

plot : The scatter plot.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc scatplt_register_destroy_func (KScatterPlot plot, void (*func) (), void *info)

This routine will register a destroy function for a scatter plot. The function will be called when the canvas is destroyed. Many destroy functions may be registered per plot. The first function registered is the first function called upon destruction.

Parameters:

plot : The scatter plot.
func : The function that is called when the plot is destroyed. The prototype function is scatplt_PROTO_destroy_func.
info : The arbitrary function information pointer.

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

EXPERIMENTAL FUNCTION: subject to change without notice

KWorldCanvas scatplt_get_worldcanvas (KScatterPlot plot)

Get the world canvas for a scatter plot.

Parameters:

plot : The scatter plot.

Returns: The KWorldCanvas object.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag scatplt_find_closest (KScatterPlot plot, double xin, double yin, double *xout, double *yout, uaddr *index, flag subpixel, double search_radius)

Find the closest point to a specified position.

Parameters:

plot : The scatter plot to search.
xin : The X world co-ordinate to search from.
yin : The Y world co-ordinate to search from.
xout : The exact X co-ordinate of the point found is written here.
yout : The exact Y co-ordinate of the point found is written here.
index : The index of the point is written here.
subpixel : If TRUE, search with subpixel resolution so that multiple points lying on the same screen pixel will be searched to find the closest point. If FALSE, the search will terminate early on the first point which lies on the same screen pixel. It is highly recommended that subpixel resolution is not used, as it may be orders of magnitude slower.
search_radius : The maximum search radius. Points further from the search position will be ignored.

Returns: TRUE if a close point was found, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag scatplt_find_closest_all (KWorldCanvas canvas, double xin, double yin, double *xout, double *yout, uaddr *index, KScatterPlot *plot, flag subpixel, double search_radius)

Find the closest point to a specified position.

Parameters:

canvas : The canvas to search. All active scatter plots are searched.
xin : The X world co-ordinate to search from.
yin : The Y world co-ordinate to search from.
xout : The exact X co-ordinate of the point found is written here.
yout : The exact Y co-ordinate of the point found is written here.
index : The index of the point is written here.
plot : The KScatterPlot the point was found in is written here.
subpixel : If TRUE, search with subpixel resolution so that multiple points lying on the same screen pixel will be searched to find the closest point. If FALSE, the search will terminate early on the first point which lies on the same screen pixel. It is highly recommended that subpixel resolution is not used, as it may be orders of magnitude slower.
search_radius : The maximum search radius. Points further from the search position will be ignored.

Returns: TRUE if a close point was found, else FALSE.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KScatterPlot scatplt_create_vv (KWorldCanvas canvas, CONST char *array1,CONST array_desc *arr_desc1, unsigned int xdim1, unsigned int ydim1, unsigned int type1, double scale1, double offset1, KwcsAstro ap1, unsigned int num_restr1, CONST char **restr_names1, CONST double *restr_values1, double *min1, double *max1, uaddr xstart, uaddr xlen, uaddr ystart, uaddr ylen, CONST char *array2,CONST array_desc *arr_desc2, unsigned int xdim2, unsigned int ydim2, unsigned int type2, double scale2, double offset2, KwcsAstro ap2, unsigned int num_restr2, CONST char **restr_names2, CONST double *restr_values2, double *min2, double *max2)

Create a value-value scatter plot from two 2D sub-arrays.

Parameters:

canvas : The world canvas onto which the scatter plot may be drawn.
array1 : The data for the first array.
arr_desc1 : The array descriptor for the first array.
xdim1 : The X dimension index for the first array.
ydim1 : The Y dimension index for the first array.
type1 : The data type for the first array.
scale1 : The data scaling for the first array.
offset1 : The data offset for the first array.
ap1 : The KwcsAstro object for the first array.
num_restr1 : The number of restrictions for the first array.
restr_names1 : The array of restriction names for the first array.
restr_values1 : The restriction values for the first array.
min1 : The minimum value from the first array. This is updated.
max1 : The maximum value from the first array. This is updated.
xstart : The X dimension start of the sub-array in the first array.
xlen : The X dimension length of the sub-array in the first array.
ystart : The Y dimension start of the sub-array in the first array.
ylen : The Y dimension length of the sub-array in the first array.
array2 : The data for the second array.
arr_desc2 : The array descriptor for the second array.
xdim2 : The X dimension index for the second array.
ydim2 : The Y dimension index for the second array.
type2 : The data type for the second array.
scale2 : The data scaling for the second array.
offset2 : The data offset for the second array.
ap2 : The KwcsAstro object for the second array.
num_restr : The number of restrictions for the second array.
restr_names : The array of restriction names for the second array.
restr_values : The restriction values for the second array.
min2 : The minimum value from the second array. This is updated.
max2 : The maximum value from the second array. This is updated.

Returns: A KScatterPlot object on success, NULL.
Multithreading Level: Unsafe
Note:

The KScatterPlot will be automatically destroyed if the canvas is destroyed.

EXPERIMENTAL FUNCTION: subject to change without notice

void scatplt_create_smart_cursor (KWorldCanvas canvas, double search_radius, flag (*func) (), void *info)

Create a smart cursor.

Parameters:

canvas : The world canvas.
search_radius : The maximum search radius. Points further from the search position will be ignored.
func : The function that is called when the plot is destroyed. The prototype function is scatplt_PROTO_cursor_func.
info : The arbitrary function information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Prototype Functions

void scatplt_PROTO_destroy_func (void *info)

Process a destroy event on a scatter plot.

Parameters:

info : An arbitrary function information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

flag scatplt_PROTO_cursor_func (KScatterPlot plot, double x, double y, uaddr index, void **info)

Process a smart cursor event on a scatter plot.

Parameters:

plot : The KScatterPlot object the cursor event matched.
x : The X co-ordinate of the point matched.
y : The Y co-ordinate of the point matched.
index : The index of the point matched.
info : A pointer to the arbitrary information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Tables

scatplt_CANVAS_ATTRIBUTES List of canvas attributes for scatter plots

Name Get Type Set Type Meaning

SCATPLT_CANVAS_ATT_END End of varargs list

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Get Type	Set Type	Meaning

SCATPLT_CANVAS_ATT_END			End of varargs list