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




Externalizes and writes an image to file.




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



A CAPI pane.


An image object.


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).


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


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


A boolean.


A non-negative integer.


A non-negative integer.


An integer in the range [0,100].



A filename or nil.


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













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).


There is a simple example in:

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

Drawing - Graphics Ports

CAPI User Guide and Reference Manual (Macintosh version) - 3 Aug 2017