copy-pixels-to-stream-from-file

Arguments: filename &optional stream position

This function reads a pixmap file and copies the image to stream. stream should be a cg-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. It indicates the stream to draw the pixmap on. If nil, a bitmap-stream 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, 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, 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 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.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.