load-pixmap

Arguments: pathname &key name pixmap-to-return (icon-index 0) make-unique-name use-gdi-plus

Loads a pixmap (pixel map) from a file and returns a cg:pixmap object. The pixmap can then be drawn by calling copy-to-stream.

The file can be any of the various types of pixmap files that can be loaded by the underlying windowing system (Windows or GTK). On any platform these should include bmp, png, jpg, gif, and tiff files along with others. On Windows, icon files (.ico) can also be loaded.

The arguments are:

• pathname: a pathname or path namestring naming the file from which to load the pixmap. The file should be either a .bmp (Windows bitmap), .ico (icon) or .cur (mouse cursor) file. An error is signaled if this file does not exist or if its contents are not in the standard format of one of the valid types of files.
• name: a symbol that will be used for the name of the pixmap. This symbol may be used in later calls to find-pixmap (if the pixmap is first cached by calling cache-pixmap), and appears in the print name of the pixmap. If nil, a unique symbol based on the name of the file from which the pixmap was loaded is created and used for the name.
• pixmap-to-return: either nil or an existing pixmap object to re-use. If nil, a new pixmap object is created and returned. If a pixmap, the pixmap is "filled in" with the information read from the file and then returned. This argument may be useful for updating a pixmap object from an edited (or alternate) file while keeping the pixmap eq to the former version of it.
• icon-index: a non-negative integer indicating which icon to read from a .ico icon file, where zero indicates the first icon. The default is zero. This argument applies only if pathname names a .ico icon file, and will be ignored if pathname names a .bmp pixmap file.
• make-unique-name: if true, ensures that the name for the pixmap (typically taken from the filename) is not already in use as the name of a cached pixmap.
• use-gdi-plus: this argument is used only on the Windows platform, and only for bmp files. Through Allegro CL release 9.0, Common Graphics on Windows could load only bmp files. Common Graphics loaded a bmp file by parsing the file contents in lisp. Now Common Graphics uses the newer GDI+ API of Windows, where Windows can load a variety of types of pixmap files itself. But for backward compatibility, if the file is a bmp file then by default the file will still be loaded "by hand" the old way. (We expect no difference in behavior, but are being cautious.) To use the new approach even if the file is a bmp file, pass use-gdi-plus as true.

See also save-pixmap (which creates .bmp files) and load-lisp-pixmap (which loads a Lisp file which will recreate a pixmap). cg-pixmaps.htm discusses pixmaps in general.

Issue with locad-pixmap and GTM on Macs

There is a known but unsolved problem with load-pixmap on the Mac. On the GTK platforms (Linux and Mac), load-pixmap simply passes the pixmap file path to a single GTK function, and GTK does all the work. But it seems to fail on the Mac even for pixmaps where it works on Linux. We suspect that something in the substrate of GTK on the Mac is not supporting this GTK function properly.

One possible workaround is to create pixmaps from Lisp arrays of pixel values, as described in cg-pixmaps.htm. But note if you're starting with BMP files, the only way to use that approach would be to use the function import-pixmaps on a Linux or Windows machine that is able to load the BMP files, and then take the file of Lisp source code that it writes over to your application on the Mac and load the Lisp file there. When building a standalone application, if you load the Lisp file at build time then the pixmaps will be built into the image file and so will not need to be loaded from separate files at run time.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had significant revisions compared to the 9.0 page.
Created 2019.8.20.