get-pixmap

Arguments: stream &key box

Creates and returns a pixmap that is a copy of the image that is currently displayed in some rectangular area of the screen. The argument stream may be either the screen itself or a window (the screen is the value of (screen *system*), see screen and *system*). If box is nil, then the area of the screen that is covered by the entire interior of stream is copied; otherwise box should be a box (see make-box) that specifies a portion of the page (scrollable canvas) of stream, to indicate the area of the screen to copy. When stream is the screen, then the box argument must be specified.

Note that the image copied is whatever appears on the screen at that moment; if other windows are covering stream then whatever covers the specified area of stream is what is copied. Therefore, when passing a window (rather than the screen) to get-pixmap, an application typically will first ensure that the window being copied is not covered by other windows, and that the desired part of the window's page is currently scrolled into the window.

An exception to the above is that if stream is a bitmap-pane, then the image is copied from the memory bitmap of the bitmap-pane rather than from the screen. If box is nil, then the entire page of the bitmap-pane is copied; otherwise box should specify the portion of the bitmap-pane's page to copy. (The bitmap-pane of a bitmap-window may be found by calling frame-child on the bitmap-window.)

Another exception is that if the double-buffered property of a window is true, then get-pixmap will return an image from the window even if the window is covered, but only for the part of the window's page that is currently scrolled into the window's interior (see visible-box). The reason is that a double-buffered window has a memory bitmap, but only for the interior area of the window.

The bits-per-pixel of the returned pixmap is always the same as the bits-per-pixel of the screen. This value depends on the end user's global operating system settings; in Windows this is set in the Display area of Control Panel.

get-pixmap is functionally equivalent to the older function get-texture (called get-pixels in earlier releases), except that it returns the new higher-level pixmap object rather than separate texture and texture-info objects, and the optional texture and texture-info parameters are not present on get-pixmap (to avoid consing these arguments).

See also get-screen-pixmap.

GTK Note

It does not work to pass the screen to get-pixmap on GTK; you must pass a window instead. (If you do pass the screen, the *gtk-compatibility-warning-action* will be invoked.) When called on a region of a window that is not visible, it may return whatever is on the screen at that location, but this cannot be guaranteed by Common Graphics.

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.