Externalizes and writes an image to file.
graphics-ports
externalize-and-write-image gp image destination &key type if-exists errorp x-hot y-hot quality &allow-other-keys => result
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]. |
result⇩ |
A filename or nil . |
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:
File extension | Image type |
---|---|
"TIF" |
|
"DIB" |
|
"JPE" |
|
"JPEG" |
|
"JFIF" |
|
"JP2" |
|
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")
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:33:02