get-texture

Arguments: hbitmap &optional from-box texture texture-info

See get-pixmap, which provides a better interface to achieving what get-texture does.

This function was called get-pixels in earlier releases. The get-pixels symbol still exists and it names a function identical to get-texture.

This function copies all or part of the image displayed by a window or a bitmap handle into texture and texture-info objects. Two values are returned:

(1) texture containing the pixels copied from the window or bitmap handle, and

(2) texture-info structure that can be used during further processing of the pixel-map.

This function can be used to store pixels from a screen into a file by first calling get-pixels and then calling either save-pixmap (to save as a .bmp file) or save-lisp-pixmap (to save as a Lisp form).

stream-or-texture-handle identifies the object from which to copy the pixel-map. It can be a window, (screen *system*) (see screen and *system*), or a bitmap handle (as created by open-texture). If the window is a bitmap-window or bitmap-pane, then the pixels are copied from the memory bitmap associated with the window, and so the window does not need to be visible on the screen while copying from it. For other types of windows, pixels are copied from the window's interior as that region currently appears on the screen, so you may need to expose and redisplay the window before using get-texture on it.

from-box should be a box structure indicating the area of the window or bitmap handle to copy from. If this argument is not supplied, the page size of the window is used. The default page size for windows is the size of the screen, which causes this function to create very large pixmaps that often result in running out of memory. If this is a problem, you can either pass this from-box argument to specify a smaller area, or use a smaller page-width and -height for the window.

texture can be a scratch pixel-map array that you can pass to avoid creating a new object each time you call get-texture. If this argument is supplied and the texture is at least as wide and as tall as the area being copied, then it will be filled with the copied pixels and returned; otherwise a new pixel-map array is created, filled, and returned. The width of the texture should be a multiple of 32 (though the returned texture-info will contain the actual width of the copied area).

texture-info can be a scratch texture-info that you can pass to avoid consing a new one with each call. If this argument is supplied, it will be modified and returned as the second value; otherwise a new texture-info structure is created and returned.

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.