read-external-image

read-external-image Function

Summary

Returns an external image read from a file.

Package

graphics-ports

Signature

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

Arguments

`file`⇩	A pathname designator.
`transparent-color-index`⇩
	An integer, a cons or `nil`.
`type`⇩	A keyword, or `nil`.

Values

image

An external image.

Description

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.

Examples

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

(example-edit-file "capi/graphics/images")
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)
```
Then compile and run the example, click the Change... button and select the Setup.bmp file.