# 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_destroy | Destroy a world canvas.
canvas_register_precompute_func | Register a refresh precompute callback.
canvas_register_refresh_func | Register world canvas refresh callback.
canvas_register_size_control_func | Register size control callback.
canvas_register_legend_reservation_func | Register legend space reservation callback.
canvas_register_position_event_func | Register position event callback.
canvas_register_destroy_func | Register destroy callback.
canvas_get_attributes | Get canvas attributes.
canvas_set_attributes | Set canvas attributes.
canvas_resize | Resize a world canvas.
canvas_refresh_if_visible | Refresh a world canvas if it is visible.
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_register_transforms_free_func | Register non-linear co-ordinate transformation free 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_warp_pointer | Warp the pointer to a new location.
canvas_test_for_boundary | Test if co-ordinates lie within the canvas boundary.
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_get_margins | Get margin space for a canvas.
canvas_associate_object | Associate an object with a world canvas.
canvas_get_associated_object | Get an associated object for 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_track_compute | Compute track strings.
canvas_draw_circle_marker | Draw a circle marker.
canvas_draw_line_marker | Draw a line marker.
canvas_create_stroke_instruction | Create an image editing stroke instruction.
canvas_zoom_handle_keys | Install callbacks to handle zoom key bindings for a world canvas.
canvas_zoom_handle_mouse | Install callbacks to handle left mouse zooming for world canvas.

#### Prototype Functions

canvas_PROTO_precompute_func | Precompute event callback.
canvas_PROTO_refresh_func | Refresh event callback.
canvas_PROTO_size_control_func | Size control callback.
canvas_PROTO_position_func | Position event callback.
canvas_PROTO_destroy_func | Process a destroy event on a world canvas.
canvas_PROTO_coord_convert_func | Co-ordinate conversion callback.
canvas_PROTO_coord_transform_func | Co-ordinate transformation callback.
canvas_PROTO_legend_reservation_func | Legend space reservation 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.
- The world canvas will be automatically destroyed if the pixel canvas is destroyed.

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

void canvas_destroy (KWorldCanvas canvas)

Destroy a world canvas.

Parameters:

- canvas : The world canvas.

Returns: Nothing.
Multithreading Level: Unsafe

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

KCallbackFunc canvas_register_precompute_func (KWorldCanvas canvas, void (*precompute_func) (), void *info)

This routine will register a refresh precompute function for a workd canvas. The refresh precompute function will be called whenever the contents of the canvas need to be redrawn, prior to any drawing operations commencing. The callback must not perform any drawing operations: any drawing operations may be performed by the ordinary refresh callbacks. Many precompute functions may be registered per canvas. The first function registered is the first function called upon refresh.

Parameters:

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

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

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

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

KCallbackFunc canvas_register_legend_reservation_func (KWorldCanvas canvas, void (*func) (), void *info)

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

Parameters:

- canvas : The world canvas.
- func : The function that is called when the canvas needs to be refreshed. The prototype function is canvas_PROTO_legend_reservation_func.
- info : The initial arbitrary function information pointer.

Returns: A KCallbackFunc object.
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

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

KCallbackFunc canvas_register_destroy_func (KWorldCanvas canvas, flag wc_only, void (*func) (), void *info)

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

Parameters:

- canvas : The world canvas.
- wc_only : If TRUE, the function is only called for a destroy of the world canvas; if the pixel canvas is being destroyed, the function is not called. If FALSE, the function is called regardless of whether the pixel canvas is being destroyed.
- func : The function that is called when the canvas is destroyed. The prototype function is canvas_PROTO_destroy_func.
- info : The arbitrary function information pointer.

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

- All functions registered with wc_only TRUE are called before those registered with wc_only FALSE.

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

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

flag canvas_refresh_if_visible (KWorldCanvas canvas, flag always_clear)

Refresh a world canvas if it is visible.

Parameters:

- canvas : The KWorldCanvas object. This may be NULL.
- always_clear : If TRUE, the canvas is always cleared before refreshing, else only parts are cleared.

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 linear 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

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

void canvas_register_transforms_free_func ( KWorldCanvas canvas, void (*func) () )

Register non-linear co-ordinate transformation free function.

Parameters:

- canvas : The world canvas object.
- func : The function that is called when transform data is to be freed.

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.

flag 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: TRUE if changes were made, else FALSE.
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

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

flag canvas_warp_pointer (KWorldCanvas canvas, double x, double y, flag linear, flag discard)

Warp the pointer to a new location.

Parameters:

- x : The horizontal position to warp to.
- y : The vertical position to warp to.
- linear : If TRUE, input co-orindates are in linear co-ordinates.
- discard : If TRUE, any pending events are discarded.

Returns: TRUE if warping is supported, else FALSE.
Multithreading Level: Unsafe

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

flag canvas_test_for_boundary (KWorldCanvas canvas, unsigned int num_coords, CONST double *x, CONST double *y)

Test if co-ordinates lie within the canvas boundary.

Parameters:

- canvas : The world canvas object.
- x : The array of horizontal world co-ordinates.
- y : The array of vertical world co-ordinates.
- num_coords : The number of co-ordinates to test.

Returns: TRUE if any co-ordinates lie within the boundary, else FALSE.
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 : The start of the arc, in units of degrees, relative to +X. Increasing positive values are anticlockwise.
- angle2 : The end of the arc, in units of degrees, relative to +X. Increasing positive values are anticlockwise.
- rotation : The rotation of the arc, 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 anticlockwise from the right.
- 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, double angle1, double angle2, double 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 : The start of the arc, in units of degrees, relative to +X. Increasing positive values are anticlockwise.
- angle2 : The end of the arc, in units of degrees, relative to +X. Increasing positive values are anticlockwise.
- rotation : The rotation of the arc, 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 anticlockwise from the right.
- 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

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

void canvas_get_margins (KWorldCanvas canvas, int *left_margin, int *right_margin, int *bottom_margin, int *top_margin)

Get margin space for a canvas.

Parameters:

- canvas : The world canvas.
- left_margin : The number of pixels required for the left margin is written here.
- right_margin : The number of pixels required for the right margin is written here.
- bottom_margin : The number of pixels required for the bottom margin is written here.
- top_margin : The number of pixels required for the top margin is written here.

Returns: Nothing.
Multithreading Level: Unsafe

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

void canvas_associate_object (KWorldCanvas canvas, CONST void *key, CONST void *object, flag replace)

Associate an object with a world canvas.

Parameters:

- canvas : The world canvas.
- key : The key for the associated data object.
- object : The object pointer.
- flag : If TRUE, an existing object with the same key is replaced.

Returns: Nothing. On failure, the process aborts.
Multithreading Level: Unsafe

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

void * canvas_get_associated_object (KWorldCanvas canvas, CONST void *key)

Get an associated object for a world canvas.

Parameters:

- canvas : The world canvas.
- key : The key to search for.

Returns: A pointer to the associated object. NULL is returned if the key is not found.
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 <canvas_create>.

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

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

void canvas_track_compute (KWorldCanvas canvas, double x, double y, double x_lin, double y_lin, char world_string[STRING_LENGTH], char extra_string[STRING_LENGTH])

Compute track strings.

Parameters:

- canvas : The world canvas.
- x : The horizontal world co-ordinate of the event.
- y : The vertical world co-ordinate of the event.
- x_lin : The horizontal linear co-ordinate.
- y_lin : The vertical linear co-ordinate.
- world_string : The world co-ordinates and restriction information will be written here.
- extra_string : Extra information is written here. This may be NULL if world_string is also NULL.

Returns: Nothing.
Multithreading Level: Unsafe

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

void canvas_draw_circle_marker (KWorldCanvas canvas, KPixCanvasRefreshArea *area, double x, double y)

Draw a circle marker.

Parameters:

- canvas : The world canvas to draw to.
- area : State information for undrawing the old marker. This is updated.
- x : The horizontal linear co-ordinate of the marker.
- y : The vertical linear co-ordinate of the marker.

Returns: Nothing.
Multithreading Level: Unsafe

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

void canvas_draw_line_marker (KWorldCanvas canvas, KPixCanvasRefreshArea *area, double lpos, flag pos_is_vertical)

Draw a line marker.

Parameters:

- canvas : The world canvas to draw to.
- area : State information for undrawing the old marker. This is updated.
- lpos : The linear co-ordinate of the marker.
- pos_is_vertical : If TRUE, the position is a vertical co-ordinate and thus the marker will be horizontal, else the position is a horizontal co-ordinate and the marker will be vertical.

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

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

KCallbackFunc canvas_zoom_handle_keys (KWorldCanvas canvas, CONST KWorldCanvasLimits *limits)

Install callbacks to handle zoom key bindings for a world canvas.

Parameters:

- canvas : The world canvas object.
- limits : The canvas limits. This is referenced when the appropriate keys are pressed.

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe

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

KPixCanvasEditorContext canvas_zoom_handle_mouse (KWorldCanvas canvas, CONST KWorldCanvasLimits *limits)

Install callbacks to handle left mouse zooming for world canvas.

Parameters:

- canvas : The world canvas object.
- limits : The canvas limits. This is referenced when the appropriate keys are pressed.

Returns: The KPixCanvasEditorContext created for rubber-banding. Extra key bindings may be added to this context.
Multithreading Level: Unsafe

## Prototype Functions

void canvas_PROTO_precompute_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)

This routine processes a precompute event for a world canvas.

Parameters:

- canvas : The world canvas.
- 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. The data are only valid during this callback.
- cmap : The canvas colourmap.
- cmap_resize : If TRUE, the refresh is due to a colourmap resize.
- info : A pointer to the arbitrary information pointer.
- pspage : The PostScriptPage object. If this is NULL, the refresh is *not* destined for a PostScript page.
- 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.

Returns: Nothing.
Multithreading Level: Unsafe

void canvas_PROTO_refresh_func (KWorldCanvas canvas, int width, int height, CONST 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. The data are only valid during this callback.
- 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, flag *force)

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 after removing the space consumed by the dressing.
- height : The height of the canvas in pixels after removing the space consumed by the dressing.
- 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.
- force : If the value TRUE is written here, the location is forced. If the value FALSE is written here, or nothing is written here, the canvas boundary may be centred.

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_transforms_func).

void canvas_PROTO_destroy_func (void *info)

Process a destroy event on a world canvas.

Parameters:

- info : An arbitrary function information pointer.

Returns: Nothing.
Multithreading Level: Unsafe

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

This routine will convert between linear 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_linear : If TRUE, then a pixel to linear co-ordinate transform is required, else a linear 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

void canvas_PROTO_legend_reservation_func (KWorldCanvas canvas, void **info, int *left_margin, int *right_margin, int *bottom_margin, int *top_margin)

This routine reserves space for a legend.

Parameters:

- canvas : The canvas on which the event occurred.
- info : A pointer to the arbitrary function information pointer.
- left_margin : The number of pixels required for the left margin must be written here. If nothing is written, 0 is assumed.
- right_margin : The number of pixels required for the right margin must be written here. If nothing is written, 0 is assumed.
- bottom_margin : The number of pixels required for the bottom margin must be written here. If nothing is written, 0 is assumed.
- top_margin : The number of pixels required for the top margin must be written here. If nothing is written, 0 is assumed.

Returns: Nothing.
Multithreading Level: Unsafe

## Tables

canvas_ATTRIBUTES List of attributes for KWorldCanvas objects

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