Graphics in Graphics Windows: Chimara Reference Manual

Graphics in Graphics Windows

Graphics in Graphics Windows — Drawing graphics in graphics windows

Functions

void	glk_window_set_background_color ()
void	glk_window_fill_rect ()
void	glk_window_erase_rect ()

Includes

#include <libchimara/glk.h>

Description

A graphics window is a rectangular canvas of pixels, upon which you can draw images. The contents are entirely under your control. You can draw as many images as you like, at any positions — overlapping if you like. If the window is resized, you are responsible for redrawing everything. See Graphics Windows.

Note that graphics windows do not support a full set of object-drawing commands, nor can you draw text in them. That may be available in a future Glk extension. For now, it seems reasonable to limit the task to a single primitive, the drawing of a raster image. And then there's the ability to fill a rectangle with a solid color — a small extension, and hopefully no additional work for the library, since it can already clear with arbitrary background colors. In fact, if glk_window_fill_rect() did not exist, an author could invent it — by briefly setting the background color, erasing a rectangle, and restoring.

If you call glk_image_draw() or glk_image_draw_scaled() in a graphics window, val1 and val2 are interpreted as X and Y coordinates. The image will be drawn with its upper left corner at this position.

It is legitimate for part of the image to fall outside the window; the excess is not drawn. Note that these are signed arguments, so you can draw an image which falls outside the left or top edge of the window, as well as the right or bottom.

There are a few other commands which apply to graphics windows.

Functions

glk_window_set_background_color ()

void
glk_window_set_background_color (winid_t win,
                                 glui32 color);

This sets the window's background color. It does not change what is currently displayed; it only affects subsequent clears and resizes. The initial background color of each window is white.

Colors are encoded in a 32-bit value: the top 8 bits must be zero, the next 8 bits are the red value, the next 8 bits are the green value, and the bottom 8 bits are the blue value. Color values range from 0 to 255.

So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.

This function may only be used with graphics windows. To set background colors in a text window, use text styles with color hints; see Styles.

Parameters

win	A graphics window.
color	a 32-bit RGB color value.

glk_window_fill_rect ()

void
glk_window_fill_rect (winid_t win,
                      glui32 color,
                      glsi32 left,
                      glsi32 top,
                      glui32 width,
                      glui32 height);

This fills the given rectangle with the given color. It is legitimate for part of the rectangle to fall outside the window. If width or height is zero, nothing is drawn.

Parameters

win	A graphics window.
color	A 32-bit RGB color value, see `glk_window_set_background_color()`.
left	The x coordinate of the top left corner of the rectangle.
top	The y coordinate of the top left corner of the rectangle.
width	The width of the rectangle.
height	The height of the rectangle.

glk_window_erase_rect ()

void
glk_window_erase_rect (winid_t win,
                       glsi32 left,
                       glsi32 top,
                       glui32 width,
                       glui32 height);

This fills the given rectangle with the window's background color.

You can also fill an entire graphics window with its background color by calling glk_window_clear().

Parameters

win	A graphics window.
left	The x coordinate of the top left corner of the rectangle.
top	The y coordinate of the top left corner of the rectangle.
width	The width of the rectangle.
height	The height of the rectangle.