7.3 Image Functions

The following paragraphs describe the CLX functions used to:



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.