Many of the drawing functions come in pairs. One function in the pair takes two arguments to specify a point by its x and y coordinates; the other function takes one argument, a point object. The function accepting coordinates of the point has a name with an asterisk (*) appended to it, and the function accepting a point object has the same name without an asterisk. For example, draw-point accepts a point object, and draw-point* accepts coordinates of a point. We expect that using the starred functions and specifying points by their coordinates will be more convenient in most cases.
Any drawing functions may create an output record that corresponds to the figure being drawn. 15 Extended Stream Input Facilities for a complete discussion of output recording. During output recording, none of these functions capture any arguments that are points, point sequences, coordinate sequences, or text strings. Line styles, text styles, transformations, and clipping regions may be captured.
The drawing functions are all specified as ordinary functions, not as generic functions. This is intended to ease the task of writing compile-time optimizations that avoid keyword argument taking, check for such things as constant drawing options, and so forth. If you need to specialize any of the drawing methods, use define-graphics-method.
Although the functions in this section are specified to be called on sheets, they can also be called on streams and mediums.
draw-point sheet point &key ink clipping-region transformation line-style line-thickness line-unit
draw-point* sheet x y &key ink clipping-region transformation line-style line-thickness line-unit
Summary: These functions (structured and spread arguments, respectively) draw a single point on the sheet sheet at the point point, or the position (x, y).
The unit and thickness components of the current line style (see 3.2 Using CLIM Drawing Options) affect the drawing of the point by controlling the number of pixels used to render the point on the display device.
draw-points sheet point-seq &key ink clipping-region transformation line-style line-thickness line-unit
draw-points* sheet coord-seq &key ink clipping-region transformation line-style line-thickness line-unit
Summary: These functions (structured and spread arguments, respectively) draw a set of points on the sheet sheet.
For convenience and efficiency, these functions exist as equivalents to:
(map nil #'(lambda (point) (draw-point sheet point)) point-seq)
and:
(do ((i 0 (+ i 2)))
((= i (length coord-seq)))
(draw-point* sheet (elt coord-seq i) (elt coord-seq (+ i 1))))
draw-line sheet point1 point2 &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
draw-line* sheet x1 y1 x2 y2 &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
Summary: These functions (structured and spread arguments, respectively) draw a line segment on the sheet sheet from the point point1 to point2, or from the position (x1, y1) to (x2, y2).
The current line style (see 3.2 Using CLIM Drawing Options) affects the drawing of the line in the obvious way, except that the joint shape has no effect. Dashed lines start dashing at point1.
draw-lines sheet point-seq &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
draw-lines* sheet coord-seq &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
Summary: These functions (structured and spread arguments, respectively) draw a set of disconnected line segments. These functions are equivalent to:
(do ((i 0 (+ i 2)))
((= i (length point-seq)))
(draw-line sheet (elt point-seq i) (elt point-seq (1+ i))))
and:
(do ((i 0 (+ i 4)))
((= i (length coord-seq)))
(draw-line* sheet
(elt coord-seq i) (elt coord-seq (+ i 1))
(elt coord-seq (+ i 2))
(elt coord-seq (+ i 3))))
draw-polygon sheet point-seq &key (filled t) (closed t) ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape line-cap-shape
draw-polygon* sheet coord-seq &key (filled t) (closed t) ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape line-cap-shape
Summary: Draws a polygon or polyline on the sheet sheet. When filled is nil, this draws a set of connected lines; otherwise, it draws a filled polygon. If closed is t (the default) and filled is nil, it ensures that a segment is drawn that connects the ending point of the last segment to the starting point of the first segment. The current line style (see 3.3 CLIM Line Styles for details) affects the drawing of unfilled polygons in the obvious way. The cap shape affects only the "open" vertices in the case when closed is nil. Dashed lines start dashing at the starting point of the first segment, and may or may not continue dashing across vertices, depending on the window system.
If filled is t, a closed polygon is drawn and filled in. In this case, closed is assumed to be t as well.
draw-rectangle sheet point1 point2 &key (filled t) ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape
draw-rectangle* sheet x1 y1 x2 y2 &key (filled t) ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape
Summary: Draws either a filled or unfilled rectangle on the sheet sheet that has its sides aligned with the coordinate axes of the native coordinate system. One corner of the rectangle is at the position (x1, y1) or point1 and the opposite corner is at (x2, y2) or point2. The arguments x1, y1, x2, and y1 are real numbers that are canonicalized in the same way as for make-bounding-rectangle. filled is as for draw-polygon*.
The current line style (see 3.2 Using CLIM Drawing Options) affects the drawing of unfilled rectangles in the obvious way, except that the cap shape has no effect.
draw-rectangles sheet points &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape
draw-rectangles* sheet position-seq &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-joint-shape
Summary: These functions (structured and spread arguments, respectively) draw a set of rectangles on the sheet sheet. points is a sequence of point objects; position-seq is a sequence of coordinate pairs. It is an error if position-seq does not contain an even number of elements.
Ignoring the drawing options, these functions are equivalent to:
(do ((i 0 (+ i 2)))
((= i (length points)))
(draw-rectangle sheet (elt points i) (elt points (1+ i))))
and:
(do ((i 0 (+ i 4)))
((= i (length position-seq)))
(draw-rectangle* sheet
(elt position-seq i)
(elt position-seq (+ i 1))
(elt position-seq (+ i 2))
(elt position-seq (+ i 3))))
draw-ellipse sheet center-pt radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key (filled t) start-angle end-angle ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
draw-ellipse* sheet center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy &key (filled t) start-angle end-angle ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
Summary: These functions (structured and spread arguments, respectively) draw an ellipse (when filled is t, the default) or an elliptical arc (when filled is nil) on the sheet sheet. The center of the ellipse is the point center-pt, or the position (center-x, center-y).
Two vectors, (radius-1-dx, radius-1-dy) and (radius-2-dx, radius-2-dy) specify the bounding parallelogram of the ellipse as explained in 2.5 General Geometric Objects in CLIM All of the radii are real numbers. If the two vectors are collinear, the ellipse is not well-defined and the ellipse-not-well-defined error will be signaled. The special case of an ellipse with its major axes aligned with the coordinate axes can be obtained by setting both radius-1-dy and radius-2-dx to 0.
start-angle and end-angle are real numbers that specify an arc rather than a complete ellipse. Angles are measured with respect to the positive x axis. The elliptical arc runs positively (counter-clockwise) from start-angle to end-angle. The default for start-angle is 0; the default for end-angle is 2π.
In the case of a "filled arc" (that is, when filled is t and start-angle or end-angle are supplied and are not 0 and 2π), the figure drawn is the "pie slice" area swept out by a line from the center of the ellipse to a point on the boundary as the boundary point moves from start-angle to end-angle.
When drawing unfilled ellipses, the current line style (see 3.2 Using CLIM Drawing Options) affects the drawing in the obvious way, except that the joint shape has no effect. Dashed elliptical arcs start dashing at start-angle.
draw-circle sheet center-pt radius &key (filled t) start-angle end-angle ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
draw-circle* sheet center-x center-y radius &key (filled t) start-angle end-angle ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
Summary: These functions (structured and spread arguments, respectively) draw a circle (when filled is t, the default) or a circular arc (when filled is nil) on the sheet sheet. The center of the circle is center-pt or (center-x, center-y) and the radius is radius. These are just special cases of draw-ellipse and draw-ellipse*. filled is as for draw-ellipse*.
start-angle and end-angle allow the specification of an arc rather than a complete circle in the same manner as that of the ellipse functions.
The "filled arc" behavior is the same as that of an ellipse.
draw-text sheet string-or-char point &key text-style (start 0) end (align-x :left) (align-y :baseline) toward-point transform-glyphs ink clipping-region transformation text-style text-family text-face text-size
draw-text* sheet string-or-char x y &key text-style (start 0) end (align-x :left) (align-y :baseline) toward-x toward-y transform-glyphs ink clipping-region transformation text-style text-family text-face text-size
Summary: The text specified by string-or-char is drawn on the sheet sheet starting at the position specified by the point point, or the position (x, y). The exact definition of "starting at" depends on align-x and align-y. align-x is one of :left, :center, or :right. align-y is one of :baseline, :top, :center, or :bottom. align-x defaults to :left and align-y defaults to :baseline; with these defaults, the first glyph is drawn with its left edge and its baseline at point.
text-style defaults to nil, meaning that the text will be drawn using the current text style of the sheet's medium.
start and end specify the start and end of the string, in the case where string-or-char is a string. If start is supplied, it must be an integer that is less than the length of the string. If end is supplied, it must be an integer that is less than the length of the string, but greater than or equal to start.
Normally, glyphs are drawn from left to right no matter what transformation is in effect. toward-x or toward-y (derived from toward-point in the case of draw-text) can be used to change the direction from one glyph to the next one. For example, if toward-x is less than the x position of point, then the glyphs will be drawn from right to left. If toward-y is greater than the y position of point, then the glyphs' baselines will be positioned one above another. More precisely, the reference point in each glyph lies on a line from point to toward-point, and the spacing of each glyph is determined by packing rectangles along that line, where each rectangle is "char-width" wide and "char-height" high.
transform-glyphs is not supported in this version of CLIM.
CLIM also provides a few compound drawing functions. The compound drawing functions could be composed by a programmer from the basic drawing functions, but are provided by CLIM because they are commonly used.
draw-arrow sheet point-1 point-2 &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape to-head from-head head-length head-width
draw-arrow* sheet x1 y1 x2 y2 &key ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape from-head to-head head-length head-width
Summary: These functions (structured and spread arguments, respectively) draw a line segment on the sheet sheet from the point point1 to point2, or from the position (x1, y1) to (x2, y2). If to-head is t (the default), then the "to" end of the line is capped by an arrowhead. If from-head is t (the default is nil), then the "from" end of the line is capped by an arrowhead. The arrowhead has length head-length (default 10) and width head-width (default 5).
The current line style (see 3.2 Using CLIM Drawing Options) affects the drawing of the line portion of the arrow in the obvious way, except that the joint shape has no effect. Dashed arrows start dashing at point1.
draw-oval sheet center-pt x-radius y-radius &key (filled t) ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
draw-oval* sheet center-x center-y x-radius y-radius &key (filled t) ink clipping-region transformation line-style line-thickness line-unit line-dashes line-cap-shape
Summary: These functions (structured and spread arguments, respectively) draw a filled or unfilled oval (that is, a "race-track" shape) on the sheet sheet. The oval is centered on center-pt, or (center-x, center-y). If x-radius or y-radius is 0, then a circle is drawn with the specified non-zero radius. Otherwise, a figure is drawn that is a rectangle with dimension x-radius by y-radius, with the two short sides replaced by a semicircular arc of the appropriate size.
Patterning creates a bounded rectangular arrangement of designs, like a checkerboard. Drawing a pattern draws a different design in each rectangular cell of the pattern. To create an infinite pattern, apply make-rectangular-tile to a pattern.
A stencil is a special kind of pattern that contains only opacities.
make-pattern array inks
Summary: Returns a pattern ink that has (array-dimension array 0) cells in the vertical direction and (array-dimension array 1) cells in the horizontal direction. array must be a two-dimensional array of non-negative integers less than the length of inks. inks must be a sequence of designs. The design in cell (i, j) of the resulting pattern is the nth element of inks, if n is the value of (aref array i j). For example, array can be a bit-array and inks can be a list of two inks, the ink drawn for 0 and the one drawn for 1.
Each cell of a pattern can be regarded as a hole that allows the ink in it to show through. Each cell might have a different ink in it. The portion of the ink that shows through a hole is the portion on the part of the drawing plane where the hole is located. In other words, incorporating an ink into a pattern does not change its alignment to the drawing plane, and does not apply a coordinate transformation to the design. Drawing a pattern collects the pieces of inks that show through all the holes and draws the pieces where the holes lie on the drawing plane. The pattern is completely transparent outside the area defined by the array.
This function captures its mutable inputs; the consequences of modifying those objects are unspecified.
Tiling repeats a rectangular portion of a pattern throughout the drawing plane.
make-rectangular-tile Function
make-rectangular-tile pattern width height
Summary: Returns a pattern that, when used as an ink, tiles a rectangular portion of the pattern pattern across the entire drawing plane. The resulting pattern repeats with a period of width horizontally and height vertically. width and height must both be integers. The portion of pattern that appears in each tile is a rectangle whose top-left corner is at (0, 0) and whose bottom-right corner is at (width, height). The repetition of pattern is accomplished by applying a coordinate transformation to shift pattern into position for each tile, and then extracting a width-by-height portion of that pattern.
Applying a coordinate transformation to a rectangular tile does not change the portion of the argument pattern that appears in each tile. However, it can change the period, phase, and orientation of the repeated pattern of tiles. This is so that adjacent figures drawn using the same tile have their inks "line up".
draw-pattern* sheet pattern x y &key clipping-region transformation
Summary: Draws the pattern pattern on the sheet sheet at the position (x, y). pattern is any pattern created by make-pattern. clipping-region and transformation are as for with-drawing-options or any of the drawing functions.
Note that transformation only affects the position at which the pattern is drawn, not the pattern itself. If you want to affect the pattern, you should explicitly call transform-region on the pattern.
You draw a bitmap by drawing an appropriately aligned and scaled pattern constructed from the bitmap's bits. A 1 in the bitmap corresponds to +foreground- ink+. A 0 corresponds to +background-ink+ if an opaque drawing operation is desired, or to +nowhere+ if a transparent drawing operation is desired.
Drawing a (colored) raster image consists of drawing an appropriately aligned and scaled pattern constructed from the raster array and raster color map.
draw-pattern* could be implemented as follows, assuming that the functions pattern-width and pattern-height return the width and height of the pattern.
(defun draw-pattern* (sheet pattern x y &key clipping-region
transformation)
(check-type pattern pattern)
(let ((width (pattern-width pattern))
(height (pattern-height pattern)))
(if (or clipping-region transformation)
(with-drawing-options
(sheet
:clipping-region clipping-region
:transformation transformation)
(draw-rectangle* sheet x y
(+ x width) (+ y height)
:filled t :ink pattern))
(draw-rectangle* sheet x y (+ x width) (+ y height)
:filled t :ink pattern))))
A pixmap can be thought of as an "off-screen window," that is, a medium that can be used for graphical output, but that is not visible on any display device. Pixmaps are provided to allow a programmer to generate a piece of output associated with some display device that can then be rapidly drawn on a real display device. For example, an electrical CAD system might generate a pixmap that corresponds to a complex, frequently-used part in a VLSI schematic, and then use copy-from-pixmap to draw the part as needed.
The exact representation of a pixmap is explicitly unspecified. There is no interaction between the pixmap operations and output recording; that is, displaying a pixmap on a medium is a pure drawing operation that affects only the display, not the output history. Some mediums may not support pixmaps; in this case, an error will be signaled.
allocate-pixmap Generic Function
allocate-pixmap medium width height
Summary: Allocates and returns a pixmap object that can be used on any medium that shares the same characteristics as medium. (What constitutes "shared characteristics" varies from host to host.) medium can be a sheet, a medium, or a stream.
The resulting pixmap will be width units wide, height units high, and as deep as is necessary to store the information for the medium. The exact representation of pixmaps is explicitly unspecified. The returned value is the pixmap.
deallocate-pixmap Generic Function
deallocate-pixmap pixmap
Summary: Deallocates the pixmap pixmap.
pixmap-width pixmap
pixmap-height Generic Function
pixmap-height pixmap
pixmap-depth pixmap
Summary: These functions return, respectively, the programmer-specified width, height, and depth of the pixmap pixmap.
copy-to-pixmap Generic Function
copy-to-pixmap medium medium-x medium-y width height &optional pixmap (pixmap-x 0) (pixmap-y 0)
Summary: Copies the pixels from the medium medium starting at the position specified by (medium-x, medium-y) into the pixmap pixmap at the position specified by (pixmap-x, pixmap-y). A rectangle whose width and height is specified by width and height is copied. medium-x and medium-y are specified in user coordinates. (If medium is a medium or a stream, then medium-x and medium-y are transformed by the user transformation.)
If pixmap is not supplied, a new pixmap will be allocated. Otherwise, pixmap must be an object returned by allocate-pixmap that has the appropriate characteristics for medium.
The returned value is the pixmap.
copy-from-pixmap Generic Function
copy-from-pixmap pixmap pixmap-x pixmap-y width height medium window-x window-y
Summary: Copies the pixels from the pixmap pixmap starting at the position specified by (pixmap-x, pixmap-y) into the medium medium at the position (medium-x, medium-y). A rectangle whose width and height is specified by width and height is copied. medium-x and medium-y are specified in user coordinates. (If medium is a medium or a stream, then medium-x and medium-y are transformed by the user transformation.)
pixmap must be an object returned by allocate-pixmap that has the appropriate characteristics for medium.
The returned value is the pixmap. This is intended to specialize on both the pixmap and medium arguments.
copy-area medium from-x from-y width height to-x to-y
Summary: Copies the pixels from the medium medium starting at the position specified by (from-x, from-y) to the position (to-x, to-y) on the same medium. A rectangle whose width and height is specified by width and height is copied. from-x, from-y, to-x, and to-y are specified in user coordinates. (If medium is a medium or a stream, then medium-x and medium-y are transformed by the user transformation.)
with-output-to-pixmap (medium-var medium &key width height) &body body
Summary: Binds medium-var to a "pixmap medium" (that is, a medium that does output to a pixmap with the characteristics appropriate to the medium medium) and then evaluates body in that context. All the output done to the medium designated by medium-var inside of body is drawn on the pixmap stream. The pixmap medium supports the medium output protocol, including all of the graphics functions.
width and height are integers that give the dimensions of the pixmap. If they are omitted, the pixmap will be large enough to contain all the output done by body.
medium-var must be a symbol; it is not evaluated. The returned value is a pixmap that can be drawn onto medium using copy-from-pixmap.
CLIM 2.0 User Guide - 01 Dec 2021 19:38:56