Generic Function | Package: cg | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version

## 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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 10.1 Unrevised from 10.0 to 10.1. 10.0 version