17.8 Images

Some graphics device types support images, which are rectangular pieces of picture that may be drawn into a graphics device. Images are often called something else in the host graphics system, such as bitmaps or pixmaps. The operations supported vary between devices, so look under the different device types to see what operations are available. All devices that support images support the following operations.

operation on graphics-device: create-image width height

Images are created using the create-image graphics operation, specifying the width and height of the image in device coordinates (pixels).

(graphics-operation device 'create-image 200 100)

The initial contents of an image are unspecified.

create-image is a graphics operation rather than a procedure because the kind of image returned depends on the kind of graphics device used and the options specified in its creation. The image may be used freely with other graphics devices created with the same attributes, but the effects of using an image with a graphics device with different attributes (for example, different colors) is undefined. Under X, the image is display dependent.

operation on graphics-device: draw-image x y image

The image is copied into the graphics device at the specified position.

operation on graphics-device: draw-subimage x y image im-x im-y w h

Part of the image is copied into the graphics device at the specified (x, y) position. The part of the image that is copied is the rectangular region at im-x and im-y and of width w and height h. These four numbers are given in device coordinates (pixels).

procedure: image? object

Returns #t if object is an image, otherwise returns #f.

procedure: image/destroy image

This procedure destroys image, returning storage to the system. Programs should destroy images after they have been used because even modest images may use large amounts of memory. Images are reclaimed by the garbage collector, but they may be implemented using memory outside of Scheme’s heap. If an image is reclaimed before being destroyed, the implementation might not deallocate that non-heap memory, which can cause a subsequent call to create-image to fail because it is unable to allocate enough memory.

procedure: image/height image

Returns the height of the image in device coordinates.

procedure: image/width image

Returns the width of the image in device coordinates.

procedure: image/fill-from-byte-vector image bytes

The contents of image are set in a device-dependent way, using one byte per pixel from bytes (a string). Pixels are filled row by row from the top of the image to the bottom, with each row being filled from left to right. There must be at least (* (image/height image) (image/width image)) bytes in bytes.