Arguments: filename &optional stream position
This function reads a pixmap file and copies the image to a window, bitmap-stream, or printer stream. This function may be useful for displaying many large pixmaps without the overhead of creating lisp representations of each pixmap, since the pixels are transferred directly from the file to the stream without creating any lisp array to store them in. No pixmap object is created, so the individual pixels cannot be examined in lisp (except by calling "pixel" or "pixel-x-y" to ask the stream for its pixel values).
filename is a pathname or path namestring indicating the file to read the pixmap from. This file should be either a .bmp (device-independent bitmap), .ico (icon), or .cur (cursor) file.
stream is either a window, a bitmap-stream, a
printer stream, or nil, indicating the stream
to draw the pixmap on. If nil, a hidden
bitmap-pane is created and used. If the pixmap is to be used in
multiple places or at multiple times in the interface, it may be
useful to call this function once to store the pixmap on a
bitmap-stream or hidden bitmap-pane, and then copy the image from
there to a window with copy-stream-area
whenever needed.
position is a position or nil, indicating where to position the upper left
corner of the pixmap on stream. If nil, the
image is positioned in the upper left corner of the stream.
Two values are returned:
(1) the stream that was passed in or created,
(2) a texture-info containing the dimensions, depth, and colors of the pixmap.
Note that if stream is a bitmap-pane or bitmap-window, then the image is copied to the backing store of the window but not to the visible window itself. The image may then be viewed at any time by calling invalidate-window on the window. This allows loading a new pixmap into the window while the end user is still viewing the previous pixmap, and then to very quickly switch to the new pixmap when the user is ready.
Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.
The documentation is described in introduction.htm and the index is in index.htm.
Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.
Created 2000.10.5.