copy-to-stream

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

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.

The alpha argument is used only on Windows, and only when the variable *alpha-blending* is true. It can create translucent effects where the existing background partly "shows through" the pixmap that is being displayed. Its value should be either nil or an integer between 0 and 255 inclusive. If 255, nil, or unspecified, the pixmap will be drawn with full opacity. Otherwise the value specifies the amount of opacity, where 0 would make the pixmap completely transparent and unseen (not useful), and where for example 192 would let the previous background show through by one-fourth. See the variable *alpha-blending* for more information.

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-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
The object described on this page has been modified in the 10.0 release; see the Release Notes.
Created 2019.8.20.