7.3 Image Functions

create-image

&key :bit-lsb-first-p :bits-per-pixel :blue-mask :byte-lsb-first-p :bytes-per-line :data :depth :format :green-mask :height :name :plist :red-mask :width :x-hot :y-hot

Function

:bit-lsb-first-p: For a returned image, true if the order of bits in each :data byte is least-significant bit first.
:bits-per-pixel: One of 1, 4, 8, 16, 24, or 32.
:blue-mask: For :true-color or :direct-color images, a pixel mask.
:byte-lsb-first-p: For a returned image, true if the :data byte order is least-significant byte first.
:bytes-per-line: For a returned image, the number of :data bytes per scanline.
:data: Either a list of bitmaps, a pixarray, or an array of card8 bytes.
:depth: The number of bits per displayed pixel.
:format: One of :bitmap, :xy-format, or :z-format.
:green-mask: For :true-color or :direct-color images, a pixel mask.
:height: A card16 for the image height in pixels.
:name: An optional stringable for the image name.
:plist: An optional image property list.
:red-mask: For :true-color or :direct-color images, a pixel mask.
:width: A card16 for the image width in pixels.
:x-hot: For a cursor image, the x position of the hot spot.
:y-hot: For a cursor image, the y position of the hot spot.

Creates an image object from the given :data and returns either an image, image-xy, or an image-z, depending on the type of image :data. If the :data is a list, it is assumed to be a list of bitmaps and an image-xy is created. If the :data is a pixarray, an image-z is created. Otherwise, the :data must be an array of bytes (card8), in which case a basic image object is created.

If the :data is a list, each element must be a bitmap of equal size. :width and :height default to the bitmap width -- (array-dimension bitmap 1) -- and the bitmap height -- (array-dimension bitmap 0) -- respectively. :depth defaults to the number of bitmaps.

If the :data is a pixarray, :width and :height default to the pixarray width -- (array-dimension pixarray 1), and the pixarray height -- (array-dimension pixarray 0), respectively. :depth defaults to (pixarray-depth :data). The :bits-per-pixel is rounded to a valid size, if necessary. By default, the :bits-per-pixel is equal to the :depth.

If the :data is an array of card8, the :width and :height are required to interpret the image data correctly. The :bits-per-pixel defaults to the :depth, and the :depth defaults to 1. :bytes-per-line defaults to:

(floor (length :data) (* :bits-per-pixel :height))

The :format defines the storage format of image data bytes and can be one of the following values:

:xy-pixmap: The :data is organized as a set of bitmaps representing image bit planes, appearing in most-significant to least-significant bit order.
:z-pixmap: The :data is organized as a set of pixel values in scanline order.
:bitmap: Similar to :xy-pixmap, except that the :depth must be 1, and 1 and 0 bits represent the foreground and background pixels, respectively.

By default, the :format is :bitmap if :depth is 1; otherwise, :z-pixmap.

image: Type image.

copy-image

image &key (:x 0) (:y 0) :width :height :result-type

Function

image: An image object.
:x, :y: card16 values defining the position of the upper-left corner of the subimage copied.
:width, :height: card16 values defining the size of subimage copied.
:result-type: One of 'image-x, 'image-xy, or 'image-z.

Returns a new image, of the given :result-type, containing a copy of the portion of the image defined by :x, :y, :width, and :height. By default, :width is:

(- (image-width image) :x)

and :height is:

(- ( image-height image) :y)

If necessary, the new image is converted to the :result-type , that can be one of the following values:

'image-x: A basic image object is returned.
'image-xy: An image-xy is returned.
'image-z: An image-z is returned.

new-image: Type image.

get-image

drawable &key :x :y :width :height :plane-mask (:format :z-format ) :result-type

Function

drawable: A drawable.
:x, :y: card16 values defining the upper-left drawable pixel returned. These arguments are required.
:width, :height: card16 values defining the size of the image returned. These arguments are required.
:plane-mask: A pixel mask.
:format: Either :xy-pixmap or :z-pixmap.
:result-type: One of 'image-x, 'image-xy, or 'image-z.

Returns an image containing pixel values from the region of the drawable given by :x, :y, :width , and :height. The bits for all planes selected by 1 bits in the :plane-mask are returned as zero; the default :plane-mask is all 1 bits. The :format of the returned pixel values may be either :xy-format or :z-format.

The :result-type defines the type of image object returned:

'image-x: A basic image object is returned.
'image-xy: An image-xy is returned.
'image-z: An image-z is returned.

By default, :result-type is 'image-z if :format is :z-format and 'image-xy if :format is :xy-format.

image: Type image.

put-image

drawable gcontext image &key (:src-x 0) (:src-y 0) :x :y :width :height :bitmap-p

Function

drawable: The destination drawable.
gcontext: The graphics context used to display the image.
image: An image object.
:src-x, :src-y: card16 values defining the upper-left position of the image region to display.
:x, :y: The position in the drawable where the image region is displayed. These arguments are required.
:width, :height: card16 values defining the size of the image region displayed.
:bitmap-p: If image is depth 1, then if true, foreground and background pixels are used to display 1 and 0 bits of the image.

Displays a region of the image defined by :src-x, :src-y, :width, and :height on the destination drawable, with the upper-left pixel of the image region displayed at the drawable position given by :x and :y. By default, :width is:

(- (image-width image) :src-x)

and :height is:

(- ( image-height image) :src-y)

The following attributes of the gcontext are used to display the image: clip-mask, clip-x, clip-y, function, plane-mask, and subwindow-mode.

The :bitmap-p argument applies only to images of depth 1. In this case, if :bitmap-p is true or if the image is a basic image object created with :format :bitmap, the image is combined with the foreground and background pixels of the gcontext. 1 bits of the image are displayed in the foreground pixel and 0 bits are displayed in the background pixel.