Image Resources: Chimara Reference Manual

Image Resources

Image Resources — Graphics in Glk

Functions

glui32	glk_image_get_info ()
glui32	glk_image_draw ()
glui32	glk_image_draw_scaled ()

Includes

#include <libchimara/glk.h>

Description

In accordance with this modern age, Glk provides for a modicum of graphical flair. It does not attempt to be a complete graphical toolkit. Those already exist. Glk strikes the usual uncomfortable balance between power, portability, and ease of implementation: commands for arranging pre-supplied images on the screen and intermixed with text.

Graphics is an optional capability in Glk; not all libraries support graphics. This should not be a surprise.

Most of the graphics commands in Glk deal with image resources. Your program does not have to worry about how images are stored. Everything is a resource, and a resource is referred to by an integer identifier. You may, for example, call a function to display image number 17. The format, loading, and displaying of that image is entirely up to the Glk library for the platform in question.

Of course, it is also desirable to have a platform-independent way to store sounds and images. Blorb is the official resource-storage format of Glk. A Glk library does not have to understand Blorb, but it is more likely to understand Blorb than any other format.

Glk does not specify the exact format of images, but Blorb does. Images in a Blorb archive must be PNG or JPEG files. More formats may be added if real-world experience shows it to be desirable. However, that is in the domain of the Blorb specification. The Glk spec, and Glk programming, will not change.

At present, images can only be drawn in graphics windows and text buffer windows. In fact, a library may not implement both of these possibilities. You should test each with the gestalt_DrawImage selector if you plan to use it. See Testing for Graphics Capabilities.

Functions

glk_image_get_info ()

glui32
glk_image_get_info (glui32 image,
                    glui32 *width,
                    glui32 *height);

This gets information about the image resource with the given identifier. It returns TRUE (1) if there is such an image, and FALSE (0) if not. You can also pass pointers to width and height variables; if the image exists, the variables will be filled in with the width and height of the image, in pixels. (You can pass NULL for either width or height if you don't care about that information.)

You should always use this function to measure the size of images when you are creating your display. Do this even if you created the images, and you know how big they “should” be. This is because images may be scaled in translating from one platform to another, or even from one machine to another. A Glk library might display all images larger than their original size, because of screen resolution or player preference. Images will be scaled proportionally, but you still need to call glk_image_get_info() to determine their absolute size.

Parameters

image	An image resource number.
width	Pointer to a location at which to store the image's width.
height	Pointer to a location at which to store the image's height.

Returns

TRUE if image is a valid identifier, FALSE if not.

glk_image_draw ()

glui32
glk_image_draw (winid_t win,
                glui32 image,
                glsi32 val1,
                glsi32 val2);

This draws the given image resource in the given window. The position of the image is given by val1 and val2 , but their meaning varies depending on what kind of window you are drawing in. See Graphics is Graphics Windows and Graphics in Text Buffer Windows.

This function returns a flag indicating whether the drawing operation succeeded.

A FALSE result can occur for many reasons. The image data might be corrupted; the library may not have enough memory to operate; there may be no image with the given identifier; the window might not support image display; and so on.

Parameters

win	A graphics or text buffer window.
image	An image resource number.
val1	The x coordinate at which to draw the image (if `win` is a graphics window); or, an image alignment constant (if `win` is a text window).
val2	The y coordinate at which to draw the image (if `win` is a graphics window); this parameter is ignored if `win` is a text buffer window.

Returns

TRUE if the operation succeeded, FALSE if not.

glk_image_draw_scaled ()

glui32
glk_image_draw_scaled (winid_t win,
                       glui32 image,
                       glsi32 val1,
                       glsi32 val2,
                       glui32 width,
                       glui32 height);

This is similar to glk_image_draw(), but it scales the image to the given width and height , instead of using the image's standard size. (You can measure the standard size with glk_image_get_info().)

If width or height is zero, nothing is drawn. Since those arguments are unsigned integers, they cannot be negative. If you pass in a negative number, it will be interpreted as a very large positive number, which is almost certain to end badly.

Parameters

win	A graphics or text buffer window.
image	An image resource number.
val1	The x coordinate at which to draw the image (if `win` is a graphics window); or, an image alignment constant (if `win` is a text window).
val2	The y coordinate at which to draw the image (if `win` is a graphics window); this parameter is ignored if `win` is a text buffer window.
width	The width of the image.
height	The height of the image.

Returns

TRUE if the operation succeeded, FALSE otherwise.