2.4 Graphics Protocols

Every medium implements methods for the various graphical drawing generic functions. Furthermore, every sheet that supports the standard output protocol implements these methods as well; often, the sheet methods will simply call the same methods on the sheet's medium.

2.4.1 Arguments

• All these generic functions take the same arguments as the non-generic spread function equivalents, except that the arguments that are keyword arguments in the non-generic functions are required arguments in the generic functions.
• The drawing-function-specific arguments are either x and y positions, or a sequence of x and y positions. Note that these positions will first be transformed by the medium's current transformation, and then transformed a second time by the medium's device transformation in order to produce the coordinates as they will actually appear on the screen.
• The ink, line style (or text style), and clipping regions arguments are optional, and default from the medium, based on medium-ink, medium-line-style (or medium-current-text-style), and medium-clipping-region, respectively.

2.4.2 General Behavior of Drawing Functions

Using draw-line* as an example, calling any of the drawing functions specified previously results in the following series of function calls on a non-output recording sheet:

• A program calls draw-line* on arguments sheet, x1, y1, x2, and y2, and perhaps some drawing options.
• draw-line* merges the supplied drawing options into the sheet's medium, and then calls medium-draw-line* on the sheet. (Note that a compiler macro could detect the case where there are no drawing options or constant drawing options, and do this at compile time.)
• medium-draw-line* on the sheet calls the same method—medium-draw-line*—on the medium.
• medium-draw-line* performs the necessary user transformations by applying the medium transformation to x1, y1, x2, and y2, and to the clipping region.

2.4.3 Medium-Specific Drawing Functions

All mediums and all sheets that support the standard output protocol implement methods for the following generic functions.

medium-draw-point* Generic Function

medium-draw-point* medium x y

Summary: Draws a point on the medium medium.

medium-draw-points* Generic Function

medium-draw-points* medium coord-seq

Summary: Draws a set of points on the medium medium.

medium-draw-line* Generic Function

medium-draw-line* medium x1 y1 x2 y2

Summary: Draws a line from (x1, y1) to (x2, y2) on the medium medium.

medium-draw-lines* Generic Function

medium-draw-lines* medium coord-seq

Summary: Draws a set of disconnected lines on the medium medium.

medium-draw-polygon* Generic Function

medium-draw-polygon* medium coord-seq closed

Summary: Draws a polygon or polyline on the medium medium.

medium-draw-rectangle* Generic Function

medium-draw-rectangle* medium x1 y1 x2 y2

Summary: Draws a rectangle whose corners are at (x1, y1) and (x2, y2) on medium.

medium-draw-ellipse* Generic Function

medium-draw-ellipse* medium center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy start-angle end-angle

Summary: Draws a rectangle on medium. The center is at (center-x, center-y). The vectors (radius-1-dx, radius-1-dy) and (radius-2-dx, radius-2-dy) specify the radii. start-angle and end-angle are real numbers that specify an arc, not a complete ellipse.

medium-draw-text* Generic Function

medium-draw-text* medium text x y (start 0) end (align-x :left) (align-y :baseline) toward-x toward-y transform-glyphs

Summary: Draws a character or a string on the medium medium. The text is drawn starting at (x, y), and towards (toward-x, toward-y).