All Manuals > CAPI User Guide and Reference Manual > 22 GRAPHICS-PORTS Reference Entries

externalize-and-write-image 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.

image should be an image that can be drawn to gp. The bytes of image are written to destination as if by write-sequence.

The output image type can be specified by 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 extensionImage 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
13 Drawing - Graphics Ports


CAPI User Guide and Reference Manual (Macintosh version) - 01 Dec 2021 19:31:44