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. If type is one of the list that is returned by list-known-image-formats then the image can be displayed on the screen that was passed to list-known-image-formats, but an external-image can be created with any type. 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:

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