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.

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 either a bitmap-pane or bitmap-window, 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; otherwisebox should specify the portion of the bitmap-pane's page to copy.

The bits-per-pixell 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.

Copyright (c) 1998-2002, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 6.2. This page was not revised from the 6.1 page.
Created 2002.2.26.