copy-to-stream

Arguments: pixmap-or-cursor stream &optional to-box-or-position from-box-or-nil (mode po-replace)

Copies a pixmap object or a cursor object to stream. stream should be a cg-stream. This function replaces the older function copy-pixels-to-stream, which required the use of separate texture and texture-info objects.

If from-box-or-nil is a box, this function copies the from-box-or-nil portion of pixmap-or-cursor to the to-box-or-position portion of stream, using a particular pixel-combination mode. If from-box-or-nil is nil, the whole pixmap or cursor is copied.

If to-box-or-position is a box, the pixmap-or-cursor is copied to that box and is stretched (if necessary) as with copy-pixels-to-stream. If to-box-or-position is a position, then the pixmap or cursor is copied without stretching so its upper left corner is at the position. If to-box-or-position is nil (the default), then the pixmap or cursor is copied without stretching to position 0,0 of stream.

If pixmap-or-cursor has a mask texture, then copy-pixels-with-mask-to-stream is called internally in order to use it. Otherwise copy-pixels-to-stream is called internally. If pixmap-or-cursor has a pixmap-handle, then that is used for drawing the pixmap, and otherwise the pixmap's texture is used.

mode may be any value that is valid as the paint-operation of a stream. copy-to-stream always uses the value of this mode argument, rather than using the stream's current paint-operation as other drawing functions do. The default value is po-replace. See paint-operation for more information on the various choices.

Instead of passing a pixmap object, you can alternately pass either a cursor object, a pixmap handle, or a symbol that is bound to a pixmap, cursor, or pixmap handle. copy-to-stream will not work on a cursor object if calling texture on it returns nil, as is the case with several cursors supplied by the operating system, because Common Graphics does not have the pixel array to copy.

To fill an area by tiling a pixmap rather than by stretching it, call replicate-pixmap instead.

For an overview of pixmaps, see cg-pixmaps.htm.

GTK Note

If the pixmap has a mask and a call to copy-to-stream stretches the pixmap, then the masking will not be done correctly. We don't know whether we will find a reasonable way to make this work in the future.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.