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_x	Create a pixel canvas from an X window.
kwin_set_gc_x	Set Graphics Context for an X-based pixel canavas.
kwin_get_gc_x	Get Graphics Context for an X-based pixel canavas.
kwin_create_generic	Create generic pixel canvas.
kwin_create_child	Create a child pixel canvas.
kwin_destroy	Destroy a pixel canvas.
kwin_register_destroy_func	Register destroy callback.
kwin_register_refresh_func	Register a refresh callback.
kwin_register_position_event_func	Register position event callback.
kwin_register_bindings	Register mouse and key binding descriptions with a pixel canvas.
kwin_resize	Resize a pixel canvas.
kwin_refresh_if_visible	Refresh a pixel canvas if it is visible.
kwin_partial_refresh	Perform a partial refresh of a pixel canvas.
kwin_process_position_event	Process position event on a pixel canvas.
kwin_get_attributes	Get the attributes for a pixel canvas.
kwin_set_attributes	Set the attributes for a pixel canvas.
kwin_associate_object	Associate an object with a pixel canvas.
kwin_get_associated_object	Get an associated object for a pixel canvas.
kwin_clear	Clear a rectangular portion of a pixel canvas.
kwin_draw_pc_image	Draw PseudoColour image to a pixel canvas.
kwin_compute_pc_subimage	Compute PseudoColour subimage for a pixel canvas.
kwin_draw_rgb_image	Draw TrueColour image to a pixel canvas.
kwin_draw_cached_image	Draw cached image to a pixel canvas.
kwin_draw_cached_subimages	Draw previously computed cached subimages.
kwin_draw_point	Draw a single point onto a pixel canvas.
kwin_draw_points	Draw multiple points onto a pixel canvas.
kwin_draw_line	Draw a single line onto a pixel canvas.
kwin_draw_lines	Draw multiple connected lines onto a pixel canvas.
kwin_fill_ellipse	Draw a filled ellipse onto a pixel canvas.
kwin_fill_polygon	Draw a filled polygon onto a pixel canvas.
kwin_draw_string	Draw a string onto a pixel canvas.
kwin_draw_rectangle	Draw a single rectangle onto a pixel canvas.
kwin_fill_rectangle	Draw a single filled rectangle onto a pixel canvas.
kwin_draw_arc	Draw an arc onto a pixel canvas.
kwin_draw_ellipse	Draw an ellipse onto a pixel canvas.
kwin_draw_ellipses	Draw multiple ellipses onto a pixel canvas.
kwin_fill_ellipses	Draw multiple filled ellipses onto a pixel canvas.
kwin_draw_segments	Draw multiple disjoint lines onto a pixel canvas.
kwin_get_size	Get the size of a pixel canvas.
kwin_free_cache_data	Free some cache data allocated by kwin_draw_pc_image.
kwin_set_clip_areas	Set the clip areas.
kwin_convert_to_canvas_coord	Convert low-level co-ordinates to pixel co-ordinates.
kwin_convert_from_canvas_coord	Convert pixel co-ordinates to low-level co-ordinates.
kwin_get_colour	Get (possibly allocate) a colourcell for a canvas.
kwin_get_pixel_RGB_values	Get RGB components of pixel values.
kwin_load_font	Load a font for later use.
kwin_get_string_size	Determine the size of a string.
kwin_warp_pointer	Warp the pointer to a new location.
kwin_hershey_get_string	Get string using Hershey (stroke) font for later drawing.
kwin_hershey_draw_string	Draw string using Hershey (stroke) font.
kwin_mem_write_rgb	Refresh a pixel canvas into a memory buffer.
kwin_get_colour_harder	Get (possibly allocate) a colourcell for a canvas.
kwin_open_gl_test_available	Test if the GLX extension is supported for a display.
kwin_open_gl_test_stereo	Test if a particular visual can display stereo.
kwin_write_ps	Refresh a pixel canvas onto a PostScriptPage object.
kwin_ps_generate	Generate PostScript output.
kwin_queue_position_event	Queue a position event on a pixel canvas for possible processing.
kwin_xgl_test_stereo	Test if stereo supported using XGL.
kwin_xgl_create_stereo	Create a stereo pixel canvas using XGL.

Prototype Functions

kwin_PROTO_refresh_func	Process a refresh event for a pixel canvas.
kwin_PROTO_position_func	Process a position event on a pixel canvas.
kwin_PROTO_destroy_func	Process a destroy event for an object.
kwin_PROTO_iscale_func	Intensity scale function.

Tables

kwin_ATTRIBUTES	List of attributes for KPixCanvas objects
kwin_STRING_ATTRIBUTES	List of attributes for KPixCanvasFont string
kwin_XGL_STATUS	List of XGL stereo support types
kwin_ENVIRONMENT	List of environment variables

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:

display : The X display.
window : The window ID in which the canvas lies.
gc : The graphics context.
xoff : The horizontal offset of the canvas origin (upper-left corner) relative to the parent window.
yoff : The vertical offset of the canvas origin (upper-left corner) relative to the parent window.
width : The width (vertical extent) of the canvas.
height : The height (horizontal extent) of the canvas.

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

This routine is only available with the X window system.

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:

canvas : The canvas.
gc : The Graphics Context.

Returns: Nothing.
Multithreading Level: Unsafe
Note:

This routine is only available with the X window system.

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:

canvas : The canvas.

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

This routine is only available with the X window system.

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, KPixFuncCreateChild create_child, KPixFuncClearArea clear_area, KPixFuncDestroy destroy, ...)

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:

info : A pointer to canvas specific data.
xoff : The horizontal offset of the canvas origin (upper-left corner) relative to the parent object.
yoff : The vertical offset of the canvas origin (upper-left corner) relative to the parent object.
width : The width (vertical extent) of the canvas.
height : The height (horizontal extent) of the canvas.
depth : The depth (in bits) of the canvas.
visual : The visual type of the canvas.
visible : TRUE if the canvas is visible, else FALSE.
create_child : The function that is called when a child canvas is created.
clear_area : The function that is called when the canvas is to be cleared.
destroy : The function that is called when the canvas is destroyed.
... : The optional list of parameter attribute-key attribute-value pairs must follow. See the header file for details on defined attributes. This list must be terminated with the value KWIN_ATT_END .

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:

parent : The parent pixel canvas.
xoff : The horizontal offset of the canvas origin (upper-left corner) relative to the parent pixel canvas.
yoff : The vertical offset of the canvas origin (upper-left corner) relative to the parent pixel canvas.
width : The width (vertical extent) of the canvas.
height : The height (horizontal extent) of the canvas.
absorb_events : If TRUE, any events passed from the parent canvas to the child canvas and consumed by the registered event functions for the child canvas are consumed from the parent canvas. If FALSE, the child canvas does not consume events from the parent. Note that the parent events are still *passed* to the child canvas.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void kwin_destroy (KPixCanvas canvas)

Destroy a pixel canvas.

Parameters:

canvas : The pixel canvas.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

KCallbackFunc kwin_register_destroy_func (KPixCanvas canvas, void (*func) (), void *info)

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

Parameters:

canvas : The pixel canvas.
func : The function that is called when the canvas is destroyed. The prototype function is kwin_PROTO_destroy_func.
info : The arbitrary function information pointer.

Returns: A KCallbackFunc object. On failure, the process aborts.
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:

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

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:

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

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

EXPERIMENTAL FUNCTION: subject to change without notice

void kwin_register_bindings (KPixCanvas canvas, KPixCanvasBinding *bindings, flag copy)

Parameters:

canvas : The pixel canvas.
bindings : The list of bindings. This must be terminated with NULL entries.
copy : If TRUE, the string contents are copied, else pointer copies are made.

Returns: Nothing.
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:

canvas : The canvas.
clear : If TRUE, the canvas is first cleared.
xoff : The horizontal offset of the canvas origin (upper-left corner) relative to the parent window.
yoff : The vertical offset of the canvas origin (upper-left corner) relative to the parent window.
width : The new width (horizontal extent) of the canvas. If this is less than 1 canvas is not resized, it is only refreshed.
height : The new height (vertical extent) of the canvas. If this is less than 1 canvas is not resized, it is only refreshed.

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:

canvas : The pixel canvas.
clear : If TRUE the canvas is cleared prior to refreshing.

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:

canvas : The pixel canvas.
num_areas : The number of areas in the pixel canvas to refresh.
areas : The list of areas to refresh. The values here are updated to ensure all points lie within the boundaries of the pixel canvas.
clear_all : If TRUE, each refreshed region is first cleared, else the clear field of each area determines whether an area is cleared.

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:

canvas : The pixel canvas.
x : The horizontal position of the event, relative to the parent window.
y : The vertical position of the event, relative to the parent window.
clip : If this is TRUE, events outside of the canvas boundary are clipped to the nearest boundary and passed on to the registered position event consumers. If this is FALSE, events outside of the canvas boundary are not consumed (i.e. they are ignored).
event_code : The arbitrary event code.
event_info : The arbitrary event information.

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:

canvas : The pixel canvas.
... : The optional list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the value KWIN_ATT_END. See kwin_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

void kwin_set_attributes (KPixCanvas canvas, ...)

Set the attributes for a pixel canvas.

Parameters:

canvas : The pixel canvas.
... : The optional list of parameter attribute-key attribute-value pairs must follow. This list must be terminated with the value KWIN_ATT_END. See kwin_ATTRIBUTES for the list of attributes.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void kwin_associate_object (KPixCanvas canvas, CONST void *key, CONST void *object, flag replace)

Associate an object with a pixel canvas.

Parameters:

canvas : The pixel 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 * kwin_get_associated_object (KPixCanvas canvas, CONST void *key)

Get an associated object for a pixel canvas.

Parameters:

canvas : The pixel 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

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

Clear a rectangular portion of a pixel canvas.

Parameters:

canvas : The canvas.
x : The horizontal offset of the rectangle.
y : The vertical offset of the rectangle.
width : The width of the rectangle. If this is less than 0 the pixel canvas is cleared to its right edge.
height : The height of the rectangle. If this is less than 0 the pixel canvas is cleared to its bottom edge.

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

To clear the entire canvas, the following should be used: kwin_clear (canvas, 0, 0, -1, -1);

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:

canvas : The pixel canvas.
x_off : The horizontal offset, relative to the top-left corner of the canvas.
y_off : The vertical offset, relative to the top-left corner of the canvas.
x_pixels : The number of horizontal pixels to draw.
y_pixels : The number of vertical pixels to draw.
slice : The start of the slice image data.
hoffsets : The array of horizontal byte offsets.
voffsets : The array of vertical byte offsets.
width : The width of the input image (in values).
height : The height of the input image (in values).
type : The type of the slice image data.
conv_type : The input conversion type (when the input is complex).
num_pixels : The number of pixels in the pixel array.
pixel_values : The array of pixel values.
blank_pixel : The pixel value to be used when the intensity value is an undefined value.
min_sat_pixel : The pixel value to be used when the intensity value is below the minimum value.
max_sat_pixel : The pixel value to be used when the intensity value is above the maximum value.
i_min : The minimum intensity value.
i_max : The maximum intensity value.
iscale_func : The function to be called when non-linear intensity scaling is required. If NULL, linear intensity scaling is used. The prototype function is kwin_PROTO_iscale_func.
iscale_info : A pointer to arbitrary information for iscale_func.
cache_ptr : Cache data is written here. The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. 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.

EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_compute_pc_subimage (KPixCanvas canvas, int x_off, int y_off, int x_pixels,int y_pixels, int cache_width, int cache_height, CONST char *slice, CONST uaddr *hoffsets, CONST uaddr *voffsets, unsigned int image_width, unsigned int image_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)

This routine will compute a subimage cache for a 2-dimensional slice of a Karma array for a pixel canvas. This slice may be tiled. The slice is a PseudoColour subimage.

Parameters:

canvas : The pixel canvas.
x_off : The horizontal offset of the subimage, relative to the top-left corner of the image cache.
y_off : The vertical offset of the subimage, relative to the top-left corner of the image cache.
x_pixels : The number of horizontal pixels to generate.
y_pixels : The number of vertical pixels to generate.
cache_width : The width of the image cache.
cache_height : The height of the image cache.
slice : The start of the slice image data.
hoffsets : The array of horizontal byte offsets for the input image.
voffsets : The array of vertical byte offsets for the input image.
image_width : The width of the input image (in values).
image_height : The height of the input image (in values).
type : The type of the slice image data.
conv_type : The input conversion type (when the input is complex).
num_pixels : The number of pixels in the pixel array.
pixel_values : The array of pixel values.
blank_pixel : The pixel value to be used when the intensity value is an undefined value.
min_sat_pixel : The pixel value to be used when the intensity value is below the minimum value.
max_sat_pixel : The pixel value to be used when the intensity value is above the maximum value.
i_min : The minimum intensity value.
i_max : The maximum intensity value.
iscale_func : The function to be called when non-linear intensity scaling is required. If NULL, linear intensity scaling is used. The prototype function is kwin_PROTO_iscale_func.
iscale_info : A pointer to arbitrary information for iscale_func.
cache : Cache data is written here. The routine will produce cache data which will vastly increase the speed of subsequent operations on this data. 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 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:

canvas : The pixel canvas.
x_off : The horizontal offset, relative to the top-left corner of the canvas.
y_off : The vertical offset, relative to the top-left corner of the canvas.
x_pixels : The number of horizontal pixels to draw.
y_pixels : The number of vertical pixels to draw.
red_slice : The start of the red slice data.
green_slice : The start of the green slice data.
blue_slice : The start of the blue slice data.
hoffsets : The array of horizontal byte offsets.
voffsets : The array of vertical byte offsets.
width : The width of the input image (in values).
height : The height of the input image (in values).
cache_ptr : Cache data is written here. The routine may produce cache data which will vastly increase the speed of subsequent operations on this data. 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.
Note:

The 3 colour components must be of type K_UBYTE .

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:

cache : The cache data.
x_off : The horizontal offset, relative to the top-left corner of the canvas.
y_off : The vertical offset, relative to the top-left corner of the canvas.

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:

cache : The cache data.
x_off : The horizontal offset, relative to the top-left corner of the canvas, which corresponds to the image origin.
y_off : The vertical offset, relative to the top-left corner of the canvas, which corresponds to the image origin.
num_areas : The number of image areas to draw.
areas : The list of image areas.

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:

canvas : The canvas.
x : The horizontal offset of the point.
y : The vertical offset of the point.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
x_array : The horizontal co-ordinates of the points.
y_array : The vertical co-ordinates of the points.
num_points : The number of points.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
x0 : The horizontal offset of the first point.
y0 : The vertical offset of the first point.
x1 : The horizontal offset of the second point.
y1 : The vertical offset of the second point.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
x_array : The horizontal co-ordinates of the points.
y_array : The vertical co-ordinates of the points.
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: 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:

canvas : The canvas.
cx : The horizontal co-ordinate of the centre of the ellipse.
cy : The vertical co-ordinate of the centre of the ellipse.
rx : The horizontal radius.
ry : The vertical radius.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
point_x : The array of x co-ordinates of vertices of the polygon.
point_y : The array of y co-ordinates of vertices of the polygon.
num_vertices : The number of vertices in the polygon.
pixel_value : The pixel value to use.
convex : If TRUE, then the points must form a convex polygon.

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:

canvas : The canvas.
x : The horizontal offset of the string origin.
y : The vertical offset of the string origin.
string : The string.
pixel_value : The pixel value to use.
clear_under : If TRUE, then the routine will draw both the foreground and background of the characters.

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:

canvas : The canvas.
x : The horizontal offset of the rectangle.
y : The vertical offset of the rectangle.
width : The width of the rectangle. The point x + width is a vertex.
height : The height of the rectangle. The point y + height is a vertex.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
x : The horizontal offset of the rectangle.
y : The vertical offset of the rectangle.
width : The width of the rectangle. The point x + width is a vertex.
height : The height of the rectangle. The point y + height is a vertex.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
cx : The horizontal co-ordinate of the centre of the ellipse.
cy : The vertical co-ordinate of the centre of the ellipse.
rx : The horizontal radius.
ry : The vertical radius.
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 use.
fill : If TRUE, the arc is filled, else only the outside is drawn.

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:

canvas : The canvas.
cx : The horizontal co-ordinate of the centre of the ellipse.
cy : The vertical co-ordinate of the centre of the ellipse.
rx : The horizontal radius.
ry : The vertical radius.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
cx : The array of horizontal co-ordinate of the centre of the ellipse.
cy : The array of vertical co-ordinate of the centre of the ellipse.
rx : The array of horizontal radii.
ry : The array of vertical radii.
num_ellipses : The number of ellipses.
pixel_value : The pixel value to use.

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:

canvas : The canvas.
cx : The array of horizontal co-ordinate of the centre of the ellipse.
cy : The array of vertical co-ordinate of the centre of the ellipse.
rx : The array of horizontal radii.
ry : The array of vertical radii.
num_ellipses : The number of ellipses.
pixel_value : The pixel value to use.

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:

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

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:

width : The number of horizontal pixels will be written here. This may be NULL.
height : The number of vertical pixels will be written here. This may be NULL.

Returns: Nothing.
Multithreading Level: Unsafe

void kwin_free_cache_data (KPixCanvasImageCache cache)

Free some cache data allocated by kwin_draw_pc_image.

Parameters:

cache : The cache data.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void kwin_set_clip_areas (KPixCanvas canvas, unsigned int num_areas, KPixCanvasRefreshArea *areas)

Set the clip areas.

Parameters:

canvas : The canvas.
num_areas : The number of clip areas. If 0, there are no clip areas.
areas : The array of clip areas.

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:

canvas : The canvas.
xin : The lower level horizontal co-ordinate.
yin : The lower level vertical co-ordinate.
xout : The horizontal canvas co-ordinate will be written here.
yout : The vertical canvas co-ordinate will be written here.

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:

canvas : The canvas.
xin : The horizontal canvas co-ordinate.
yin : The vertical canvas co-ordinate.
xout : The lower level horizontal co-ordinate will be written here.
yout : The lower level vertical co-ordinate will be written here.

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:

canvas : The canvas.
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 this canvas. ALSO: the pixel value becomes invalid EVERY time the canvas is refreshed/ resized. If the canvas is refreshed/ resized, this routine MUST be called again.

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:

canvas : The pixel canvas.
pixels : The array of colourmap indices.
reds : The red components will be written to this array.
greens : The green components will be written to this array.
blues : The blue components will be written to this array.
num_colours : The number of colours in the arrays.

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:

canvas : The pixel canvas for which the font is valid.
fontname : The name of the font.

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:

font : The font.
string : The string.
... : The optional list of parameter attribute-key attribute-value-ptr pairs must follow. This list must be terminated with the value KWIN_STRING_END. See kwin_STRING_ATTRIBUTES for the list of attributes.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_warp_pointer (KPixCanvas canvas, int x, int y, flag relative, flag discard)

Warp the pointer to a new location.

Parameters:

x : The horizontal position to warp to.
y : The vertical position to warp to.
relative : If TRUE, the pointer is warped relative to it's current position.
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

KPixCanvasHersheyString kwin_hershey_get_string (CONST char *string, double angle, double size, double *width, double *height, double *ascent, double *descent)

Get string using Hershey (stroke) font for later drawing.

Parameters:

angle : The rotation angle of the string in degrees.
size : The size of the font in pixels (typically 12.8).
width : The width of the string in pixels (ignoring rotations) is written here. If this is NULL nothing is written here.
height : The height of the string in pixels (ignoring rotations) is written here. If this is NULL nothing is written here.
ascent : The ascent of the string in pixels (ignoring rotations) is written here. This is typically positive. If this is NULL nothing is written here.
descent : The descent of the string in pixels (ignoring rotations) is written here. This is typically negative. If this is NULL nothing is written here.

Returns: A KPixCanvasHersheyString object on success, else NULL. This is valid until the next call to this function.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

void kwin_hershey_draw_string (KPixCanvas canvas, KPixCanvasHersheyString string, double x, double y, double size, unsigned long pixel_value)

Draw string using Hershey (stroke) font.

Parameters:

canvas : The KPixCanvas to draw onto.
string : The string to draw.
x : The starting horizontal position of the string.
y : The starting vertical position of the string.
size : The size of the font in pixels (typically 12.8).
pixel_value : The pixel value to use when drawing the string.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_mem_write_rgb (KPixCanvas canvas, void *red, void *green, void *blue, uaddr stride, unsigned int width, unsigned int height)

This routine will refresh a pixel canvas, redirecting output to a memory buffer.

Parameters:

canvas : The pixel canvas.
red : The red buffer pointer.
green : The green buffer pointer.
blue : The blue buffer pointer.
stride : The stride in bytes between adjacent pixels.
width : The width of the memory buffer in pixels.
height : The height of the memory buffer in pixels.

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

EXPERIMENTAL FUNCTION: subject to change without notice

flag kwin_get_colour_harder (KPixCanvas canvas, CONST char *colourname, unsigned long *pixel_value)

This function will get a colourcell for a canvas. It is similar to the kwin_get_colour function, except that tries harder for TrueColour and DirectColour visuals, by using the pixel masks.

Parameters:

canvas : The canvas.
colourname : The name of the colour to get.
pixel_value : The pixel value will be written here.

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

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

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:

display : The X11 display handle.

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:

display : The X11 display handle.
visinfo : The XVisualInfo structure.

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:

canvas : The pixel canvas.
pspage : The PostScriptPage object.

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

EXPERIMENTAL FUNCTION: subject to change without notice

void kwin_ps_generate (KPixCanvas canvas, CONST char *destination, flag queue, double hoffset, double voffset, double hsize, double vsize, unsigned int orientation, flag eps, double thin_linewidth, unsigned int tray, flag preserve_aspect, CONST char *media_size)

Generate PostScript output.

Parameters:

canvas : The pixel canvas to generate PostScript for.
destination : The name of the file or printer queue to send the output.
queue : If TRUE, send to a printer queue, else write to a file.
hoffset : The horizontal offset (in centimeters) of the co-ordinate origin.
voffset : The vertical offset (in centimeters) of the co-ordinate origin.
hsize : The desired horizontal size of the co-ordinate system (in centimeters).
vsize : The desired vertical size of the co-ordinate system (in centimeters).
portrait : If TRUE, objects will be drawn in portrait mode (i.e. the x-axis will be horizontal), else they will be drawn in landscape mode (i.e. the x-axis will be vertical).
eps : If TRUE the file format will be Encapsulated PostScript, else regular PostScript is written.
thin_linewidth : The width (in mm) of thin lines.
tray : The tray to print to. See psw_TRAY_TYPES for a list of trays.
preserve_aspect : If TRUE, the aspect ratio of the canvas is preserved in the PostScript output (i.e. screen pixels will be square in the PostScript output), else the canvas is stretched to fill the specified area.
media_size : The size of the media.

Returns: Nothing.
Multithreading Level: Unsafe

EXPERIMENTAL FUNCTION: subject to change without notice

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

This function is similar to the kwin_process_position_event function, except that non-critical events may be dropped if the system is too busy. This avoids application response lagging behind user input.

Parameters:

canvas : The pixel canvas.
x : The horizontal position of the event, relative to the parent window.
y : The vertical position of the event, relative to the parent window.
clip : If this is TRUE, events outside of the canvas boundary are clipped to the nearest boundary and passed on to the registered position event consumers. If this is FALSE, events outside of the canvas boundary are not consumed (i.e. they are ignored).
event_code : The arbitrary event code.
event_info : The arbitrary event information.

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

Only mouse move and mouse drag events are considered non-critical.
Older events are dropped, ensuring that the most recent event is always processed.
Events may be processed in the context of a work function (see the w package for information on work functions).

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:

display : The X display.
window : The window ID of a window of the same class as the desired stereo window.

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

This routine is only available with the X window system.

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:

display : The X display.
window : The window ID in which the canvas lies.
gc : The graphics context.
xoff : The horizontal offset of the canvas origin (upper-left corner) relative to the parent window.
yoff : The vertical offset of the canvas origin (upper-left corner) relative to the parent window.
width : The width (vertical extent) of the canvas.
height : The height (horizontal extent) of the canvas.

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

This routine is only available with the X window system.

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:

canvas : The pixel canvas.
width : The width of the canvas in pixels.
height : The height of the canvas in pixels.
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.
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 pixel canvas, subsequent refresh routines will be told to refresh the entire canvas.

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:

canvas : The pixel canvas on which the event occurred.
x : The horizontal position of the event, relative to the canvas origin
y : The vertical position of the event, relative to the canvas origin.
event_code : The arbitrary event code.
e_info : A pointer to arbitrary event information.
f_info : A pointer to an arbitrary function information pointer.

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

flag kwin_PROTO_destroy_func (void *info)

Process a destroy event for an object.

Parameters:

info : An arbitrary function information pointer.

Returns: Nothing.
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:

out : The output array.
out_stride : The stride (in doubles) of the output array.
inp : The input array.
inp_stride : The stride (in doubles) of the input array.
num_values : The number of values to scale.
i_min : The minimum intensity value.
i_max : The maximum intensity value.
info : A pointer to arbitrary information.

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

Tables

kwin_ATTRIBUTES List of attributes for KPixCanvas objects

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 List of attributes for KPixCanvasFont string

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 List of XGL stereo support types

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

kwin_ENVIRONMENT List of environment variables

Variable Meaning

KWIN_DISABLE_PIXMAPS Disable pixmap cache

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services

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)

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