Function

Summary

Displays an image on a graphics port at a given position.

Package

graphics-ports

Signature

draw-image port image to-x to-y &rest args &key from-x from-y to-width to-height from-width from-height global-alpha

Arguments

port

A graphics port.

image

An image.

to-x, to-y

Real numbers.

args

graphics-state parameters passed as keyword arguments.

from-x , from-y

Real numbers.

to-width, to-height

Real numbers.

from-width , from-height

Real numbers.

global-alpha

A real number in the inclusive range [0,1], or nil.

Description

The function draw-image displays image on the port at to-x to-y .

The default value of from-x and from-y is 0. The from-width and from-height arguments default to the size of the image. In addition, to-width defaults to from-width and to-height defaults to from-height .

When port 's drawing-mode is :compatible, graphics state translation is guaranteed to be supported but support for scaling and rotation are library dependent. Specifically, scaling is supported in the Windows, Cocoa and GTK+ implementations, but not on X11/Motif.

When port 's drawing-mode is :quality, the target coordinates are fully transformed according to the transformation in the graphics-state.

For more information about drawing-mode , see The drawing mode and anti-aliasing.

global-alpha , if non-nil, is a blending factor that applies to the whole image, in the Windows and Cocoa implementations, but not on X11/Motif or GTK+. The value 0 means use only the target (that is, do not draw anything) and the value 1 means use only the source (that is, normal drawing). Intermediate real values mean use proportions of both the target and source. The value nil also means normal drawing, and this is the default value.

Notes

On Microsoft Windows, if the image was loaded from a .ico file then draw-image ignores from-x , from-y , from-width , from-height and the graphics-state operation when drawing the image, and also global-alpha is ignored.

Compatibility note

In LispWorks 6.1 and earlier versions, the to-width and to-height arguments defaulted to the size of the image and from-width defaulted to to-width and from-height defaulted to to-height .

Examples

This example scales an image with various values of from-width , to-width , from-height and to-height . It illustrates the effect of the default of these value which has changed since LispWorks 6.1:

(example-edit-file "capi/graphics/image-scaling")

Further examples:

Draw the whole image at (10 20) without scaling:

(gp:draw-image port image 10 20)

Draw the whole image at (10 20) scaling it to 100x200:

(gp:draw-image port image 10 20

               :to-width 100

               :to-height 200)

Draw a 16x32 pixel rectangle from (60 80) in the image at (10 20) without scaling:

(gp:draw-image port image 10 20

               :from-x 60

               :from-y 80

               :from-width 16

               :from-height 32)

Draw a 16x32 pixel rectangle from (60 80) in the image at (10 20) scaling it to 100x200:

(gp:draw-image port image 10 20

               :from-x 60

               :from-y 80

               :from-width 16

               :from-height 32

               :to-width 100

               :to-height 200)

See also

image
Drawing - Graphics Ports