The "kwin" Package

These routines are meant to provide a high level mechanism to create and manipulate pixel canvases. After creating a pixel canvas from some graphics system primitive object, the canvas may be manipulated without the need to use the underlying graphics system interface. This renders code much more portable.

Library: karmagraphics
Link With: -lkarmagraphics

Functions

kwin_create_xCreate a pixel canvas from an X window.
kwin_set_gc_xSet Graphics Context for an X-based pixel canavas.
kwin_get_gc_xGet Graphics Context for an X-based pixel canavas.
kwin_create_genericCreate generic pixel canvas.
kwin_create_childCreate a child pixel canvas.
kwin_register_refresh_funcRegister a refresh callback.
kwin_register_position_event_funcRegister position event callback.
kwin_resizeResize a pixel canvas.
kwin_refresh_if_visibleRefresh a pixel canvas if it is visible.
kwin_partial_refreshPerform a partial refresh of a pixel canvas.
kwin_process_position_eventProcess position event on a pixel canvas.
kwin_get_attributesGet the attributes for a pixel canvas.
kwin_set_attributesSet the attributes for a pixel canvas.
kwin_clearClear a rectangular portion of a pixel canvas.
kwin_draw_pc_imageDraw PseudoColour image to a pixel canvas.
kwin_draw_rgb_imageDraw TrueColour image to a pixel canvas.
kwin_draw_cached_imageDraw cached image to a pixel canvas.
kwin_draw_cached_subimagesDraw previously computed cached subimages.
kwin_draw_pointDraw a single point onto a pixel canvas.
kwin_draw_pointsDraw multiple points onto a pixel canvas.
kwin_draw_lineDraw a single line onto a pixel canvas.
kwin_draw_linesDraw multiple connected lines onto a pixel canvas.
kwin_fill_ellipseDraw a filled ellipse onto a pixel canvas.
kwin_fill_polygonDraw a filled polygon onto a pixel canvas.
kwin_draw_stringDraw a string onto a pixel canvas.
kwin_draw_rectangleDraw a single rectangle onto a pixel canvas.
kwin_fill_rectangleDraw a single filled rectangle onto a pixel canvas.
kwin_draw_arcDraw an arc onto a pixel canvas.
kwin_draw_ellipseDraw an ellipse onto a pixel canvas.
kwin_draw_ellipsesDraw multiple ellipses onto a pixel canvas.
kwin_draw_ellipses_TRANSITIONDraw multiple ellipses onto a pixel canvas.
kwin_fill_ellipsesDraw multiple filled ellipses onto a pixel canvas.
kwin_fill_ellipses_TRANSITIONDraw multiple filled ellipses onto a pixel canvas.
kwin_draw_segmentsDraw multiple disjoint lines onto a pixel canvas.
kwin_get_sizeGet the size of a pixel canvas.
kwin_free_cache_dataFree some cache data allocated by kwin_draw_pc_image.
kwin_convert_to_canvas_coordConvert low-level co-ordinates to pixel co-ordinates.
kwin_convert_from_canvas_coordConvert pixel co-ordinates to low-level co-ordinates.
kwin_get_colourGet (possibly allocate) a colourcell for a canvas.
kwin_get_pixel_RGB_valuesGet RGB components of pixel values.
kwin_load_fontLoad a font for later use.
kwin_get_string_sizeDetermine the size of a string.
kwin_hersey_draw_stringDraw string using Hershey (stroke) font.
kwin_open_gl_test_availableTest if the GLX extension is supported for a display.
kwin_open_gl_test_stereoTest if a particular visual can display stereo.
kwin_write_psRefresh a pixel canvas onto a PostScriptPage object.
kwin_xgl_test_stereoTest if stereo supported using XGL.
kwin_xgl_create_stereoCreate a stereo pixel canvas using XGL.

Prototype Functions

kwin_PROTO_refresh_funcProcess a refresh event for a pixel canvas.
kwin_PROTO_position_funcProcess a position event on a pixel canvas.
kwin_PROTO_iscale_funcIntensity scale function.

Tables

kwin_ATTRIBUTESList of attributes for KPixCanvas objects
kwin_STRING_ATTRIBUTESList of attributes for KPixCanvasFont string
kwin_XGL_STATUSList of XGL stereo support types


Functions


KPixCanvas kwin_create_x (Display *display, Window window, GC gc, int xoff, int yoff, int width, int height)

This routine will create a pixel canvas, ready for drawing, from an X window. Note that the origin of a KPixCanvas is the upper-left corner.

Parameters:

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


void kwin_set_gc_x (KPixCanvas canvas, GC gc)

This routine will register a new Graphics Context to be used when drawing into the pixel canvas. Subsequent drawing operations will use the new Graphics Context.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe
Note:


GC kwin_get_gc_x (KPixCanvas canvas)

This routine will get the Graphics Context used when drawing into the pixel canvas. If the Graphics Context is modified, it should be registered prior to drawing on the canvas by calling kwin_set_gc_x.

Parameters:

Returns: The Graphics Context.
Multithreading Level: Unsafe
Note:


EXPERIMENTAL FUNCTION: subject to change without notice

KPixCanvas kwin_create_generic (void *info, int xoff, int yoff, int width, int height, unsigned int depth, unsigned int visual, flag visible, KPixFuncDrawPoint draw_point, KPixFuncCreateChild create_child, KPixFuncClearArea clear_area, ...)

This routine will create a pixel canvas. The interface to this routine is generic. Note that the origin of a KPixCanvas is the upper-left corner.

Parameters:

Returns: A pixel canvas on success, else NULL.
Multithreading Level: Unsafe


KPixCanvas kwin_create_child (KPixCanvas parent, int xoff, int yoff, int width, int height, flag absorb_events)

This routine will create a pixel canvas, ready for drawing, within an existing pixel canvas. The new pixel canvas is a child of the parent pixel canvas. The child *does not* receive refresh events from the parent, it *does* receive position events from the parent, provided these events lie within the child's boundaries. For X-based graphics, a copy of the Graphics Context is made for the child. Note that the origin of a KPixCanvas is the upper-left corner.

Parameters:

Returns: A pixel canvas on success, else NULL.
Multithreading Level: Unsafe


KCallbackFunc kwin_register_refresh_func (KPixCanvas canvas, void (*refresh_func) (), void *info)

This routine will register a refresh function for a pixel 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


KCallbackFunc kwin_register_position_event_func (KPixCanvas canvas, flag (*func) (), void *f_info)

This routine will register a position event function for a pixel 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. On failure, the process aborts.
Multithreading Level: Unsafe


flag kwin_resize (KPixCanvas canvas, flag clear, int xoff, int yoff, int width, int height)

This routine will register a resize in the pixel canvas size. This will cause any refresh routines registered for the canvas to be called. This routine is meant to be called by an X event handler for the underlying window, however the routine is available for all graphics systems.

Parameters:

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


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_refresh_if_visible (KPixCanvas canvas, flag clear)

Refresh a pixel canvas if it is visible.

Parameters:

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


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_partial_refresh (KPixCanvas canvas, unsigned int num_areas, KPixCanvasRefreshArea *areas, flag clear_all)

Perform a partial refresh of a pixel canvas.

Parameters:

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


flag kwin_process_position_event (KPixCanvas canvas, int x, int y, flag clip, unsigned int event_code, void *event_info)

This routine will process (inject) a position event on the lower level object (parent: i.e. X window) for a pixel canvas. This event is processed with all position event consumer routines until one successfully consumes the event.

Parameters:

Returns: TRUE if the event was consumed, else FALSE.
Multithreading Level: Unsafe


void kwin_get_attributes (KPixCanvas canvas, ...)

Get the attributes for a pixel canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


void kwin_set_attributes (KPixCanvas canvas, ...)

Set the attributes for a pixel canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


flag kwin_clear (KPixCanvas canvas, int x, int y, int width, int height)

Clear a rectangular portion of a pixel canvas.

Parameters:

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


flag kwin_draw_pc_image (KPixCanvas canvas, int x_off, int y_off, int x_pixels, int y_pixels, CONST char *slice, CONST uaddr *hoffsets, CONST uaddr *voffsets, unsigned int width, unsigned int height, unsigned int type, unsigned int conv_type, unsigned int num_pixels, unsigned long *pixel_values, unsigned long blank_pixel,unsigned long min_sat_pixel, unsigned long max_sat_pixel, double i_min, double i_max, flag (*iscale_func) (), void *iscale_info, KPixCanvasImageCache *cache_ptr)

This routine will draw a 2-dimensional slice of a Karma array onto a pixel canvas. This slice may be tiled. The slice is a PseudoColour image.

Parameters:

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


flag kwin_draw_rgb_image (KPixCanvas canvas, int x_off, int y_off, int x_pixels, int y_pixels, CONST unsigned char *red_slice, CONST unsigned char *green_slice, CONST unsigned char *blue_slice, CONST uaddr *hoffsets, CONST uaddr *voffsets, unsigned int width, unsigned int height, KPixCanvasImageCache *cache_ptr)

This routine will draw a 2-dimensional slice of a Karma array onto a pixel canvas. This slice may be tiled. The slice is a RGB image.

Parameters:

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


flag kwin_draw_cached_image (KPixCanvasImageCache cache, int x_off, int y_off)

This routine will draw a previously computed image cache data (computed by kwin_draw_pc_image) onto the canvas on which the original image was drawn.

Parameters:

Returns: TRUE on success if there is valid cache data, else FALSE indicating that the image must be recomputed and drawn using kwin_draw_pc_image.
Multithreading Level: Unsafe


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_draw_cached_subimages (KPixCanvasImageCache cache, int x_off, int y_off, unsigned int num_areas, KPixCanvasRefreshArea *areas)

This routine will draw sections of a previously computed image cache data (computed by kwin_draw_pc_image) onto the canvas on which the original image was drawn.

Parameters:

Returns: TRUE on success if there is valid cache data, else FALSE indicating that the image must be recomputed and drawn using kwin_draw_pc_image.
Multithreading Level: Unsafe


flag kwin_draw_point (KPixCanvas canvas, double x, double y, unsigned long pixel_value)

Draw a single point onto a pixel canvas.

Parameters:

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


flag kwin_draw_points (KPixCanvas canvas, double *x_array, double *y_array, unsigned int num_points, unsigned long pixel_value)

Draw multiple points onto a pixel canvas.

Parameters:

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


flag kwin_draw_line (KPixCanvas canvas, double x0, double y0, double x1, double y1, unsigned long pixel_value)

Draw a single line onto a pixel canvas.

Parameters:

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


flag kwin_draw_lines (KPixCanvas canvas, int *x_array, int *y_array, int num_points, unsigned long pixel_value)

Draw multiple connected lines onto a pixel canvas.

Parameters:

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


flag kwin_fill_ellipse (KPixCanvas canvas, double cx, double cy, double rx, double ry, unsigned long pixel_value)

Draw a filled ellipse onto a pixel canvas.

Parameters:

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


flag kwin_fill_polygon (KPixCanvas canvas, int *point_x, int *point_y, unsigned int num_vertices, unsigned long pixel_value, flag convex)

Draw a filled polygon onto a pixel canvas.

Parameters:

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


flag kwin_draw_string (KPixCanvas canvas, double x, double y, CONST char *string, unsigned long pixel_value, flag clear_under)

This routine will draw a NULL terminated string onto a pixel canvas, using the default font for the canvas.

Parameters:

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


flag kwin_draw_rectangle (KPixCanvas canvas, double x, double y, double width, double height, unsigned long pixel_value)

Draw a single rectangle onto a pixel canvas.

Parameters:

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


flag kwin_fill_rectangle (KPixCanvas canvas, double x, double y, double width, double height, unsigned long pixel_value)

Draw a single filled rectangle onto a pixel canvas.

Parameters:

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


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_draw_arc (KPixCanvas canvas, double cx, double cy, double rx, double ry, double angle1, double angle2, double rotation, unsigned long pixel_value, flag fill)

Draw an arc onto a pixel canvas.

Parameters:

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


flag kwin_draw_ellipse (KPixCanvas canvas, double cx, double cy, double rx, double ry, unsigned long pixel_value)

Draw an ellipse onto a pixel canvas.

Parameters:

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


flag kwin_draw_ellipses (KPixCanvas canvas, int *cx, int *cy, int *rx, int *ry, int num_ellipses, unsigned long pixel_value)

Draw multiple ellipses onto a pixel canvas.

Parameters:

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


flag kwin_draw_ellipses_TRANSITION (KPixCanvas canvas, double *cx, double *cy, double *rx, double *ry, int num_ellipses, unsigned long pixel_value)

Draw multiple ellipses onto a pixel canvas.

Parameters:

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


flag kwin_fill_ellipses (KPixCanvas canvas, int *cx, int *cy, int *rx, int *ry, int num_ellipses, unsigned long pixel_value)

Draw multiple filled ellipses onto a pixel canvas.

Parameters:

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


flag kwin_fill_ellipses_TRANSITION (KPixCanvas canvas, double *cx, double *cy, double *rx, double *ry, int num_ellipses, unsigned long pixel_value)

Draw multiple filled ellipses onto a pixel canvas.

Parameters:

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


flag kwin_draw_segments (KPixCanvas canvas, int *x0, int *y0, int *x1, int *y1, int num_segments, unsigned long pixel_value)

Draw multiple disjoint lines onto a pixel canvas.

Parameters:

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


void kwin_get_size (KPixCanvas canvas, int *width, int *height)

Get the size of a pixel canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


void kwin_free_cache_data (KPixCanvasImageCache cache)

Free some cache data allocated by kwin_draw_pc_image.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


flag kwin_convert_to_canvas_coord (KPixCanvas canvas, int xin, int yin, int *xout, int *yout)

This routine will convert co-ordinates in a lower level object (parent, ie. X window) to co-ordinates in a pixel canvas.

Parameters:

Returns: TRUE if the co-ordinate lies within the canvas boundaries, else FALSE (although a conversion is still performed).
Multithreading Level: Unsafe


flag kwin_convert_from_canvas_coord (KPixCanvas canvas, int xin, int yin, int *xout, int *yout)

This routine will convert co-ordinates in a pixel canvas to co-ordinates in a lower level object (parent, ie. X window).

Parameters:

Returns: TRUE if the co-ordinate lies within the canvas boundaries, else FALSE (although a conversion is still performed).
Multithreading Level: Unsafe


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

Get (possibly allocate) a colourcell for a canvas.

Parameters:

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


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_get_pixel_RGB_values (KPixCanvas canvas, unsigned long *pixels, unsigned short *reds, unsigned short *greens, unsigned short *blues, unsigned int num_colours)

This routine will determine the RGB components of an array of colourmap entries.

Parameters:

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


KPixCanvasFont kwin_load_font (KPixCanvas canvas, CONST char *fontname)

This routine will load a font which may be then used to draw text onto a pixel canvas.

Parameters:

Returns: A pixel font on success, else NULL.
Multithreading Level: Unsafe


flag kwin_get_string_size (KPixCanvasFont font, CONST char *string, ...)

Determine the size of a string.

Parameters:

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


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_hersey_draw_string (KPixCanvas canvas, CONST char *string, double x, double y, double angle, double size, unsigned long pixel_value, double *width, double *height)

Draw string using Hershey (stroke) font.

Parameters:

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


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_open_gl_test_available (Display *display)

Test if the GLX extension is supported for a display.

Parameters:

Returns: TRUE if the GLX extension is supported, else FALSE.
Multithreading Level: Unsafe


EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_open_gl_test_stereo (Display *display, XVisualInfo *visinfo)

Test if a particular visual can display stereo.

Parameters:

Returns: TRUE if stereo is available, else FALSE.
Multithreading Level: Unsafe


flag kwin_write_ps (KPixCanvas canvas, PostScriptPage pspage)

This routine will refresh a pixel canvas, redirecting output to a PostScriptPage object.

Parameters:

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


unsigned int kwin_xgl_test_stereo (Display *display, Window window)

This routine will determine if stereoscopic display is supported using XGL on a particular display.

Parameters:

Returns: A status code. See kwin_XGL_STATUS for a list of values.
Multithreading Level: Unsafe
Note:


flag kwin_xgl_create_stereo (Display *display, Window window, int xoff, int yoff, int width, int height, KPixCanvas *mono, KPixCanvas *left, KPixCanvas *right)

This routine will create a stereo pixel canvas, ready for drawing, from an X window, using the XGL library. Note that the origin of a KPixCanvas is the upper-left corner.

Parameters:

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


Prototype Functions


void kwin_PROTO_refresh_func (KPixCanvas canvas, int width, int height, void **info, PostScriptPage pspage, unsigned int num_areas, KPixCanvasRefreshArea *areas, flag *honoured_areas)

Process a refresh event for a pixel canvas.

Parameters:

Returns: Nothing.
Multithreading Level: Unsafe


flag kwin_PROTO_position_func (KPixCanvas canvas, int x, int y, unsigned int event_code, void *e_info, void **f_info)

Process a position event on a pixel canvas.

Parameters:

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


flag kwin_PROTO_iscale_func (double *out, unsigned int out_stride, double *inp, unsigned int inp_stride, unsigned int num_values, double i_min, double i_max, void *info)

This routine will perform an arbitrary intensity scaling on an array of values. This routine may be called many times to scale an image.

Parameters:

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


Tables


kwin_ATTRIBUTES

Name Get Type Set Type Meaning
KWIN_ATT_END End of varargs list
KWIN_ATT_VISUAL unsigned int * Visual type
KWIN_ATT_DEPTH unsigned int * Depth of canvas
KWIN_ATT_VISIBLE flag * flag Canvas is visible
KWIN_ATT_FONT KPixCanvasFont * KPixCanvasFont Current font
KWIN_ATT_PIX_RED_MASK unsigned long * Red pixel mask
KWIN_ATT_PIX_GREEN_MASK unsigned long * Green pixel mask
KWIN_ATT_PIX_BLUE_MASK unsigned long * Blue pixel mask
KWIN_ATT_IM_RED_MASK unsigned long * Red image mask
KWIN_ATT_IM_GREEN_MASK unsigned long * Green image mask
KWIN_ATT_IM_BLUE_MASK unsigned long * Blue image mask
KWIN_ATT_IM_RED_OFFSET uaddr * Red image offset
KWIN_ATT_IM_GREEN_OFFSET uaddr * Green image offset
KWIN_ATT_IM_BLUE_OFFSET uaddr * Blue image offset
KWIN_ATT_LOWER_HANDLE void ** Lower handle
KWIN_ATT_USER_PTR void ** void * User pointer
KWIN_ATT_LINEWIDTH double * double Line width in pixels (0.0 = thin)


kwin_STRING_ATTRIBUTES

Name Get Type Meaning
KWIN_STRING_END End of varargs list
KWIN_STRING_WIDTH int * String width
KWIN_STRING_HEIGHT int * String height
KWIN_STRING_ASCENT int * String ascent
KWIN_STRING_DESCENT int * String descent


kwin_XGL_STATUS

Name Meaning
KWIN_XGL_NOT_AVAILABLE XGL is not supported
KWIN_XGL_STEREO_NOT_AVAILABLE No stereo display hardware
KWIN_XGL_STEREO_AVAILABLE Stereo available


Back to Karma Home Page
Contact: Richard Gooch
Web Development: Ariel Internet Services