fill-texture

Arguments: stream

Returns (or sets with setf) the fill-texture of a stream. The fill-texture is used by drawing functions that fill an area of a stream (as opposed to drawing lines), and may be used to fill with a pattern rather than with a solid color. The pattern will automatically be clipped at the edge of the area being filled, even if it is irregularly shaped. Functions that use the fill-texture of a stream include fill-box, fill-polygon, fill-circle, fill-circle-sector, fill-ellipse, fill-ellipse-sector, fill-rounded-box, and flood-fill.

The value should be any Common Graphics pixmap (see cg-pixmaps.htm) or one of the special symbols discussed further below. (For backward compatibility, the value may alternately be a texture, though it will draw correctly only if its width is a multiple of 32, even though the Windows 98 line will use only the first 8 by 8 pixels.)

The default value is the keyword :solid, which effectively means that the stream does not have a fill texture, and so the filling functions will simply draw in the current foreground-color of the stream.

If the value is a pixmap, then it behaves differently depending on whether it is monochrome. If the pixmap's bits-per-pixel property is 1 (indicating a monochrome pixmap), then the filling functions will draw the pixmap in the stream's current foreground-color wherever the pixmap has a "1" pixel, and in the stream's current background-color wherever it has a "0" pixel. Otherwise the pixmap will be drawn in its own colors, as with copy-to-stream.

As an alternative to specifying a custom pixmap, any of several special built-in fill-textures may be used by specifying a particular keyword symbol rather than a pixmap. These symbols include :12%foreground, :25%foreground, :37%foreground, :50%foreground, :62%foreground, :75%foreground, and :87%foreground. These fill-textures draw a pattern consisting of the indicated portion of pixels being drawn in the stream's current foreground-color, with the remaining pixels being drawn in the background-color. The foreground-color pixels are intermingled amongst the background-color pixels as evenly as possible, to "dither" the two colors. For example, if a stream's current background-color is yellow, its foreground-color is dark-red, and its fill-texture is the symbol :25%foreground, then filling functions will draw three-quarters of the pixels in the filled area as yellow, with one-quarter of the pixels sprinkled throughout as red.

A second set of special fill-texture symbols draw parallel straight lines in the foreground-color of a stream, with the remaining pixels in the background-color. These values are :horizontal, :vertical, :left-diagonal (drawing lines from upper-right to lower-left), and :right-diagonal (drawing lines from upper-left to lower-right).

Examples

;; This example uses the built-in :left-diagonal fill-texture.
(let* ((frame (make-window :filler :class 'bitmap-window
                           :interior (make-box 100 100 300 300)))
       (drawing-pane (frame-child frame)))
  (setf (foreground-color drawing-pane) red)
  (setf (background-color drawing-pane) yellow)
  (setf (fill-texture drawing-pane) :left-diagonal)
  (fill-ellipse drawing-pane (make-position 100 100) 80 50 0)
  (draw-ellipse drawing-pane (make-position 100 100) 80 50 0))
                
;; This example uses a multicolor pixmap.
(let* ((frame (make-window :filler :class 'bitmap-window
                :interior (make-box 100 100 300 300)))
       (drawing-pane (frame-child frame)))
  (setf (fill-texture drawing-pane)(find-pixmap :melvin))
  (fill-ellipse drawing-pane (make-position 100 100) 80 50 0)
  (draw-ellipse drawing-pane (make-position 100 100) 80 50 0))

;; This example uses a monochrome pixmap.
(let* ((frame (make-window :filler :class 'bitmap-window
                :interior (make-box 100 100 300 300)))
       (drawing-pane (frame-child frame)))
  (setf (foreground-color drawing-pane) dark-blue)
  (setf (background-color drawing-pane) cyan)
  (setf (fill-texture drawing-pane)
        (make-instance 'pixmap
           :bits-per-pixel 1
           :contents '(#*000111100000
                       #*001000010000
                       #*010000001000
                       #*100000000111
                       #*010000001000
                       #*001000010000)))
  (fill-ellipse drawing-pane (make-position 100 100) 80 50 0)
  (draw-ellipse drawing-pane (make-position 100 100) 80 50 0))

Copyright (c) 1998-2006, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had significant revisions compared to the 6.2 page.
Created 2005.9.20.