All Manuals > CAPI User Guide and Reference Manual > 22 GRAPHICS-PORTS Reference Entries

read-external-image Function


Returns an external image read from a file.




read-external-image file &key transparent-color-index type => image

A pathname designator.
An integer, a cons or nil.
A keyword, or nil.
An external image.

The function read-external-image returns an external image read from file.

If transparent-color-index is an integer it specifies the index of the transparent color in the color map.

transparent-color-index can also be a cons (index . new-color) where new-color is a color specification that is converted to the color to use instead of the color at index index in the color map. new-color can also be the keyword :transparent. On most platforms this makes it truly transparent. On Motif it uses the background of the pane that it is associated with by load-image.

transparent-color-index works only for images with a color map, that is, those with 256 colors or less. The default value is nil, meaning that there is no transparent color.

type tells read-external-image that the image is in a particular graphics format. Currently the only recognized value is :bmp, which means the image is read as a Bitmap. Other values of type cause read-external-image to read the image according to the file type of file. "bmp" or "dib" mean that the image is read as a Bitmap. Other file types are handled in Operating System-specific ways. See 13.10 Working with images for details. The default value of type is nil.


To see the effect of transparent-color-index, do:

  1. (example-edit-file "capi/graphics/images")
  2. Specify a non-white :background for the viewer pane. Use an image editing tool to find the transparent color index (183 in this image) and change the call to read-external-image like this:
    (gp:read-external-image file
       :transparent-color-index 183)
  3. Then compile and run the example, click the Change... button and select the Setup.bmp file.
See also


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:44