********************* DUIM-Graphics Library ********************* .. current-library:: duim-graphics .. current-module:: duim-graphics Overview ======== The DUIM-Graphics library contains interfaces that define a wide variety drawing operations for use in your GUI applications, as well as two classes. The library contains a single module, *duim-graphics*, from which all the interfaces described in this chapter are exposed. `DUIM-Graphics Module`_ contains complete reference entries for each exposed interface. The DUIM graphic drawing model is an idealized model of graphical pictures. The model provides the language that application programs use to describe the intended visual appearance of textual and graphical output. Usually not all of the contents of the screen are described using the graphic drawing model. For example, menus and scroll bars would usually be described in higher-level terms. An important aspect of the DUIM graphic drawing model is its extreme device independence. The model describes ideal graphical images and ignores limitations of actual graphics devices. One consequence of this is that the actual visual appearance of the screen can only be an approximation of the appearance specified by the model: however, another important consequence of this is that the model is highly portable. DUIM separates output into two layers: A text/graphics layer in which you specify the desired visual appearance independent of device resolution and characteristics #. A rendering layer in which some approximation of the desired visual appearance is created on the device. Of course application programs can inquire about the device resolution and characteristics if they wish and modify their desired visual appearance on that basis. There is also a third layer above these two layers, the adaptive toolkit layer where one specifies the desired functionality rather than the desired visual appearance. Definitions =========== This section contains definitions of terms that will be used in this chapter. - *Drawing plane* A drawing plane is an infinite two-dimensional plane on which graphical output occurs. The drawing plane contains an arrangement of colors and opacities that is modified by each graphical output operation. It is not possible to read back the contents of a drawing plane, except by examining the output-history. Normally each window has its own drawing plane. - *Coordinates* Coordinates are a pair of real numbers in implementation-defined units that identify a point in the drawing plane. - *Mediums* In this chapter, we use a medium as a destination for output. The medium has a drawing plane, two designs (called the medium's foreground and background), a transformation, a clipping region, a line style, and a text style. There are per-medium, dynamically scoped, default drawing options. Different medium classes are provided to allow you to draw on different sorts of devices, such as displays, printers, and virtual devices such as bitmaps. - *Sheets* Many sheets can be used for doing output, so the drawing functions can also take a sheet as the output argument. In this case, drawing function "trampolines" to the sheet's medium. So, while the functions defined here are specified to be called on mediums, they can also be called on sheets. - *Streams* A stream is a special kind of sheet that implements the stream protocol; streams include additional state such as the current text cursor (which is some point in the drawing plane). - By default, the "fundamental" coordinate system of a DUIM stream (not a general sheet or medium, whose fundamental coordinate system is not defined) is a left handed system with x increasing to the right, and y increasing downward. (0,0) is at the upper left corner. - For more general information about DUIM streams, you should refer to the manual *Library Reference: System and I/O*. Drawing is approximate ====================== Note that although the drawing plane contains an infinite number of mathematical points, and drawing can be described as an infinite number of color and opacity computations, the drawing plane cannot be viewed directly and has no material existence: it is only an abstraction. What *can* be viewed directly is the result of rendering portions of the drawing plane onto a medium. No infinite computations or objects of infinite size are required to implement DUIM, because the results of rendering have finite size and finite resolution. A drawing plane is described as having infinitely fine spatial, color, and opacity resolution, and as allowing coordinates of unbounded positive or negative magnitude. A viewport into a drawing plane, on the other hand, views only a finite region (usually rectangular) of the drawing plane. Furthermore, a viewport has limited spatial resolution and can only produce a limited number of colors. These limitations are imposed by the display hardware on which the viewport is displayed. A viewport also has limited opacity resolution, determined by the finite arithmetic used in the drawing engine. Coordinates are real numbers in implementation-defined units. Often these units equal the spatial resolution of a viewport, so that a line of thickness 1 is equivalent to the thinnest visible line. However, this equivalence is not required and should not be assumed by application programs. DUIM can be quite restrictive in the size and resolution of its viewports. For example, the spatial resolution might be only a few dozen points per inch, the maximum size might be only a few hundred points on a side, and there could be as few as two displayable colors (usually black and white). Fully transparent and fully opaque opacity levels are supported, but a DUIM implementation might support only a few opacity levels in between (or possibly even none). A DUIM implementation might implement color blending and unsaturated colors by stippling, although it is preferred, when possible, for a viewport to display a uniform color as a uniform color rather than as a perceptible stipple. However, there are no such limitations when DUIM records the output to a sheet, since DUIM just remembers the drawing operations that were performed, not the results of rendering. The application programmer uses the DUIM graphic drawing model as an interface to describe the intended visual appearance. DUIM then approximates that ideal appearance in a viewport, within its limitations of spatial resolution, color resolution, number of simultaneously displayable colors, and drawing speed. Naturally, doing this usually requires trade-offs, for example between speed and accuracy, and these trade-offs depend on the hardware and software environment and the user concerns in any given situation. For example: - If the device only supports a limited number of colors, the desired color may be approximated using techniques such as dithering or stippling. - If the device cannot draw curves precisely, they may be approximated, with or without anti-aliasing. - If the device has limited opacity resolution, color blending may be approximate. A viewport might display colors that do not appear in the drawing plane, both because of color and opacity approximation and because of anti-aliasing at the edges of drawn shapes. Drawing computations are always carried out "in color", even if the viewport is only capable of displaying black and white. In other words, the DUIM drawing model is always the fully general model, even if an implementation's color resolution is limited enough that full use of the model is not possible. Of course an application that fundamentally depends on color will not work well on a viewport that cannot display color. Other applications will degrade gracefully. Whether the implementation uses raster graphics or some other display technique is invisible at this interface. DUIM does not specify the existence of pixels nor the exact details of scan conversion, which will vary from one drawing engine to the next. Rendering conventions for geometric shapes ========================================== This section describes the conventions for how DUIM renders a shape on a display device. When DUIM draws a geometric shape on a display device, the idealized geometric shape must somehow be rendered on that device. This involves mapping points on the idealized geometric shape onto points on the display device. Idealized geometric shapes are made up of a set of mathematical points which have no size. The rendering of these shapes on the display device is usually composed of pixels, which are roughly square, and are specified in "device coordinates". Device coordinates are calculated by transforming the user-supplied coordinates by each of the following: - The user-supplied transformation - The medium transformation - The transformation that maps from the sheet to the display device .. note:: If the last of these is a pure translation that translates by an integer multiple of device units, then it has no effect on the rendering other than placement of the figure drawn on the display device. Roughly speaking, a pixel is affected by drawing a shape only when it is inside that shape. Since pixels are little squares, and the abstract points in an idealized geometric shape have no size, most shapes will have many pixels that lie only partially inside the shape. It is important, therefore, to describe which pixels will be affected when rendering a shape, and which will not. On devices that support color or grayscale, the rendering engine uses anti-aliasing techniques to render pixels that lie only partially inside the shape. That is, the affected pixels are drawn a little lighter than pixels that are wholly within the shape, the precise shade depending on how much of it is inside the shape. The conventions used by DUIM are the same as the conventions used by X11: - A pixel is a addressed by its upper-left corner. - A pixel is considered to be inside a shape, and hence affected by the rendering of that shape, if the center of the pixel is inside the shape. If the center of the pixel lies exactly on the boundary of the shape, it is considered to be inside the shape if the inside of the shape is immediately to the right of the center point of the pixel (that is, an increasing x direction on the display device). If the center of the pixel lies exactly on a horizontal boundary, it is considered to be inside the shape if the inside of the shape is immediately below the center point of the pixel (that is, an increasing y direction on the display device). This situation is illustrated in :ref:`how-pixels-are-defined-inside-outside`. - An unfilled idealized geometric shape is drawn by calculating an artificial area for the shape, and then deciding which pixels are inside or outside that area, using the rules described above. The artificial area is calculated by taking the filled shape consisting of those points that are within half the line thickness from the outline curve (using a normal distance function, that is, the length of the line drawn at right angles to the tangent to the outline curve at the nearest point). To visualize this, imagine a filled shape the same size as the unfilled shape, and overlay on this filled shape an identical, but slightly smaller, unfilled shape. .. _how-pixels-are-defined-inside-outside: .. figure:: images/graphics-3.png :align: center How pixels are defined to be "inside" and "outside" shapes It is important to note that these rules imply that the decision point used for insideness checking is offset from the point used for addressing the pixel by half a device unit in both the x and y directions. It is worth considering the motivations for these conventions. When two shapes share a common edge, it is important that only one of the shapes own any pixel. The two triangles in :ref:`two-triangles` illustrate this. The pixels along the diagonal belong to the lower figure. When the decision point of the pixel (its center) lies to one side of the line or the other, there is no issue. When the boundary passes through a decision point, which side the inside of the figure is on is used to decide. .. _two-triangles: .. figure:: images/graphics-4.png :align: center Two triangles The reason for choosing the decision point half a pixel offset from the address point is to reduce the number of common figures (such as rectilinear lines and rectangles with integral coordinates) that invoke the boundary condition rule. This usually leads to more symmetrical results. For instance, shows a circle drawn when the decision point is the same as the address point. The four lighter points are indeterminate: it is not clear whether they are inside or outside the shape. Since each boundary case is determined according to which side has the figure on it, and since the same rule must be applied uniformly for all figures, there is no choice but to pick only two of the four points, leading to an undesirable lopsided figure. .. figure:: images/graphics-5.png :align: center Choosing any two of the shaded pixels causes asymmetry If all four boundary points had been chosen instead, the result would be a symmetrical figure. However, since this figure is symmetrical about a whole pixel, it is one pixel wider than it ought to be. The problem with this can be seen clearly in :ref:`two-forms-of-circle-inscribed-in-a-square`, in which a circle is drawn over a square. In the left-hand figure, the decision point is at the center of the pixel, but in the right-hand figure, it is not. .. _two-forms-of-circle-inscribed-in-a-square: .. figure:: images/graphics-6.png :align: center Two forms of a circle inscribed in a square It is for this reason that the decision point is at the center of the pixel. This draws circles that look like the one in :ref:`an-aesthetically-pleasing-circle` .. _an-aesthetically-pleasing-circle: .. figure:: images/graphics-7.png :align: center An aesthetically pleasing circle A consequence of these rendering conventions is that, when the start or end coordinate (minus half the line thickness, if the shape is a path) is not an integer, then rendering is not symmetric under reflection transformations. Thus, to correctly and portably draw an outline of thickness 1 around a (rectilinear) rectangular area with integral coordinates, the outline path must have half-integral coordinates. Drawing rectilinear areas whose boundaries are not on pixel boundaries cannot be guaranteed to be portable. In other words, the "control points" for a rectangular area are at the corners, while the control points for a rectilinear path are in the center of the path, not at the corners. Therefore, in order for a path and an area to abut seamlessly, the coordinates of the path must be offset from the coordinates of the area by half the thickness of the path. Permissible alternatives during rendering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some platforms may distinguish between lines of the minimum thinness from lines that are thicker than that. The two rasterizations depicted in :ref:`two-examples-of-lines-of-thickness-1` are both perfectly reasonable rasterizations of tilted lines that are a single device unit wide. The right-hand line is drawn as a tilted rectangle, the left as the "thinnest visible" line. .. _two-examples-of-lines-of-thickness-1: .. figure:: images/graphics-8.png :align: center Two examples of lines of thickness 1 For thick lines, a platform may choose to draw the exact tilted fractional rectangle, or the coordinates of that rectangle might be rounded so that it is distorted into another polygonal shape. The latter case may be prove to be faster on some platforms. The two rasterizations depicted in :ref:`two-examples-of-lines-of-thickness-2` are both reasonable. .. _two-examples-of-lines-of-thickness-2: .. figure:: images/graphics-9.png :align: center Two examples of lines of thickness 2 The decision about which side of the shape to take when a boundary line passes through the decision point is made arbitrarily, although this is compatible with the X11 definition. This is not necessarily the most convenient decision. The main problem with this is illustrated by the case of a horizontal line (see :ref:`two-possible-definitions-of-horizontal-lines`). The DUIM definition draws the rectangular slice above the coordinates, since those pixels are the ones whose centers have the figure immediately above them. This definition makes it simpler to draw rectilinear borders around rectilinear areas. .. _two-possible-definitions-of-horizontal-lines: .. figure:: images/graphics-10.png :align: center Two possible definitions of horizontal lines. Left figure is X11 definition Drawing using path related functions ==================================== A number of functions are provided that let you perform a number of connected drawing operations by encapsulating all the operations as a single path, rendering the graphic itself only when the whole path has been defined explicitly. You can use these functions by following the general procedure below: 1. Create a new path using :gf:`start-path`. 2. Define the appearance of the path using any combination of :gf:`line-to`, :gf:`move-to`, :gf:`curve-to`, and :gf:`arc-to`. 3. Optionally, use :gf:`close-path` to create a closed path from the segments defined in step 2 above. 4. End the current path definition using :gf:`end-path` (if you have not already used :gf:`close-path`). 5. Render the outline of the path to the drawable object using :gf:`stroke-path`. 6. If the path you created is closed, flood fill the path using :gf:`fill-path`. Each of these functions is described in a little more in the following sections. For full details about each individual function, refer to its full reference entry in `DUIM-Graphics Module`_. Functions for controlling the definition of a path ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following generic functions provide overall control of the definition of a path. In each case, the argument *drawable* is either a sheet or a medium. .. generic-function:: start-path :signature: start-path *drawable* => () :description: Starts a new path on *drawable*. The path can be created with any number of calls to :gf:`line-to`, :gf:`curve-to`, :gf:`arc-to`, and :gf:`move-to`. Its appearance can also be manipulated using :gf:`fill-path` and :gf:`stroke-path`. After creating the path, use either :gf:`close-path` or :gf:`end-path` to finish the path, or :gf:`abort-path` to abandon it altogether. .. generic-function:: end-path :signature: end-path *drawable* => () :description: Ends the definition of the current path in *drawable*. Once the definition has been ended, the path can be rendered to the drawable using :gf:`fill-path` or :gf:`stroke-path`. The function :gf:`close-path` can also be used to end the definition of a path. .. generic-function:: close-path :signature: close-path *drawable* => () :description: Closes the current path on the *drawable*: that is, creates a closed figure from the elements already defined. For example, if you create a path that has four connected lines (using :gf:`line-to`), you can use :gf:`close-path` to join the first and last lines in the path to create a closed, five-sided figure. .. generic-function:: abort-path :signature: abort-path *drawable* => () :description: Aborts the current path on *drawable*. Any operations that have been performed since the last call to *start-path* are discarded. .. generic-function:: fill-path :signature: fill-path *drawable* => () :description: Uses the current brush to fill the current path on *drawable*. Only closed paths can be filled. If the path has not already been closed using :gf:`close-path`, it is closed automatically. .. generic-function:: stroke-path :signature: stroke-path *drawable* => () :description: Uses the current pen to draw the current path on *drawable*. Note that the path must not have been previously filled. This function does not close the path: you must use :gf:`close-path` if you wish to do this. Functions for describing the appearance of a path ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The following generic functions actually perform drawing operations within a path. Again, in each case, the argument *drawable* is either a sheet or a medium. All other arguments are instances of :drm:``. .. generic-function:: line-to :signature: line-to *drawable x y* => () :description: Draws a line from the current position in the path to (*x*, *y*). .. generic-function:: curve-to :signature: curve-to *drawable x1 y1 x2 y2 x3 y3* => () :description: Draws a curve in the current path on *drawable* starting from the current position, and passing through (*x1*, *y1*), (*x2*, *y2*), and (*x3*, *y3*). .. generic-function:: move-to :signature: move-to *drawable x y* => () :description: Move the position in the current path on *drawable* to (*x*, *y*). The function :gf:`move-to` can be used several times within the definition of a path, allowing for the definition of several visually separate sections within the same path. .. generic-function:: arc-to :signature: arc-to *drawable center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy* #key *start-angle end-angle* => () :description: Draws an arc in the current path on *drawable*. .. figure:: images/graphics-11.png :align: center Description of the arguments for arc-to The center of the arc is defined by (*center-x*, *center-y*), the points furthest away from the center for each radius are calculated by adding *radius-1-dx* and *radius-1-dy* to *center-x* and *center-y* respectively (to calculate the outermost points for the first radius), and adding *radius-2-dx* and *radius-2-dy* to *center-x* and *center-y* respectively (to calculate the outermost points for the second radius). The arguments *start-angle* and *end-angle* define the extent of the arc that is drawn. For each function listed above, an equivalent function is also provided that passes composite objects in its arguments, rather than separate coordinates. These functions take the same name as the functions above, but with a ``*`` character appended. (Thus, :gf:`line-to*` performs the same operation as :gf:`line-to`, but passes composite objects in its arguments). You should be aware that using these composite object functions may lead to a loss of performance. For more details, see the full reference entries for each function. DUIM-Graphics Module ==================== This section contains a complete reference of all the interfaces that are exported from the *duim-graphics* module. .. generic-function:: abort-path Aborts the current path on the specified drawable object. :signature: abort-path *drawable* => () :parameter drawable: An instance of type ``type-union(, )``. :description: Aborts the current path on *drawable*. Any operations that have been performed since the last call to :gf:`start-path` are discarded. :seealso: - :gf:`close-path` - :gf:`end-path` - :gf:`start-path` .. generic-function:: arc-to Draws an arc in the current path on the specified drawable. :signature: arc-to *drawable center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy* #key *start-angle end-angle* => () :signature: arc-to\* *drawable center radius-1-dx radius-1-dy radius-2-dx radius-2-dy* #key *start-angle end-angle* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter radius-1-dx: An instance of type :drm:``. :parameter radius-1-dy: An instance of type :drm:``. :parameter radius-2-dx: An instance of type :drm:``. :parameter radius-2-dy: An instance of type :drm:``. :parameter start-angle: An instance of type ``false-or()``. :parameter end-angle: An instance of type ``false-or()``. The following arguments are specific to ``arc-to``. :parameter center-x: An instance of type :drm:``. :parameter center-y: An instance of type :drm:``. The following argument is specific to ``arc-to*``. :parameter center: An instance of type :class:``. :description: Draws an arc in the current path on the specified drawable. This function is used, in combination with :gf:`line-to`, :gf:`curve-to`, and :gf:`move-to`, to define a path. The function :gf:`start-path` should be used to start the definition of the path, and :gf:`end-path` can be used to finish the definition. The center of the arc is defined by (*center-x*, *center-y*), and the extreme points of the virtual ellipse around the arc (that is, the points furthest away from the center for each radius) are calculated by adding the radius vectors *radius-1-dx* and *radius-1-dy* to *center-x* and *center-y* respectively (to calculate the outermost points for the first radius), and adding the radius vectors *radius-2-dx* and *radius-2-dy* to *center-x* and *center-y* respectively (to calculate the outermost points for the second radius). Please note that :gf:`arc-to` does not currently support arcs whose orientation is not axis-aligned ellipses. For all practical purposes, this means that *radius-1-dy* and *radius-2-dx* must always be 0. .. figure:: images/graphics-12.png :align: center The arguments *start-angle* and *end-angle* define the extent of the arc that is drawn. The function ``arc-to*`` is identical to ``arc-to``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`curve-to` - :gf:`draw-bezier-curve` - :gf:`draw-line` - :gf:`line-to` - :gf:`move-to` .. generic-function:: close-path Closes the current path on the specified drawable. :signature: close-path *drawable* => () :parameter drawable: An instance of type ``type-union(, )``. :description: Closes the current path on the *drawable*: that is, creates a closed figure from the elements already defined. For example, if you create a path that has four connected lines (using :gf:`line-to`), you can use :gf:`close-path` to join the first and last lines in the path to create a closed, five-sided figure. Only closed paths can be filled, although :gf:`fill-path` will close a non-closed path automatically. :seealso: - :gf:`abort-path` - :gf:`end-path` - :gf:`start-path` .. generic-function:: copy-area Copies a rectangle of pixels from a specified medium to the same medium. :signature: copy-area *medium from-x from-y width height to-x to-y* #key *function* => () :parameter medium: An instance of type :class:``. :parameter from-x: An instance of type :class:``. :parameter from-y: An instance of type :class:``. :parameter width: An instance of type :drm:``. :parameter height: An instance of type :drm:``. :parameter to-x: An instance of type :class:``. :parameter to-y: An instance of type :class:``. :parameter function: An instance of type :drm:``. Default value: :const:`$boole-1`. :description: Copies the pixels from the *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. If *medium* is a medium or a stream, then the x and y values are transformed by the user transformation. The copying must be done by *medium-copy-copy*. :seealso: - :gf:`copy-from-pixmap` - :gf:`copy-to-pixmap` .. generic-function:: copy-from-pixmap Copies a rectangle of pixels from the specified pixmap to the specified medium. :signature: copy-from-pixmap *pixmap pixmap-x pixmap-y width height medium medium-x medium-y* #key *function* => () :parameter pixmap: An instance of type :class:``. :parameter pixmap-x: An instance of type :class:``. :parameter pixmap-y: An instance of type :class:``. :parameter width: An instance of type :drm:``. :parameter height: An instance of type :drm:``. :parameter medium: An instance of type :class:``. :parameter medium-x: An instance of type :class:``. :parameter medium-y: An instance of type :class:``. :parameter function: An instance of type :drm:``. Default value: :const:`$boole-1`. :description: Copies a rectangle of pixels from *pixmap* starting at the position specified by (*pixmap-x*, *pixmap-y*) into *medium* at the position (*medium-x*, *medium-y*). A rectangle whose width and height is specified by *width* and *height* is copied. If *medium* is a medium or a stream, then *medium-x* and *medium-y* are transformed by the user transformation. The copying must be done by *medium-copy-copy*. :seealso: - :gf:`copy-area` - :gf:`copy-to-pixmap` - :class:`` .. generic-function:: copy-to-pixmap Copies a rectangle of pixels from the specified medium to the specified pixmap. :signature: copy-to-pixmap *medium medium-x medium-y width height pixmap pixmap-x pixmap-y* #key *function* => () :parameter medium: An instance of type :class:``. :parameter medium-x: An instance of type :class:``. :parameter medium-y: An instance of type :class:``. :parameter width: An instance of type :drm:``. :parameter height: An instance of type :drm:``. :parameter pixmap: An instance of type :class:``. :parameter pixmap-x: An instance of type :class:``. :parameter pixmap-y: An instance of type :class:``. :parameter function: An instance of type :drm:``. Default value: :const:`$boole-1`. :description: Copies the pixels from the *medium* starting at the position specified by (*medium-x*, *medium-y*) into *pixmap* at the position specified by (*pixmap-x*, *pixmap-y*). A rectangle whose width and height is specified by *width* and *height* is copied. If *medium* is a medium or a stream, then *medium-x* and *medium-y* are transformed by the user transformation. The copying must be done by *medium-copy-copy*. If *pixmap* is not supplied, a new pixmap will be allocated. :seealso: - :gf:`copy-area` - :gf:`copy-from-pixmap` .. generic-function:: curve-to Draws a curve through three specified points in the current path on the specified drawable. :signature: curve-to *drawable x1 y1 x2 y2 x3 y3* => () :signature: curve-to\* *drawable point1 point2 point3* => () :parameter drawable: An instance of type ``type-union(, )``. The following arguments are specific to ``curve-to``. :parameter x1: An instance of type :drm:``. :parameter y1: An instance of type :drm:``. :parameter x2: An instance of type :drm:``. :parameter y2: An instance of type :drm:``. :parameter x3: An instance of type :drm:``. :parameter y3: An instance of type :drm:``. The following arguments are specific to ``curve-to*``. :parameter point1: An instance of type :class:``. :parameter point2: An instance of type :class:``. :parameter point3: An instance of type :class:``. :description: Draws a curve in the current path on *drawable* starting from the current position, and passing through (*x1*, *y1*), (*x2*, *y2*), and (*x3*, *y3*). This function is used, in combination with :gf:line-to`, :gf:`move-to`, and :gf:`arc-to`, to define a path. The function :gf:`start-path` should be used to start the definition of the path, and :gf:`end-path` can be used to finish the definition. The function ``curve-to*`` is identical to ``curve-to``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`arc-to` - :gf:`draw-bezier-curve` - :gf:`draw-line` - :gf:`line-to` - :gf:`move-to` .. generic-function:: destroy-pixmap Destroys the specified pixmap. :signature: destroy-pixmap *pixmap* => () :parameter pixmap: An instance of type :class:``. :description: Destroys *pixmap*. :seealso: - :gf:`draw-pixmap` .. generic-function:: do-with-output-to-pixmap Returns a pixmap for the specified medium. :signature: do-with-output-to-pixmap *medium continuation* #key *width height clear?* => *pixmap* :parameter medium: An instance of type :class:``. :parameter continuation: An instance of type :drm:``. :parameter width: An instance of type :drm:``. :parameter height: An instance of type :drm:``. :parameter clear?: An instance of type :drm:``. Default value: ``#t``. :value pixmap: An instance of type :class:``. :description: Returns a pixmap for the specified medium. This function is called by :gf:`with-output-to-pixmap` and returns the pixmap that is operated on. If you are subclassing :class:`, you must define new methods on this function. The *width* and *height* are integers that give the width and height of the pixmap. If they are unsupplied, the result pixmap will be large enough to contain all of the output done by the body of code executed by :macro:`with-output-to-pixmap`. :seealso: - :gf:`with-output-to-pixmap` .. generic-function:: draw-arrow Draws an arrow between two specified points. :signature: draw-arrow *drawable x1 y1 x2 y2* #key *from-head? to-head? head-length head-width* => () :signature: draw-arrow\* *drawable point1 point2* #key *from-head? to-head? head-length head-width* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter from-head?: An instance of type :drm:``. Default value: ``#f``. :parameter to-head?: An instance of type :drm:``. Default value: ``#t``. :parameter head-length: An instance of type :drm:``. Default value: *10*. :parameter head-width: An instance of type :drm:``. Default value: *5*. The following arguments are specific to ``draw-arrow``. :parameter x1: An instance of type :drm:``. :parameter y1: An instance of type :drm:``. :parameter x2: An instance of type :drm:``. :parameter y2: An instance of type :drm:``. The following arguments are specific to ``draw-arrow*``. :parameter point1: An instance of type :class:``. :parameter point2: An instance of type :class:``. :description: Draws an arrow on *drawable* between two (*x1*, *y1*) and (*x2*, *y2* ), using the current pen. Dashed lines start dashing from the first point. If *from-head?* is ``#t``, then the arrow-head points from (*x1*, *y1*) to (*x2*, *y2*). If *to-head?* is ``#t``, then the arrow-head points from (*x2*, *y2*) to (*x1*, *y1*). If both *from-head?* and *to-head?* are ``#t``, then a double-headed arrow is drawn. The arguments *head-length* and *head-width* specify the length and width of the arrow-head respectively, in pixels. .. figure:: images/graphics-13.png :align: center The function ``draw-arrow*`` is identical to ``draw-arrow``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-line` .. generic-function:: draw-bezier-curve Draws a bezier curve through the specified set of points. :signature: draw-bezier-curve *sheet coord-seq* #key *filled?* => () :signature: draw-bezier-curve\* *drawable points* #key *filled?* => () :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following arguments are specific to ``draw-bezier-curve``. :parameter sheet: An instance of type :class:``. :parameter coord-seq: An instance of type ``limited(, of: )``. The following arguments are specific to ``draw-bezier-curve*``. :parameter drawable: An instance of type ``type-union(, )``. :parameter points: An instance of type ``limited(, of: )``. :description: Draws a bezier curve on *sheet* or *drawable* (depending on the function you use) through the sequence of coordinates given by *coord-seq*, using the current pen. Dashed lines start dashing from the first point. If *filled?* is ``#t`` then the bezier-curve will be filled, using the current brush. The function ``draw-bezier-curve*`` is identical to ``draw-bezier-curve``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`curve-to` - :gf:`draw-line` .. generic-function:: draw-circle Draws a circle with the specified center and radius. :signature: draw-circle *drawable center-x center-y radius* #key *start-angle end-angle filled?* => () :signature: draw-circle\* *drawable center radius #key start-angle end-angle filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter radius: An instance of type :drm:``. :parameter start-angle: An instance of type ``false-or()``. :parameter end-angle: An instance of type ``false-or()``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following arguments are specific to ``draw-circle``. :parameter center-x: An instance of type :drm:``. :parameter center-y: An instance of type :drm:``. The following argument is specific to ``draw-circle*``. :parameter center: An instance of type :class:``. :description: Draws a circle on *drawable* with center (*center-x*, *center-y*) and a radius of *radius* pixels, using the current pen. The *start-angle* and *end-angle* arguments let you draw a sector of a circle rather than a whole circle. If *filled?* is ``#t``, then the circle will be filled, using the current brush. The function ``draw-circle*`` is identical to ``draw-circle``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-ellipse` - :gf:`draw-oval` .. generic-function:: draw-ellipse Draws an ellipse with the specified center and radius vectors. :signature: draw-ellipse *drawable center-x center-y radius-1-dx radius-1-dy radius-2-dx radius-2-dy* #key *start-angle end-angle filled?* => () :signature: draw-ellipse\* *drawable center radius-1-dx radius-1-dy radius-2-dx radius-2-dy* #key *start-angle end-angle filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter radius-1-dx: An instance of type :drm:``. :parameter radius-1-dy: An instance of type :drm:``. :parameter radius-2-dx: An instance of type :drm:``. :parameter radius-2-dy: An instance of type :drm:``. :parameter start-angle: An instance of type ``false-or()``. :parameter end-angle: An instance of type ``false-or()``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following arguments are specific to ``draw-ellipse``. :parameter center-x: An instance of type :drm:``. :parameter center-y: An instance of type :drm:``. The following argument is specific to ``draw-ellipse*``. :parameter center: An instance of type :class:``. :description: Draws an ellipse on *drawable* with the specified center and extreme points, using the current pen. The center of the ellipse is defined by (*center-x*, *center-y*), and the extreme points of the ellipse (that is, the points furthest away from the center for each radius) are calculated by adding the radius vectors *radius-1-dx* and *radius-1-dy* to *center-x* and *center-y* respectively (to calculate the outermost points for the first radius), and adding the radius vectors *radius-2-dx* and *radius-2-dy* to *center-x* and *center-y* respectively (to calculate the outermost points for the second radius). Please note that *draw-ellipse* does not currently support non-axis-aligned ellipses. For all practical purposes, this means that *radius-1-dy* and *radius-2-dx* must always be 0. .. figure:: images/graphics-14.png :align: center The arguments *start-angle* and *end-angle* let you draw just a section of the ellipse, rather than the whole ellipse. If *filled?* is ``#t`` then the ellipse will be filled, using the current brush. The function ``draw-ellipse*`` is identical to ``draw-ellipse``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-circle` - :gf:`draw-oval` .. generic-function:: draw-image Draws the specified image at the specified position. :signature: draw-image *drawable image x y* => () :signature: draw-image\* *drawable image point* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter image: An instance of type :class:``. The following arguments are specific to ``draw-image``. :parameter x: An instance of type :drm:``. :parameter y: An instance of type :drm:``. The following argument is specific to ``draw-image*``. :parameter point: An instance of type :class:``. :description: Draws *image* on *drawable* at (*x*, *y*). The function ``draw-image*`` is identical to ``draw-image``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-pixmap` - :gf:`draw-text` .. generic-function:: draw-line Draws a line between the specified points. :signature: draw-line *drawable x1 y1 x2 y2* => () :signature: draw-line\* *drawable point1 point2* => () :parameter drawable: An instance of type ``type-union(, )``. The following arguments are specific to ``draw-line``. :parameter x1: An instance of type :drm:``. :parameter y1: An instance of type :drm:``. :parameter x2: An instance of type :drm:``. :parameter y2: An instance of type :drm:``. The following arguments are specific to ``draw-line*``. :parameter point1: An instance of type :class:``. :parameter point2: An instance of type :class:``. :description: Draws a line on *drawable* between (*x1*, *y1*) and (*x2*, *y2*), using the current pen. Dashed lines start dashing from the first point. The function ``draw-line*`` is identical to ``draw-line``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`curve-to` - :gf:`draw-arrow` - :gf:`draw-bezier-curve` - :gf:`draw-lines` - :gf:`draw-point` - :gf:`line-to` .. generic-function:: draw-lines Draws a series of lines between the specified sequence of points. :signature: draw-lines *drawable coord-seq* => () :signature: draw-lines\* *drawable points* => () :parameter drawable: An instance of type ``type-union(, )``. The following argument is specific to ``draw-lines``. :parameter coord-seq: An instance of type ``limited(, of: )``. The following argument is specific to ``draw-lines*``. :parameter points: An instance of type ``limited(, of: )``. :description: Draws a series of lines on *drawable* between the specified sequence of points, using the current pen. Dashed lines start dashing from the first point of each line. The function ``draw-lines*`` is identical to ``draw-line``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. Example .. code-block:: dylan draw-lines(medium, vector(100, 150, 200, 250, 300, 350, 400, 450)); :seealso: - :gf:`draw-line` - :gf:`draw-points` - :gf:`draw-rectangles` .. generic-function:: draw-oval Draws an oval with the specified center and radii. :signature: draw-oval *drawable center-x center-y x-radius y-radius* #key *filled?* => () :signature: draw-oval\* *drawable center x-radius y-radius* #key *filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter x-radius: An instance of type :drm:``. :parameter y-radius: An instance of type :drm:``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following arguments are specific to ``draw-oval``. :parameter center-x: An instance of type :drm:``. :parameter center-y: An instance of type :drm:``. The following argument is specific to ``draw-oval*``. :parameter center: An instance of type :class:``. :description: Draws an oval on *drawable* with center (*center-x*, *center-y*) and radii defined by *x-radius* and *y-radius*, using the current pen. Ovals are similar to ellipses, except that they have straight edges. .. figure:: images/graphics-15.png :align: center If *filled?* is ``#t`` then the oval will be filled, using the current brush. The function ``draw-oval*`` is identical to ``draw-oval``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-circle` - :gf:`draw-ellipse` .. generic-function:: draw-pixmap Draws the contents of the specified pixmap at the specified point. :signature: draw-pixmap *drawable pixmap x y* #key *function* => () :signature: draw-pixmap\* *drawable pixmap point* #key *function* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter pixmap: An instance of type :class:``. :parameter function: An instance of type :drm:``. Default value: :const:`$boole-1`. The following arguments are specific to ``draw-pixmap``. :parameter x: An instance of type :drm:``. :parameter y: An instance of type :drm:``. The following argument is specific to ``draw-pixmap*``. :parameter point: An instance of type :class:``. :description: Draws the contents of *pixmap* on *drawable* at (*x*, *y*). The function ``draw-pixmap*`` is identical to ``draw-pixmap``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`destroy-pixmap` - :gf:`draw-image` - :gf:`draw-text` - :gf:`make-pixmap` .. generic-function:: draw-point Draws a single point at the specified position. :signature: draw-point *drawable x y* => () :signature: draw-point\* *drawable point* => () :parameter drawable: An instance of type ``type-union(, )``. The following arguments are specific to ``draw-point``. :parameter x: The x coordinate. :parameter y: The y coordinate. The following argument is specific to ``draw-point*``. :parameter point: An instance of type :class:``. :description: Draws a single point on *drawable* at (*x*, *y*). The function ``draw-point*`` is identical to ``draw-point``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-line` - :gf:`draw-points` .. generic-function:: draw-points Draws a sequence of points at the specified positions. :signature: draw-points *drawable coord-seq* => () :signature: draw-points\* *drawable points* => () :parameter drawable: An instance of type ``type-union(, )``. The following argument is specific to ``draw-points``. :parameter coord-seq: An instance of type ``limited(, of: )``. The following argument is specific to ``draw-points*``. :parameter points: An instance of type ``limited(, of: )``. :description: Draws a sequence of points on *drawable* at the specified positions. The function ``draw-points*`` is identical to ``draw-points``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-lines` - :gf:`draw-point` - :gf:`draw-rectangles` .. generic-function:: draw-polygon Draws a polygon joining the specified points. :signature: draw-polygon *drawable coord-seq* #key *closed? filled?* => () :signature: draw-polygon\* *drawable points* #key *closed? filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter closed?: An instance of type :drm:``. Default value: ``#t``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following argument is specific to ``draw-polygon``. :parameter coord-seq: An instance of type ``limited(, of: )``. The following argument is specific to ``draw-polygon*``. :parameter points: An instance of type ``limited(, of: )``. :description: Draws a polygon on *drawable* joining the specified points, using the current pen. Dashed lines start dashing at the starting point of the first segment. If *closed?* is ``#t``, then the polygon is closed, that is, a line is drawn from the last point in the sequence back to the first. If *filled?* is ``#t`` then the polygon will be filled, using the current brush. The function ``draw-polygon*`` is identical to ``draw-polygon``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-rectangle` - :gf:`draw-regular-polygon` - :gf:`draw-triangle` .. generic-function:: draw-rectangle Draws a rectangle at the specified position. :signature: draw-rectangle *drawable x1 y1 x2 y2* #key *filled?* => () :signature: draw-rectangle\* *drawable point1 point2* #key *filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following arguments are specific to ``draw-rectangle``. :parameter x1: An instance of type :drm:``. :parameter y1: An instance of type :drm:``. :parameter x2: An instance of type :drm:``. :parameter y2: An instance of type :drm:``. The following arguments are specific to ``draw-rectangle*``. :parameter point1: An instance of type :class:``. :parameter point2: An instance of type :class:``. :description: Draws a rectangle on *drawable* with left and right corners at (*x1*, *y1*) and (*x2*, *y2*), using the current pen. Dashed lines start dashing at the starting point of the first segment. Note that the specified points could represent either top or bottom corners: only one rectangle is possible between and pair of points. .. figure:: images/graphics-16.png :align: center If *filled?* is ``#t`` then the rectangle will be filled, using the current brush. The function ``draw-rectangle*`` is identical to ``draw-rectangle``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-polygon` - :gf:`draw-rectangles` - :gf:`draw-regular-polygon` - :gf:`draw-triangle` .. generic-function:: draw-rectangles Draws a sequence of rectangles at the specified positions. :signature: draw-rectangles *drawable coord-seq* #key *filled?* => () :signature: draw-rectangles\* *drawable points* #key *filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following argument is specific to ``draw-rectangles``. :parameter coord-seq: An instance of type ``limited(, of: )``. The following argument is specific to ``draw-rectangles*``. :parameter points: An instance of type ``limited(, of: )``. :description: Draws a sequence of rectangles on *drawable* with left and right corners at the specified positions, using the current pen. Dashed lines start dashing at the starting point of the first segment of each rectangle. If *filled?* is ``#t`` then the rectangles will be filled, using the current brush. The function ``draw-rectangles*`` is identical to ``draw-rectangles``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-lines` - :gf:`draw-points` - :gf:`draw-rectangle` .. generic-function:: draw-regular-polygon Draws a regular polygon that touches the specified points, and has the specified number of sides. :signature: draw-regular-polygon *drawable x1 y1 x2 y2 nsides* #key *handedness closed? filled?* => () :signature: draw-regular-polygon\* *drawable point1 point2 nsides* #key *handedness closed? filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter nsides: An instance of type :drm:``. :parameter handedness: Default value: ``#"left"``. :parameter closed?: An instance of type :drm:``. Default value: ``#t``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following arguments are specific to ``draw-regular-polygon``. :parameter x1: An instance of type :drm:``. :parameter y1: An instance of type :drm:``. :parameter x2: An instance of type :drm:``. :parameter y2: An instance of type :drm:``. The following arguments are specific to ``draw-regular-polygon*``. :parameter point1: An instance of type :class:``. :parameter point2: An instance of type :class:``. :description: Draws a regular polygon on *drawable*, using the current pen, that touches the specified points, and has the specified number of sides. Dashed lines start dashing at the starting point of the first segment. .. figure:: images/graphics-17.png :align: center If *filled?* is ``#t`` then the polygon will be filled, using the current brush. The function ``draw-regular-polygon*`` is identical to ``draw-regular-polygon``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-polygon` - :gf:`draw-rectangle` - :gf:`draw-triangle` .. generic-function:: draw-text Draws text at the specified point, in a specified direction. :signature: draw-text *drawable text x y* #key *start end align-x align-y towards-point transform-glyphs?* => () :signature: draw-text\* *drawable text point* #key *start end align-x align-y towards-point transform-glyphs?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter text: An instance of type ``type-union(, )``. :parameter start: An instance of type :drm:``. Default value: 0. :parameter end: An instance of type :drm:``. Default value: ``size(text)``. :parameter align-x: An instance of type ``one-of(#"left", #"right", #"center")``. Default value: ``#"left"``. :parameter align-y: An instance of type ``one-of(#"top", #"bottom", #"baseline")``. Default value: ``#"baseline"``. :parameter transform-glyphs?: An instance of type :drm:``. Default value: ``#f``. :parameter do-tabs?: An instance of type :drm:``. Default value: ``#f`` The following arguments are specific to ``draw-text``. :parameter towards-x: An instance of type :drm:``. :parameter towards-y: An instance of type :drm:``. :parameter x: An instance of type :drm:``. :parameter y: An instance of type :drm:``. The following arguments are specific to ``draw-text*``. :parameter towards-point: An instance of type :class:``. :parameter point: An instance of type :class:``. :description: Draws text from *text* on *drawable* at (*x*, *y*). Text is drawn in the direction of the point (*towards-x*, *towards-y*). .. figure:: images/graphics-18.png :align: center If *start* and *end* are specified, then only a section of text is drawn, starting at character *start*, and ending with character *end*. By default, the whole of *text* is drawn. The *align-x* and *align-y* arguments let you specify the left-right alignment and the top-bottom alignment (respectively) of the text that is written to *drawable*. For *align-x*, the whole of the distance between (*x*, *y*) and (*towards-x*, *towards-y*) is used to align *text*. Thus, if *align-x* is *#"right"*, the text will appear closer to (*towards-x*, *towards-y*) than to (*x*, *y*), assuming *text* occupies less space than the distance between these two points. The argument *transform-glyphs?* controls whether the text is reversed in cases when *towards-x* is less than *x*. If *transform-glyphs?* is ``#t``, then text is reversed in these cases, that is, the last character of *text* to be written is still closest to the point (*towards-x*, *towards-y*), and the text appears reversed. If *transform-glyphs?* is ``#f``, then the first character of *text* to be written is closest to the point (*towards-x*, *towards-y*), and the text does not appear reversed. If *do-tabs?* is ``#t``, then any tab characters in *text* are honored, and are drawn as tabs. If *do-tabs?* is ``#f``, then tab characters are replaced by spaces. The function ``draw-text*`` is identical to ``draw-text``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-image` - :gf:`draw-pixmap` .. generic-function:: draw-triangle Draws a triangle between the specified points. :signature: draw-triangle *drawable x1 y1 x2 y2 x3 y3* #key *filled?* => () :signature: draw-triangle\* *drawable p1 p2 p3* #key *filled?* => () :parameter drawable: An instance of type ``type-union(, )``. :parameter filled?: An instance of type :drm:``. Default value: ``#t``. The following arguments are specific to ``draw-triangle``. :parameter x1: An instance of type :drm:``. :parameter y1: An instance of type :drm:``. :parameter x2: An instance of type :drm:``. :parameter y2: An instance of type :drm:``. :parameter x3: An instance of type :drm:``. :parameter y3: An instance of type :drm:``. The following arguments are specific to ``draw-triangle*``. :parameter p1: An instance of type :class:``. :parameter p2: An instance of type :class:``. :parameter p3: An instance of type :class:``. :description: Draws a triangle on *drawable* between the specified points, using the current pen. Dashed lines start dashing at the starting point of the first segment. .. figure:: images/graphics-19.png :align: center If *filled?* is ``#t`` then the triangle will be filled, using the current brush. The function ``draw-triangle*`` is identical to ``draw-triangle``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`draw-polygon` - :gf:`draw-rectangle` - :gf:`draw-regular-polygon` .. generic-function:: end-path Ends the definition of the current path in the specified drawable object. :signature: end-path *drawable* => () :parameter drawable: An instance of type ``type-union(, )``. :description: Ends the definition of the current path in *drawable*. Once the definition has been ended, the path can be rendered to the drawable using :gf:`fill-path` or :gf:`stroke-path`. The function :gf:`close-path` can also be used to end the definition of a path. :seealso: - :gf:`abort-path` - :gf:`close-path` - :gf:`start-path` .. generic-function:: fill-path Uses the current brush to fill the current path on the specified drawable object. :signature: fill-path *drawable* => () :parameter drawable: An instance of type ``type-union(, )``. :description: Uses the current brush to fill the current path on *drawable*. If the path has not already been closed using :gf:`close-path`, it is closed automatically. :seealso: - :gf:`stroke-path` - :gf:`close-path` .. generic-function:: line-to Draws a line from the current position in the path to a new position. :signature: line-to *drawable x y* => () :signature: line-to\* *drawable point* => () :parameter drawable: An instance of type ``type-union(, )``. The following arguments are specific to ``line-to``. :parameter x: An instance of type :drm:``. :parameter y: An instance of type :drm:``. The following argument is specific to ``line-to*``. :parameter point: An instance of type :class:``. :description: Draws a line from the current position in the path to (*x*, *y*). This function is used, in combination with :gf:`move-to`, :gf:`curve-to`, and :gf:`arc-to`, to define a path. The function :gf:`start-path` should be used to start the definition of the path, and :gf:`end-path` can be used to finish the definition. The function ``line-to*`` is identical to ``line-to``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`arc-to` - :gf:`curve-to` - :gf:`draw-bezier-curve` - :gf:`draw-line` - :gf:`move-to` .. generic-function:: make-pixmap Creates a pixmap from the specified medium with a specified size. :signature: make-pixmap *medium width height* => *pixmap* :parameter medium: An instance of type :class:``. :parameter width: An instance of type :drm:``. :parameter height: An instance of type :drm:``. :value pixmap: An instance of type :class:``. :description: Creates a pixmap from *medium* with a specified size, in pixels, given by *width* and *height*. :seealso: - :gf:`draw-pixmap` - :class:`` - :gf:`pixmap?` .. generic-function:: move-to Move the position in the current path on the specified drawable. :signature: move-to *drawable x y* => () :signature: move-to\* *drawable point* => () :parameter drawable: An instance of type ``type-union(, )``. The following arguments are specific to ``move-to``. :parameter x: An instance of type :drm:``. :parameter y: An instance of type :drm:``. The following argument is specific to ``move-to*``. :parameter point: An instance of type :class:``. :description: Move the position in the current path on *drawable* to (*x*, *y*). This function is used, in combination with :gf:`line-to`, :gf:`curve-to`, and :gf:`arc-to`, to define a path. The function :gf:`start-path` should be used to start the definition of the path, and :gf:`end-path` can be used to finish the definition. The function ``move-to`` can be used several times within the definition of a path, allowing for the definition of several visually separate drawings within the same path. The function ``move-to*`` is identical to ``move-to``, except that it passes composite objects, rather than separate coordinates, in its arguments. You should be aware that using this function may lead to a loss of performance. :seealso: - :gf:`arc-to` - :gf:`curve-to` - :gf:`line-to` .. class:: :open: :abstract: :instantiable: The class of pixmap objects. :superclasses: :class:`` :description: The class of pixmap objects. A pixmap can be thought of as an "off-screen window", that is, a medium that can be used for graphical output, but is not visible on any display device. Pixmaps are provided to allow you 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 :class:`copy-from-pixmap` to draw the part as needed. :operations: The following operation is exported from the *DUIM-Graphics* module. - :gf:`copy-from-pixmap` - :gf:`destroy-pixmap` - :gf:`draw-image` - :gf:`draw-pixmap` - :gf:`pixmap?` The following operation is exported from the *DUIM-DCs* module. - :gf:`image-height` - :gf:`image-width` :seealso: - :gf:`draw-pixmap` - :gf:`make-pixmap` - :gf:`pixmap?` .. generic-function:: pixmap? Returns true if the specified object is a pixmap. :signature: pixmap? *object* => *pixmap?* :parameter object: An instance of type :drm:``. :value pixmap?: An instance of type :drm:``. :description: Returns true if *object* is a pixmap. :seealso: - :class:`` .. class:: :open: :abstract: :instantiable: The class of pixmap mediums. :superclasses: :class:`` :description: The class of pixmap mediums, that, is mediums capable of doing output to a pixmap. :operations: - :gf:`with-output-to-pixmap` :seealso: - :class:`` - :macro:`with-output-to-pixmap` .. generic-function:: restore-clipping-region .. generic-function:: start-path Starts a new path on the specified drawable object. :signature: start-path *drawable* => () :parameter drawable: An instance of type ``type-union(, )``. :description: Starts a new path on *drawable*. The path can be created with any number of calls to :gf:`line-to`, :gf:`curve-to` and :gf:`move-to`. Its appearance can also be manipulated using :gf:`fill-path` and :gf:`stroke-path`. After creating the path, use either :gf:`close-path` or :gf:`end-path` to finish the path, or :gf:`abort-path` to abandon it altogether. :seealso: - :gf:`abort-path` - :gf:`close-path` - :gf:`end-path` .. generic-function:: stroke-path Uses the current pen to draw the current path on the specified drawable object. :signature: stroke-path *drawable* => () :parameter drawable: An instance of type ``type-union(, )``. :description: Uses the current pen to draw the current path on *drawable*. Note that the path must not have been previously filled. This function does not close the path: you must use :gf:`close-path` if you wish to do this. :seealso: - :gf:`close-path` - :gf:`fill-path` .. macro:: with-output-to-pixmap Executes a body of code, returning the results to a pixmap. :macrocall: with-output-to-pixmap (*medium*, #rest *options*) *body* end => *pixmap* :parameter medium: An instance of type :class:``. :parameter options: An instance of type :drm:``. :parameter body: An instance of type :drm:``. :value pixmap: An instance of type :class:``. :description: Executes a body of code, returning the results to a pixmap.Binds *medium* to a pixmap medium, that is, a medium that does output to a pixmap, and then evaluates *body* in that context. All the output done to *medium* inside of *body* is drawn on the pixmap stream. The pixmap medium supports the medium output protocol, including all of the graphics functions. The returned value is a pixmap that can be drawn onto *medium* using :gf:`copy-from-pixmap`. :seealso: - :gf:`do-with-output-to-pixmap` - :class:``