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 Working with images for details. The default value of type is nil.

Example

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

external-image