open-pixmap-handle

Arguments: pixmap &key recreate window

Tells the operating system to create a "device-dependent bitmap" from the texture of the specified Common Graphics pixmap oject (passed as the pixmap argument), and sets the pixmap-handle property of pixmap to be the handle to that device-dependent pixmap. (The pixels and colormap of a device-dependent pixmap are managed in the operating system rather than in Lisp.) If the pixmap has a mask texture (in the mask property), open-pixmap-handle also creates a device-dependent bitmap for the mask texture and stores it in the mask-handle property of the pixmap.

After this is done, whenever the pixmap is drawn the drawing will be accomplished by passing this pixmap handle to the operating system rather than by sending an array of all of the actual pixels plus the pixmap's color palette to the operating system each time. If the pixmap uses a palette that contains colors other than the 20 colors in the default system palette, and the user is running Windows in something less than 24-bit true-color mode (which is now atypical), then the pixmap will be drawn using the correct colors only if (1) the window argument is passed here, (2) that window currently has a palette that contains all of the pixmap's colors, and (3) the pixmap is drawn only in that window without changing that window's palette in the interim.

close-pixmap-handle may be called later to get rid of the device-dependent pixmap if desired, and the pixmap will be drawn thereafter from its lisp texture once again. open-pixmap-handle does nothing if the pixmap object already has a handle, unless recreate is true, in which case the old pixmap handle will be closed and a new one created. Using a pixmap handle may result in faster drawing, especially of larger pixmaps, but the device-dependent pixmap will also consume operating system pixmap resources.

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.