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

(load-image
pane
image
:force-plain t)

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

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.

Construct an Image Access object by calling
make-image-access
.

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.

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.

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:
examples/capi/graphics/image-access.lisp