12.8.7 Image access

You can read and write pixel values in an image via an Image Access object, but only if the image is a Plain Image. You can ensure you have a Plain Image by using the result of

To read and/or write pixel values, follow these steps:

1. Start with a Graphics Port (for example a capi:output-pane ) and an image object associated with it, which is a Plain Image. See above for how to create an image object.
2. Construct an Image Access object by calling make-image-access .
3. To read pixels from the image, first call image-access-transfer-from-image on the image access object. This notionally transfers all the pixel data from the window system into the access object. It might do nothing if the window system allows fast access to the pixel data directly. Then call image-access-pixel with the coordinates of each pixel. The pixel values are like those returned from color:convert-color and can be converted to RGB using color:unconvert-color if required.
4. To write pixels to the image, you must have already called image-access-transfer-from-image . Then call (setf image-access-pixel) with the coordinaes of each pixel to write, and then call image-access-transfer-to-image on the Image Access object. This notionally transfers all the pixel data back to the window system from the access object. It might do nothing if the window system allows fast access to the pixel data directly.
5. Free the image access object by calling free-image-access on it.

There is an example that demonstrates the uses of Image Access objects in:

This further example demonstrates the uses of Image Access objects with colors that have an alpha component: