The "canvas" Package

These routines are meant to provide a high level mechanism to create and manipulate world canvases (canvases which have a co-ordinate system based on real-world co-ordinates). These canvases utilise the pixel canvases available in the kwin package, hence the resulting code is device independent.

Library: karmagraphics
Link With: -lkarmagraphics

Functions

canvas_draw_edit_list	Draw a list of edit objects to a world canvas.
canvas_draw_edit_object	Draw one edit object to a world canvas.
canvas_create	Create world canvas.
canvas_register_refresh_func	Register world canvas refresh callback.
canvas_register_size_control_func	Register size control callback.
canvas_register_position_event_func	Register position event callback.
canvas_get_attributes	Get canvas attributes.
canvas_set_attributes	Set canvas attributes.
canvas_resize	Resize a world canvas.
canvas_specify	Set specification information for a world canvas.
canvas_get_specification	Get specification information for a world canvas.
canvas_convert_to_canvas_coords	Convert pixel co-ordinates to world co-ordinates.
canvas_convert_from_canvas_coords	Convert world co-ordinates to pixel co-ordinates.
canvas_register_coords_convert_func	Register co-ordinate conversion function.
canvas_coords_transform	Transform world co-ordinates.
canvas_register_transforms_func	Register non-linear co-ordinate transformation function.
canvas_get_pixcanvas	Get the underlying pixel canvas of a world canvas.
canvas_get_colour	Get (possibly allocating) a colourcell for a canvas.
canvas_set_dressing	Set dressing parameters for a world canvas.
canvas_get_dressing	Get dressing parameters for a world canvas.
canvas_sequence_dressing_refresh	Set order in which dressing is refreshed.
canvas_draw_dressing	Draw the dressing (axes, etc.) for a world canvas.
canvas_get_cmap	Get the Kcolourmap object associated with a world canvas.
canvas_draw_image	Draw a PseudoColour image onto a world canvas.
canvas_draw_rgb_image	Draw a TrueColour image onto a world canvas.
canvas_draw_point	Draw a single point onto a world canvas.
canvas_draw_point_p	Draw a single point onto a world canvas.
canvas_draw_line	Draw a single line onto a world canvas.
canvas_draw_line_p	Draw a single line onto a world canvas.
canvas_draw_arc	Draw an arc onto a world canvas.
canvas_draw_arc_p	Draw an ellipse onto a world canvas.
canvas_draw_ellipse	Draw an ellipse onto a world canvas.
canvas_draw_ellipse_p	Draw an ellipse onto a world canvas.
canvas_fill_ellipse	Draw a filled ellipse onto a world canvas.
canvas_fill_ellipse_p	Draw a filled ellipse onto a world canvas.
canvas_convert_ellipse_coords	Convert co-ordinates for an ellipse.
canvas_fill_polygon	Draw a filled polygon onto a world canvas.
canvas_draw_rectangle	Draw a single rectangle onto a world canvas.
canvas_draw_rectangle_p	Draw a single rectangle onto a world canvas.
canvas_fill_rectangle	Fill a single rectangle onto a world canvas.
canvas_fill_rectangle_p	Fill a single rectangle onto a world canvas.
canvas_draw_lines	Draw multiple connected lines onto a world canvas.
canvas_draw_lines_p	Draw multiple connected lines onto a world canvas.
canvas_draw_segments	Draw multiple disjoint lines onto a world canvas.
canvas_draw_segments_p	Draw multiple disjoint lines onto a world canvas.
canvas_init_win_scale	Initialise win_scale structure.
canvas_use_log_scale	Enable logarithmic scaling for a world canvas.
canvas_use_astro_transform	Use astronomical sky projections for a canvas.
canvas_create_stroke_instruction	Create an image editing stroke instruction.

Prototype Functions

canvas_PROTO_refresh_func	Refresh event callback.
canvas_PROTO_size_control_func	Size control callback.
canvas_PROTO_position_func	Position event callback.
canvas_PROTO_coord_convert_func	Co-ordinate conversion callback.
canvas_PROTO_coord_transform_func	Co-ordinate transformation callback.

Tables

canvas_ATTRIBUTES

List of attributes for KWorldCanvas objects

Functions

flag canvas_draw_edit_list (KWorldCanvas canvas, KImageEditList ilist)

Draw a list of edit objects to a world canvas.

Parameters:

canvas : The world canvas.
ilist : The instruction list.

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

flag canvas_draw_edit_object (KWorldCanvas canvas, char *object)

Draw one edit object to a world canvas.

Parameters:

canvas : The world canvas.
object : The edit object.

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

KWorldCanvas canvas_create (KPixCanvas pixcanvas, Kcolourmap cmap, struct win_scale_type *win_scale)

This routine will create a world canvas, ready for drawing, from a KPixCanvas (pixel canvas) object. The origin of a KWorldCanvas is the lower-left corner.

Parameters:

pixcanvas : The pixel canvas object.
cmap : The colourmap. If this is NULL, the canvas will only permit drawing using pixel values. This precludes the use of drawing PseudoColour images and drawing geometric primitives using data values.
win_scale : The window scaling information. The x_offset x_pixels y_offset and y_pixels fields are determined internally. If this is NULL a default scale is choosen.

Returns: A world canvas object on success, else NULL.
Multithreading Level: Unsafe
Note:

Resize events on the colourmap will cause the canvas to be refreshed.

KCallbackFunc canvas_register_refresh_func (KWorldCanvas canvas, void (*refresh_func) (),void *info)

This routine will register a refresh function for a world canvas. The refresh function will be called whenever the contents of the canvas need to be redrawn. Many refresh functions may be registered per canvas. The first function registered is the first function called upon refresh.

Parameters:

canvas : The world canvas.
refresh_func : The function that is called when the canvas is to be refreshed. The prototype function is canvas_PROTO_refresh_func.
info : The initial arbitrary canvas information pointer.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

void canvas_register_size_control_func (KWorldCanvas canvas, void (*size_control_func) (), void *info)

This routine will register the size control function for a world canvas. This function will be called whenever the lower level pixel canvas resizes, or the associated Kcolourmap object is resized, OR a call is made to canvas_resize. The function may alter the window scaling information for the canvas. Only one size control function is permitted per canvas. The size control routine is called before any refresh functions are called. This is a means for a higher level object to take control of the world canvas.

Parameters:

canvas : The world canvas object.
size_control_func : The function that is called when the canvas is to be refreshed. The prototype function is canvas_PROTO_size_control_func.
info : The initial arbitrary canvas information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

KCallbackFunc canvas_register_position_event_func (KWorldCanvas canvas, flag (*func) (), void *f_info)

This routine will register a position event function for a world canvas. The position event function will be called whenever a position event on the canvas has not been consumed. Many position event functions may be registered per canvas. The first function registered is the first function called upon a position event.

Parameters:

canvas : The world canvas.
func : The function that is called when a position event occurs. The prototype function is canvas_PROTO_position_func.
f_info : The initial arbitrary function information pointer.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

void canvas_get_attributes (KWorldCanvas canvas, ...)

Get canvas attributes.

Parameters:

canvas : The world canvas.
... : The optional attributes are given as pairs of attribute-key attribute-value pointer pairs. The list must be terminated with CANVAS_ATT_END. See canvas_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

flag canvas_set_attributes (KWorldCanvas canvas, ...)

Set canvas attributes.

Parameters:

canvas : The world canvas.
... : The optional attributes are given as pairs of attribute-key attribute-value pairs. The list must be terminated with CANVAS_ATT_END. See canvas_ATTRIBUTES for the list of attributes.

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

flag canvas_resize (KWorldCanvas canvas, struct win_scale_type *win_scale, flag always_clear)

This routine will register a resize in the world canvas size. This will cause any refresh routines registered for the canvas to be called. The associated pixel canvas is refreshed, hence, refresh routines registered for the pixel canvas will also be called.

Parameters:

canvas : The world canvas object.
win_scale : The new window scaling information. If this is NULL no change is made to the window scaling information, and a simple refresh occurs.
always_clear : If FALSE, win_scale is NULL and there is a size control function registered for the world canvas, then if that function does not change the values of the x_offset, x_pixels, y_offset or y_pixels fields in the window scaling information, the associated pixel canvas is NOT cleared. Under all other circumstances, the pixel canvas is cleared prior to calling any refresh functions.

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

flag canvas_specify (KWorldCanvas canvas, CONST char *xlabel, CONST char *ylabel, unsigned int num_restr, CONST char **restr_names, CONST double *restr_values)

This routine will change the specifications for a canvas. This includes the horizontal and vertical dimension labels and any restrictions. The entire specification is copied (i.e. the inputs may be freed).

Parameters:

canvas : The world canvas object.
xlabel : The horizontal dimension label.
ylabel : The vertical dimension label.
num_restr : The number of restrictions.
restr_names : The array of restriction names.
restr_values : The restriction values.

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

This routine DOES NOT cause the canvas to be refreshed. It is highly recommended that the canvas is refreshed after this routine, as higher level packages may depend on the specification information.
All string values are copied.

void canvas_get_specification (KWorldCanvas canvas, char **xlabel, char **ylabel, unsigned int *num_restr, char ***restr_names, double **restr_values)

This routine will get the specifications for a canvas. This includes the horizontal and vertical dimension labels and any restrictions. Only pointers are copied (i.e. the outputs may NOT be freed).

Parameters:

canvas : The world canvas object.
xlabel : The pointer to the horizontal dimension label will be written here. This may be NULL.
ylabel : The pointer to the vertical dimension label will be written here. This may be NULL.
num_restr : The number of restrictions will be written here. This may be NULL.
restr_names : The pointer to the array of restriction names will be written here. This may be NULL.
restr_values : The pointer to the array of restriction values will be written here. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_convert_to_canvas_coords (KWorldCanvas canvas, flag clip, unsigned int num_coords, CONST double *xin, CONST double *yin, double *xout_lin, double *yout_lin, double *xout, double *yout)

Convert pixel co-ordinates to world co-ordinates.

Parameters:

canvas : The world canvas object.
clip : If TRUE, pixel co-ordinates are first clipped to the canvas boundaries prior to conversion.
num_coords : The number of co-ordinates to convert.
xin : The array of input horizontal pixel co-ordinates.
yin : The array of input vertical pixel co-ordinates.
xout_lin : The array of output horizontal linear world co-ordinates are written here. If this is NULL, nothing is written here.
yout_lin : The array of output vertical linear world co-ordinates are written here. If this is NULL, nothing is written here.
xout : The array of output horizontal non-linear world co-ordinates are written here. If this is NULL, nothing is written here.
yout : The array of output vertical non-linear world co-ordinates are written here. If this is NULL, nothing is written here.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_convert_from_canvas_coords (KWorldCanvas canvas, flag clip, flag linear, unsigned int num_coords, CONST double *xin, CONST double *yin, double *xout, double *yout)

Convert world co-ordinates to pixel co-ordinates.

Parameters:

canvas : The world canvas object.
clip : If TRUE, world co-ordinates are first clipped to the canvas boundaries prior to conversion.
linear : If TRUE, the input world co-ordinates are assumed to be linear, hence no non-linear to linear co-ordinate transformation is applied.
num_coords : The number of co-ordinates to convert.
xin : The array of input horizontal world co-ordinates.
yin : The array of input vertical world co-ordinates.
xout : The array of output horizontal pixel co-ordinates are written here.
yout : The array of output vertical pixel co-ordinates are written here.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_register_coords_convert_func (KWorldCanvas canvas, flag (*coord_convert_func) (), void *info)

This routine will register the co-ordinate conversion function for a world canvas. This function will be called whenever conversions between world co-ordinates and pixel co-ordinates are performed. Only one co-ordinate conversion function is permitted per canvas. This is a means for a higher level object to take control of the world canvas.

Parameters:

canvas : The canvas.
func : The function that is called when co-ordinates are to be converted. The prototype function is canvas_PROTO_coord_convert_func.
info : The initial arbitrary canvas information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_coords_transform (KWorldCanvas canvas, unsigned int num_coords, double *x, flag x_to_linear, double *y, flag y_to_linear)

This routine will transform co-ordinates in a world canvas using the registered co-ordinate transform function (see canvas_register_transforms_func).

Parameters:

canvas : The world canvas object.
num_coords : The number of co-ordinates to transform.
x : The array of horizontal world co-ordinates. These are modified.
x_to_linear : If TRUE, then the horizontal co-ordinates are converted from non-linear to linear, else they are converted from linear to non-linear.
y : The array of vertical world co-ordinates. These are modified.
y_to_linear : If TRUE, then the vertical co-ordinates are converted from non-linear to linear, else they are converted from linear to non-linear.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_register_transforms_func (KWorldCanvas canvas, void (*coord_transform_func) (), void *info)

This routine will register the co-ordinate transform function for a world canvas. The co-ordinate transform function transforms the linear world co-ordinates used internally by the world canvas to be transformed into non-linear co-ordinates for external use. Only one co-ordinate transform function is permitted per canvas.

Parameters:

canvas : The world canvas object.
coord_transform_func : The function that is called when co-ordinates are to be transformed. The prototype function is canvas_PROTO_coord_transform_func. If an existing transformation function is registered, it is overwritten.
info : The initial arbitrary transform information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

KPixCanvas canvas_get_pixcanvas (KWorldCanvas canvas)

Get the underlying pixel canvas of a world canvas.

Parameters:

canvas : The world canvas object.

Returns: The KPixCanvas object.
Multithreading Level: Unsafe

flag canvas_get_colour (KWorldCanvas canvas, CONST char *colourname, unsigned long *pixel_value, unsigned short *red, unsigned short *green, unsigned short *blue)

Get (possibly allocating) a colourcell for a canvas.

Parameters:

canvas : The world canvas object.
colourname : The name of the colour to get.
pixel_value : The pixel value will be written here.
red : The red intensity in the hardware colourmap for the pixel will be written here. If this is NULL, nothing is written here.
green : The green intensity in the hardware colourmap for the pixel will be written here. If this is NULL, nothing is written here.
blue : The blue intensity in the hardware colourmap for the pixel will be written here. If this is NULL, nothing is written here.

Returns: TRUE if the colourcell was allocated, else FALSE.
Multithreading Level: Unsafe
Note:

The pixel value is valid ONLY for the underlying pixel canvas. ALSO: the pixel value becomes invalid EVERY time the underlying pixel canvas is refreshed/ resized. If the pixel canvas is refreshed/ resized, this routine MUST be called again.

void canvas_set_dressing (KWorldCanvas canvas, ...)

Set dressing parameters for a world canvas.

Parameters:

canvas : The world canvas.
... : The list of parameter attribute-key attribute-value pairs. This list must be terminated with the value KCD_ATT_END.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The dressing code is not yet complete.

void canvas_get_dressing (KWorldCanvas canvas, ...)

Get dressing parameters for a world canvas.

Parameters:

canvas : The world canvas.
... : The list of parameter attribute-key attribute-value pairs. This list must be terminated with the value KCD_ATT_END.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

The dressing code is not yet complete.

void canvas_sequence_dressing_refresh (KWorldCanvas canvas)

This routine will sequence the dressing (axes, etc.) refresh function for a world canvas. If this routine is not called, the dressing will be drawn after *all* registered refresh functions have been called (see canvas_register_refresh_func). If this routine is called, all preceeding refresh functions (registered with canvas_register_refresh_func) will be called on refresh prior to the dressing being drawn and all refresh functions registered after this routine is called will be called *after* the dressing is drawn.

Parameters:

canvas : The world canvas object.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_dressing (KWorldCanvas canvas)

Draw the dressing (axes, etc.) for a world canvas.

Parameters:

canvas : The world canvas object.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This routine is called automatically each time the canvas is refreshed.

Kcolourmap canvas_get_cmap (KWorldCanvas canvas)

Get the Kcolourmap object associated with a world canvas.

Parameters:

canvas : The world canvas object.

Returns: The Kcolourmap object. This may be NULL (indicating there is no colourmap associated with the canvas).
Multithreading Level: Unsafe

flag canvas_draw_image (KWorldCanvas canvas, array_desc *arr_desc, char *slice, unsigned int hdim, unsigned int vdim, unsigned int elem_index, KPixCanvasImageCache *cache_ptr)

This routine will draw a 2-dimensional PseudoColour slice of a Karma array onto a world canvas. This slice may be tiled.

Parameters:

canvas : The world canvas object.
arr_desc : The array descriptor for the image.
slice : The start of the slice (image) data.
hdim : The dimension index of the horizontal dimension.
vdim : The dimension index of the vertical dimension.
elem_index : The element index of the data packets.
cache_ptr : The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. The routine will write a pointer to this data here. Prior to process exit, a call MUST be made to kwin_free_cache_data, otherwise shared memory segments could remain after the process exits.

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

flag canvas_draw_rgb_image (KWorldCanvas canvas, array_desc *arr_desc, CONST char *slice, unsigned int hdim, unsigned int vdim, unsigned int red_index, unsigned int green_index, unsigned int blue_index, KPixCanvasImageCache *cache_ptr)

This routine will draw a 2-dimensional TrueColour slice of a Karma array onto a world canvas. This slice may be tiled.

Parameters:

canvas : The world canvas.
arr_desc : The array descriptor for the image.
slice : The start of the slice (image) data.
hdim : The dimension index of the horizontal dimension.
vdim : The dimension index of the vertical dimension.
red_index : The element index of the red components.
green_index : The element index of the green components.
blue_index : The element index of the blue components.
cache_ptr : The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. The routine will write a pointer to this data here. Prior to process exit, a call MUST be made to kwin_free_cache_data, otherwise shared memory segments could remain after the process exits.

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

void canvas_draw_point (KWorldCanvas canvas, double x, double y, double value[2])

Draw a single point onto a world canvas.

Parameters:

canvas : The world canvas object.
x : The horizontal world co-ordinate of the point.
y : The vertical world co-ordinate of the point.
value : The data value to use. This is of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_point_p (KWorldCanvas canvas, double x, double y, unsigned long pixel_value)

Draw a single point onto a world canvas.

Parameters:

canvas : The world canvas object.
x : The horizontal world co-ordinate of the point.
y : The vertical world co-ordinate of the point.
pixel_value : The pixel value to use.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_line (KWorldCanvas canvas, double x0, double y0, double x1, double y1, double value[2])

Draw a single line onto a world canvas.

Parameters:

canvas : The world canvas object.
x0 : The horizontal world co-ordinate of the first point.
y0 : The vertical world co-ordinate of the first point.
x1 : The horizontal world co-ordinate of the second point.
y1 : The vertical world co-ordinate of the second point.
value : The data value to use. This is of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_line_p (KWorldCanvas canvas, double x0, double y0, double x1, double y1, unsigned long pixel_value)

Draw a single line onto a world canvas.

Parameters:

canvas : The world canvas object.
x0 : The horizontal world co-ordinate of the first point.
y0 : The vertical world co-ordinate of the first point.
x1 : The horizontal world co-ordinate of the second point.
y1 : The vertical world co-ordinate of the second point.
pixel_value : The pixel value to use.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag canvas_draw_arc (KWorldCanvas canvas, double centre_x, double centre_y, double radius_x, double radius_y, double angle1, double angle2, double rotation, double value[2], flag fill)

Draw an arc onto a world canvas.

Parameters:

canvas : The world canvas object.
centre_x : The horizontal world co-ordinate of the centre of the ellipse.
centre_y : The vertical world co-ordinate of the centre of the ellipse.
radius_x : The horizontal radius in world co-ordinates.
radius_y : The vertical radius in world co-ordinates.
angle1 : See XDrawArc.
angle2 : See XDrawArc.
rotation : The rotation of the arc, in degrees.
value : The complex value to draw the ellipse with. This must be of type K_DCOMPLEX.
fill : If TRUE, the arc is filled, else only the outside is drawn.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag canvas_draw_arc_p (KWorldCanvas canvas, double centre_x, double centre_y, double radius_x, double radius_y, int angle1, int angle2, int rotation, unsigned long pixel_value, flag fill)

Draw an ellipse onto a world canvas.

Parameters:

canvas : The world canvas object.
centre_x : The horizontal world co-ordinate of the centre of the ellipse.
centre_y : The vertical world co-ordinate of the centre of the ellipse.
radius_x : The horizontal radius in world co-ordinates.
radius_y : The vertical radius in world co-ordinates.
angle1 : See XDrawArc.
angle2 : See XDrawArc.
rotation : The rotation of the arc, in units of 1/64 degree.
pixel_value : The pixel value to draw the ellipse with.
fill : If TRUE, the arc is filled, else only the outside is drawn.

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

void canvas_draw_ellipse (KWorldCanvas canvas, double centre_x, double centre_y, double radius_x, double radius_y, double value[2])

Draw an ellipse onto a world canvas.

Parameters:

canvas : The world canvas object.
centre_x : The horizontal world co-ordinate of the centre of the ellipse.
centre_y : The vertical world co-ordinate of the centre of the ellipse.
radius_x : The horizontal radius in world co-ordinates.
radius_y : The vertical radius in world co-ordinates.
value : The complex value to draw the ellipse with. This must be of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_ellipse_p (KWorldCanvas canvas, double centre_x, double centre_y, double radius_x, double radius_y, unsigned long pixel_value)

Draw an ellipse onto a world canvas.

Parameters:

canvas : The world canvas object.
centre_x : The horizontal world co-ordinate of the centre of the ellipse.
centre_y : The vertical world co-ordinate of the centre of the ellipse.
radius_x : The horizontal radius in world co-ordinates.
radius_y : The vertical radius in world co-ordinates.
pixel_value : The pixel value to draw the ellipse with.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_fill_ellipse (KWorldCanvas canvas, double centre_x, double centre_y, double radius_x, double radius_y, double value[2])

Draw a filled ellipse onto a world canvas.

Parameters:

canvas : The world canvas object.
centre_x : The horizontal world co-ordinate of the centre of the ellipse.
centre_y : The vertical world co-ordinate of the centre of the ellipse.
radius_x : The horizontal radius in world co-ordinates.
radius_y : The vertical radius in world co-ordinates.
value : The complex value to fill the ellipse with. This must be of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_fill_ellipse_p (KWorldCanvas canvas, double centre_x, double centre_y, double radius_x, double radius_y, unsigned long pixel_value)

Draw a filled ellipse onto a world canvas.

Parameters:

canvas : The world canvas object.
centre_x : The horizontal world co-ordinate of the centre of the ellipse.
centre_y : The vertical world co-ordinate of the centre of the ellipse.
radius_x : The horizontal radius in world co-ordinates.
radius_y : The vertical radius in world co-ordinates.
pixel_value : The pixel value to fill the ellipse with.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void canvas_convert_ellipse_coords (KWorldCanvas canvas, flag to_world, flag linear, double *centre_x, double *centre_y, double *radius_x, double *radius_y, double *rotation)

Convert co-ordinates for an ellipse.

Parameters:

canvas : The world canvas object.
to_world : If TRUE a pixel->world conversion is performed, else a world->pixel conversion is performed.
linear : If TRUE the co-ordinate conversions are pixel<->linear rather than pixel<->world.
centre_x : The horizontal co-ordinate of the centre of the ellipse.
centre_y : The vertical co-ordinate of the centre of the ellipse.
radius_x : The horizontal radius.
radius_y : The vertical radius.
rotation : The rotation of the arc, in degrees.

Returns: Nothing.
Multithreading Level: Unsafe

flag canvas_fill_polygon (KWorldCanvas canvas, edit_coord *coords, unsigned int num_vertices, double value[2], flag convex)

Draw a filled polygon onto a world canvas.

Parameters:

canvas : The world canvas object.
coords : The array of world co-ordinates of vertices of the polygon.
num_vertices : The number of vertices in the polygon.
value : The complex value to fill the polygon with. This must be of type K_DCOMPLEX.
convex : If TRUE, then the points must form a convex polygon.

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

void canvas_draw_rectangle (KWorldCanvas canvas, double x, double y, double width, double height, double value[2])

Draw a single rectangle onto a world canvas.

Parameters:

canvas : The world canvas object.
x : The horizontal offset of the rectangle.
y : The vertical offset of the rectangle.
width : The width of the rectangle.
height : The height of the rectangle.
value : The data value to use. This is of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_rectangle_p (KWorldCanvas canvas, double x, double y, double width, double height, unsigned long pixel_value)

Draw a single rectangle onto a world canvas.

Parameters:

canvas : The world canvas object.
x : The horizontal offset of the rectangle.
y : The vertical offset of the rectangle.
width : The width of the rectangle.
height : The height of the rectangle.
pixel_value : The pixel value to use.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_fill_rectangle (KWorldCanvas canvas, double x, double y, double width, double height, double value[2])

Fill a single rectangle onto a world canvas.

Parameters:

canvas : The world canvas object.
x : The horizontal offset of the rectangle.
y : The vertical offset of the rectangle.
width : The width of the rectangle.
height : The height of the rectangle.
value : The data value to use. This is of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_fill_rectangle_p (KWorldCanvas canvas, double x, double y, double width, double height, unsigned long pixel_value)

Fill a single rectangle onto a world canvas.

Parameters:

canvas : The world canvas object.
x : The horizontal offset of the rectangle.
y : The vertical offset of the rectangle.
width : The width of the rectangle.
height : The height of the rectangle.
pixel_value : The pixel value to use.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_lines (KWorldCanvas canvas, CONST double *x_array, CONST double *y_array, int num_points, double value[2])

Draw multiple connected lines onto a world canvas.

Parameters:

canvas : The world canvas object.
x_array : The horizontal world co-ordinates of the points. If this is NULL, the routine assumes horizontal co-ordinates equally spaced across the world canvas.
y_array : The vertical world co-ordinates of the points. If this is NULL, the routine assumes vertical co-ordinates equally spaced across the world canvas.
num_points : The number of points. The number of lines drawn is 1 less than this value.
value : The data value to use. This is of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_lines_p (KWorldCanvas canvas, CONST double *x_array, CONST double *y_array, int num_points, unsigned long pixel_value)

Draw multiple connected lines onto a world canvas.

Parameters:

canvas : The world canvas object.
x_array : The horizontal world co-ordinates of the points. If this is NULL, the routine assumes horizontal co-ordinates equally spaced across the world canvas.
y_array : The vertical world co-ordinates of the points. If this is NULL, the routine assumes vertical co-ordinates equally spaced across the world canvas.
num_points : The number of points. The number of lines drawn is 1 less than this value.
pixel_value : The pixel value to use.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_segments (KWorldCanvas canvas, CONST double *x0, CONST double *y0, CONST double *x1, CONST double *y1, int num_segments, double value[2])

Draw multiple disjoint lines onto a world canvas.

Parameters:

canvas : The world canvas object.
x0 : The horizontal start co-ordinates of the segments.
y0 : The vetical start co-ordinates of the segments.
x1 : The horizontal end co-ordinates of the segments.
y1 : The vetical end co-ordinates of the segments.
num_segments : The number of segments.
value : The data value to use. This is of type K_DCOMPLEX.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_draw_segments_p (KWorldCanvas canvas, CONST double *x0, CONST double *y0, CONST double *x1, CONST double *y1, int num_segments, unsigned long pixel_value)

Draw multiple disjoint lines onto a world canvas.

Parameters:

canvas : The world canvas object.
x0 : The horizontal start co-ordinates of the segments.
y0 : The vetical start co-ordinates of the segments.
x1 : The horizontal end co-ordinates of the segments.
y1 : The vetical end co-ordinates of the segments.
num_segments : The number of segments.
pixel_value : The pixel value to use.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_init_win_scale (struct win_scale_type *win_scale, unsigned int magic_number)

This routine will initialise a window scaling structure with sensible values. This routine may be used prior to calling .

Parameters:

win_scale : A pointer to the window scaling structure.
magic_number : The value of this must be K_WIN_SCALE_MAGIC_NUMBER.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_use_log_scale (KWorldCanvas canvas, flag x_log, flag y_log)

This routine will enable logarithmic scaling of the co-ordinates for a world canvas object.

Parameters:

canvas : The world canvas object.
x_log : If TRUE, the horizontal co-ordinates will be scaled logarithmically, else they will be scaled linearly.
y_log : If TRUE the vertical co-ordinates should be scaled logarithmically, else they will be scaled linearly.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void canvas_use_astro_transform (KWorldCanvas canvas, KwcsAstro ap)

Use astronomical sky projections for a canvas.

Parameters:

canvas : The world canvas object.
ap : The KwcsAstro object. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

flag canvas_create_stroke_instruction (KWorldCanvas canvas, double x0, double y0, double x1, double y1, unsigned int brush_width, double value[2], KImageEditList ilist)

This routine will create a 2-dimensional edit stroke instruction, according to the specification in the iedit package and will append it to a managed edit list.

Parameters:

canvas : The world canvas which contains the world co-ordinate system.
x0 : The starting horizontal co-ordidinate of the stroke.
y0 : The starting vertical co-ordidinate of the stroke.
x1 : The ending horizontal co-ordidinate of the stroke.
y1 : The ending vertical co-ordidinate of the stroke.
brush_width : The width of the stroke (in canvas pixels). This must be at least 1.
value : The data value in the stroke instruction. This must be of type K_DCOMPLEX.
ilist : The managed edit list.

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

Prototype Functions

void canvas_PROTO_refresh_func (KWorldCanvas canvas, int width, int height, struct win_scale_type *win_scale, Kcolourmap cmap, flag cmap_resize, void **info, PostScriptPage pspage, unsigned int num_areas, KPixCanvasRefreshArea *areas, flag *honoured_areas)

This routine is a refresh event consumer for a world canvas.

Parameters:

canvas : The world canvas being refreshed.
width : The width of the canvas in pixels.
height : The height of the canvas in pixels.
win_scale : A pointer to the window scaling information.
cmap : The colourmap associated with the canvas.
cmap_resize : TRUE if the refresh function was called as a result of a colourmap resize, else FALSE.
info : A pointer to the arbitrary canvas information pointer.
pspage : If not NULL, the PostScriptPage object the refresh is redirected to.
num_areas : The number of areas that need to be refreshed. If this is 0 then the entire pixel canvas needs to be refreshed.
areas : The list of areas that need to be refreshed. Note that these areas are given in pixel co-ordinates.
honoured_areas : If the value TRUE is written here it is assumed the routine honoured the list of refresh areas and did not write outside these areas and hence the list of areas will be passed to subsequent registered refresh routines. If FALSE is written here (or nothing is written here), implying the routine refreshed the entire canvas, subsequent refresh routines will be told to refresh the entire canvas.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_PROTO_size_control_func (KWorldCanvas canvas, int width, int height, struct win_scale_type *win_scale, void **info, flag *boundary_clear)

This routine will modify the window scaling information for a world canvas. While this routine is running, colourmap resize events are ignored. Hence this routine may safely cause the associated Kcolourmap object to be resized.

Parameters:

canvas : The world canvas object.
width : The width of the canvas in pixels.
height : The height of the canvas in pixels.
win_scale : The window scaling information. This may be modified.
info : A pointer to the arbitrary canvas information pointer.
boundary_clear : If the value TRUE is written here then the canvas_resize routine will attempt to clear only the boundary between the pixel canvas and the world canvas. If the value FALSE is written here or nothing is written here, the canvas_resize routine will clear the entire pixel canvas as appropriate.

Returns: Nothing.
Multithreading Level: Unsafe

flag canvas_PROTO_position_func (KWorldCanvas canvas, double x, double y, unsigned int event_code, void *e_info, void **f_info, double x_lin, double y_lin, int x_pix, int y_pix)

This routine is a position event consumer for a world canvas.

Parameters:

canvas : The canvas on which the event occurred.
x : The horizontal world co-ordinate of the event.
y : The vertical world co-ordinate of the event.
event_code : The arbitrary event code.
e_info : A pointer to arbitrary event information.
f_info : A pointer to an arbitrary function information pointer.
x_lin : The horizontal linear world co-ordinate prior to the transform function being called.
y_lin : The vertical linear world co-ordinate prior to the transform function being called.
x_pix : The horizontal pixel co-ordinate.
y_pix : The vertical pixel co-ordinate.

Returns: TRUE if the event was consumed, else FALSE indicating that the event is still to be processed.
Multithreading Level: Unsafe
Note:

The world co-ordinate values will have been transformed by the registered transform function (see canvas_register_transform_func).

flag canvas_PROTO_coord_convert_func (KWorldCanvas canvas, unsigned int num_coords, CONST double *xin, CONST double *yin, double *xout, double *yout, flag to_world, void **info)

This routine will convert between world co-ordinates and pixel co-ordinates for a world canvas.

Parameters:

canvas : The canvas.
num_coords : The number of co-ordinates to transform.
xin : The array of input horizontal co-ordinates.
yin : The array of input vertical co-ordinates.
xout : The array of output horizontal co-ordinates are written here.
yout : The array of output vertical co-ordinates are written here.
to_world : If TRUE, then a pixel to world co-ordinate transform is required, else a world to pixel co-ordinate transform is required.
info : A pointer to the arbitrary canvas information pointer.

Returns: TRUE if the conversion was completed, else FALSE indicating that the default conversions should be used.
Multithreading Level: Unsafe

void canvas_PROTO_coord_transform_func (KWorldCanvas canvas, unsigned int num_coords, double *x, flag x_to_linear, double *y, flag y_to_linear, double left_x, double right_x, double bottom_y, double top_y, void **info)

This routine will transform between linear and non-linear world co-ordinates.

Parameters:

canvas : The canvas on which the event occurred.
num_coords : The number of co-ordinates to transform.
x : The array of horizontal world co-ordinates. These are modified.
x_to_linear : If TRUE, then the horizontal co-ordinates are converted from non-linear to linear, else they are converted from linear to non-linear.
y : The array of vertical world co-ordinates. These are modified.
y_to_linear : If TRUE, then the vertical co-ordinates are converted from non-linear to linear, else they are converted from linear to non-linear.
info : A pointer to the arbitrary transform information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

Tables

canvas_ATTRIBUTES

Name Get Type Set Type Meaning

CANVAS_ATT_END End of varargs list
CANVAS_ATT_X_OFFSET int * int X offset (pixels)
CANVAS_ATT_Y_OFFSET int * int Y offset (pixels)
CANVAS_ATT_X_PIXELS int * int X size (pixels)
CANVAS_ATT_Y_PIXELS int * int Y size (pixels)
CANVAS_ATT_BLANK_PIXEL unsigned long * unsigned long Blank pixel
CANVAS_ATT_MIN_SAT_PIXEL unsigned long * unsigned long Min saturation pixel
CANVAS_ATT_MAX_SAT_PIXEL unsigned long * unsigned long Max saturation pixel
CANVAS_ATT_LEFT_X double * double Left X (linear)
CANVAS_ATT_RIGHT_X double * double Right X (linear)
CANVAS_ATT_BOTTOM_Y double * double Bottom Y (linear)
CANVAS_ATT_TOP_Y double * double Top Y (linear)
CANVAS_ATT_VALUE_MIN double * double Minimum value
CANVAS_ATT_VALUE_MAX double * double Maximum value
CANVAS_ATT_ISCALE_FUNC flag (*) () Intensity scale function
CANVAS_ATT_ISCALE_FREE_FUNC void (*) () Free function
CANVAS_ATT_ISCALE_INFO void ** void iscale info
CANVAS_ATT_AUTO_MIN_SAT flag * flag Auto min-sat
CANVAS_ATT_AUTO_MAX_SAT flag * flag Auto max-sat

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services

Name	Get Type	Set Type	Meaning

CANVAS_ATT_END			End of varargs list
CANVAS_ATT_X_OFFSET	int *	int	X offset (pixels)
CANVAS_ATT_Y_OFFSET	int *	int	Y offset (pixels)
CANVAS_ATT_X_PIXELS	int *	int	X size (pixels)
CANVAS_ATT_Y_PIXELS	int *	int	Y size (pixels)
CANVAS_ATT_BLANK_PIXEL	unsigned long *	unsigned long	Blank pixel
CANVAS_ATT_MIN_SAT_PIXEL	unsigned long *	unsigned long	Min saturation pixel
CANVAS_ATT_MAX_SAT_PIXEL	unsigned long *	unsigned long	Max saturation pixel
CANVAS_ATT_LEFT_X	double *	double	Left X (linear)
CANVAS_ATT_RIGHT_X	double *	double	Right X (linear)
CANVAS_ATT_BOTTOM_Y	double *	double	Bottom Y (linear)
CANVAS_ATT_TOP_Y	double *	double	Top Y (linear)
CANVAS_ATT_VALUE_MIN	double *	double	Minimum value
CANVAS_ATT_VALUE_MAX	double *	double	Maximum value
CANVAS_ATT_ISCALE_FUNC		flag (*) ()	Intensity scale function
CANVAS_ATT_ISCALE_FREE_FUNC		void (*) ()	Free function
CANVAS_ATT_ISCALE_INFO	void **	void	iscale info
CANVAS_ATT_AUTO_MIN_SAT	flag *	flag	Auto min-sat
CANVAS_ATT_AUTO_MAX_SAT	flag *	flag	Auto max-sat