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_listDraw a list of edit objects to a world canvas.
canvas_draw_edit_objectDraw one edit object to a world canvas.
canvas_createCreate world canvas.
canvas_register_refresh_funcRegister world canvas refresh callback.
canvas_register_size_control_funcRegister size control callback.
canvas_register_position_event_funcRegister position event callback.
canvas_get_attributesGet canvas attributes.
canvas_set_attributesSet canvas attributes.
canvas_resizeResize a world canvas.
canvas_specifySet specification information for a world canvas.
canvas_get_specificationGet specification information for a world canvas.
canvas_convert_to_canvas_coordsConvert pixel co-ordinates to world co-ordinates.
canvas_convert_from_canvas_coordsConvert world co-ordinates to pixel co-ordinates.
canvas_register_coords_convert_funcRegister co-ordinate conversion function.
canvas_coords_transformTransform world co-ordinates.
canvas_register_transforms_funcRegister non-linear co-ordinate transformation function.
canvas_get_pixcanvasGet the underlying pixel canvas of a world canvas.
canvas_get_colourGet (possibly allocating) a colourcell for a canvas.
canvas_set_dressingSet dressing parameters for a world canvas.
canvas_get_dressingGet dressing parameters for a world canvas.
canvas_sequence_dressing_refreshSet order in which dressing is refreshed.
canvas_draw_dressingDraw the dressing (axes, etc.) for a world canvas.
canvas_get_cmapGet the Kcolourmap object associated with a world canvas.
canvas_draw_imageDraw a PseudoColour image onto a world canvas.
canvas_draw_rgb_imageDraw a TrueColour image onto a world canvas.
canvas_draw_pointDraw a single point onto a world canvas.
canvas_draw_point_pDraw a single point onto a world canvas.
canvas_draw_lineDraw a single line onto a world canvas.
canvas_draw_line_pDraw a single line onto a world canvas.
canvas_draw_arcDraw an arc onto a world canvas.
canvas_draw_arc_pDraw an ellipse onto a world canvas.
canvas_draw_ellipseDraw an ellipse onto a world canvas.
canvas_draw_ellipse_pDraw an ellipse onto a world canvas.
canvas_fill_ellipseDraw a filled ellipse onto a world canvas.
canvas_fill_ellipse_pDraw a filled ellipse onto a world canvas.
canvas_convert_ellipse_coordsConvert co-ordinates for an ellipse.
canvas_fill_polygonDraw a filled polygon onto a world canvas.
canvas_draw_rectangleDraw a single rectangle onto a world canvas.
canvas_draw_rectangle_pDraw a single rectangle onto a world canvas.
canvas_fill_rectangleFill a single rectangle onto a world canvas.
canvas_fill_rectangle_pFill a single rectangle onto a world canvas.
canvas_draw_linesDraw multiple connected lines onto a world canvas.
canvas_draw_lines_pDraw multiple connected lines onto a world canvas.
canvas_draw_segmentsDraw multiple disjoint lines onto a world canvas.
canvas_draw_segments_pDraw multiple disjoint lines onto a world canvas.
canvas_init_win_scaleInitialise win_scale structure.
canvas_use_log_scaleEnable logarithmic scaling for a world canvas.
canvas_use_astro_transformUse astronomical sky projections for a canvas.
canvas_create_stroke_instructionCreate an image editing stroke instruction.

Prototype Functions

canvas_PROTO_refresh_funcRefresh event callback.
canvas_PROTO_size_control_funcSize control callback.
canvas_PROTO_position_funcPosition event callback.
canvas_PROTO_coord_convert_funcCo-ordinate conversion callback.
canvas_PROTO_coord_transform_funcCo-ordinate transformation callback.

Tables

canvas_ATTRIBUTESList 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:

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:

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:

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


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:

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:

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:

Returns: A KCallbackFunc object.
Multithreading Level: Unsafe


void canvas_get_attributes (KWorldCanvas canvas, ...)

Get canvas attributes.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


flag canvas_set_attributes (KWorldCanvas canvas, ...)

Set canvas attributes.

Parameters:

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:

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:

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


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:

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:

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:

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:

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:

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:

Returns: Nothing.
Multithreading Level: Unsafe


KPixCanvas canvas_get_pixcanvas (KWorldCanvas canvas)

Get the underlying pixel canvas of a world canvas.

Parameters:

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:

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


void canvas_set_dressing (KWorldCanvas canvas, ...)

Set dressing parameters for a world canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


void canvas_get_dressing (KWorldCanvas canvas, ...)

Get dressing parameters for a world canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


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:

Returns: Nothing.
Multithreading Level: Unsafe


void canvas_draw_dressing (KWorldCanvas canvas)

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

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


Kcolourmap canvas_get_cmap (KWorldCanvas canvas)

Get the Kcolourmap object associated with a world canvas.

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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


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:

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:

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