Function

Summary

Loads an image and returns the image object.

Package

graphics-ports

Signature

load-image gp id &key cache type editable image-translation-table => image

Arguments

gp

A graphics port.

id

An image identifier, a file, an external-image, or an image.

cache

A boolean.

type

A keyword, or nil.

editable

One of the keywords :with-alpha and :without-alpha, or a boolean.

image-translation-table

An image translation table.

Values

image

An image object.

Description

The function load-image loads an image identified by id via the image-translation-table using the image load function registered with it. It returns an image object with the representation slot initialized. The gp argument specifies a graphics port used to identify the library. It also specifies the resource in which colors are defined and if necessary allocated for the image. If id is in the table but the translation is not an external image, and the image loader returns an external image as the second value, that external image replaces the translation in the table. The default value of image-translation-table is *default-image-translation-table*.

id can be an image, which is just associated with the port gp and returned if it is a Plain Image or if editable is nil. Otherwise a new Plain Image object is returned, as described below.

id can also be a string or pathname denoting a file, and in this case the image is loaded according to type , as described below.

The cache argument controls whether the image translation is cached. See the convert-external-image function for more details.

type tells load-image that the image is in a particular graphics format. Currently the only recognized value is :bmp, which means the image is a Bitmap. Other values of type cause load-image to load the image according to the file type of id, if id denotes a file, as described for read-external-image. See Drawing - Graphics Ports for a discussion of image handling. The default value of type is nil.

editable controls whether the image image is a Plain Image suitable for use with the Image Access API. The values of editable have the following effects:

nil

The image is not editable.

:without-alpha

The image is editable, but does not have an alpha channel.

t

The image is editable, but does not have an alpha channel if the source of the image has an alpha channel (for example, a TIFF file with alpha channel).

:with-alpha

The image is editable and has an alpha channel. It will be fully opaque when loading files without an alpha channel.

Given an image my-image , call

(load-image port my-image :editable t)

to create an image guaranteed to work with make-image-access. The default value of editable is nil.

Normally the image is freed automatically, when gp is destroyed. However there are circumstances where you need to explicitly free an image, for example when you want it to go away before the port. If the image is not freed, a memory leak occurs.

Note: gp must already be created at the time load-image is called. If you need to delay loading the image, for example if you are computing the image dynamically, then you can call load-image in the create-callback of the port or even in its first display-callback .

Compatibility note

In LispWorks 4.4 there is a keyword argument :force-plain with the same effect as :editable. :force-plain is still accepted in LispWorks 7.0 for backwards compatibility, but you should now use :editable instead.

See also

convert-external-image
*default-image-translation-table*
load-icon-image
make-image
make-image-access
Drawing - Graphics Ports