Next: X Graphics, Previous: Custom Graphics Operations, Up: Graphics
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.
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.
The image is copied into the graphics device at the specified position.
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).
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.
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.