Function

Summary

Externalizes and writes an image to file.

Package

graphics-ports

Signature

externalize-and-write-image gp image destination &key type if-exists errorp x-hot y-hot quality &allow-other-keys => result

Arguments

gp

A CAPI pane.

image

An image object.

destination

A file namestring, a pathname or an open output stream with element type compatible with (unsigned-byte 8), i.e. base-char, (signed-byte 8) or (unsigned-byte 8).

type

One of the keywords :bmp, :jpg, :jpeg, :png and :tiff. Other keywords may be supported, depending on the platform.

if-exists

One of the keywords :error, :new-version, :rename, :rename-and-delete, :overwrite, :append and :supersede, or nil.

errorp

A boolean.

x-hot

A non-negative integer.

y-hot

A non-negative integer.

quality

An integer in the range [0,100].

Values

result

A filename or nil.

Description

The function externalize-and-write-image externalizes and writes an image object to a file or stream.

The bytes of image are written to destination as if by write-sequence.

The output image type can be specified by the argument type . If type is not supplied then the output image type is determined by the file type of destination .

If type is supplied, it must be a keyword which specifies a known type, as returned by list-known-image-formats with for-writing-too t. The types :bmp, :jpg, :png and :tiff are known on all platforms (except Motif). Additionally, :jpeg is an as alias for :jpg.

If type is not supplied, then the file extension of destination is used to "guess" the type. In general it is the extension uppercased and interned in the keyword package. It also recognizes some special cases:

Image type from file extension: special cases

File extension	Image type
"TIF"	:tiff
"DIB"	:bmp
"JPE"	:jpg
"JPEG"	:jpg
"JFIF"	:jpg
"JP2"	:jpg2000

Note: Image type :jpg2000 is implemented on Cocoa only.

errorp controls what happens if externalize-and-write-image does not recognize the type. If errorp is non-nil, it calls error, otherwise it returns nil. The default value of errorp is t.

if-exists controls what to do if destination already exists, in the same way as the if-exists argument to open. However, unlike open, the default value of if-exists is :supersede.

x-hot and y-hot are used only when generating a CUR file, which is currently implemented on GTK+ only. They specify the hotspot coordinates when the image is used as a cursor (in a LispWorks application by load-cursor and (setf capi:simple-pane-cursor), or in other applications). Their values must be integers within the width/height of the image. The default value of both x-hot and y-hot is 0.

quality is used for writing a JPG image on GTK+. It must be an integer in the inclusive range [0,100]. High values generate better images and larger files.

result is destination on success, or nil for an unknown type when errorp is nil. It signals an error in other cases (for example, failure to open the file because of permissions).

Examples

There is a simple example in:

(example-edit-file "capi/graphics/images-with-alpha")

See also

list-known-image-formats
Drawing - Graphics Ports