graphics-state

graphics-state System Class

Summary

The graphics state object, holding default parameters for drawing operations on an associated port.

Package

graphics-ports

Superclasses

t

Accessors

graphics-state-transform
graphics-state-foreground
graphics-state-background
graphics-state-operation
graphics-state-stipple
graphics-state-pattern
graphics-state-thickness
graphics-state-scale-thickness
graphics-state-dashed
graphics-state-dash
graphics-state-fill-style
graphics-state-line-end-style
graphics-state-line-joint-style
graphics-state-mask
graphics-state-mask-x
graphics-state-mask-y
graphics-state-mask-transform
graphics-state-font
graphics-state-text-mode
graphics-state-shape-mode
graphics-state-compositing-mode

Description

The system class graphics-state contains the default values of graphics parameters for drawing operations. Each graphics port has a graphics-state object associated with it. The drawing operations such as draw-ellipse, draw-rectangle and draw-string can override specific parameters by passing them as keyword arguments.

graphics-state objects are used in the with-graphics-state macro and modified using the accessor functions listed above. See 13.3.1 Setting the graphics state for examples.

graphics-state contains the following properties:

`transform`	A transform object which determines the coordinate transformation applying to the graphics port. The default value is the unit transform which leaves the port coordinates unchanged from those used by the host window system — origin at top left, X increasing to the right and Y increasing down the screen. Allowed values are anything returned by the transform functions, described in 13.6 Graphics state transforms.
`foreground`	Determines the foreground color used in drawing functions. The value can be a converted color (result of convert-color), a color name symbol, a color name string or a color spec object. Using converted colors results in better performance, because it saves the system from doing the conversion each time it uses it. The default value is `:black`. The value `:color_highlighttext` is useful for drawing text with the system highlighting.
`background`	Determines the background color used in functions which draw text such as draw-string when `block` is true. On X11/Motif, `background` also determines the background color used in drawing functions which use a stipple. Valid values are the same as for `foreground`. The default value is `:white`. The value `:color_highlight` is useful for drawing text with the system highlighting.
`operation`	Determines the color combination used in the drawing primitives when the `port`'s `drawing-mode` is `:compatible`. Valid values are 0 to 15, being the same logical values as the `op` arg to the Common Lisp function boole. The default value is boole-1. 13.7.1 Combining pixels with :compatible drawing shows how to use `operation`.
`stipple`	On X11/Motif `stipple` is a 1-bit pixmap ("bitmap") or `nil` (which is the default value). The bitmap is used in conjunction with the `fill-style` when drawing. Here, `nil` means that all pixels are drawn in the `foreground` color. A stipple is not transformed by the `transform` parameter. Its origin is assumed to coincide with the origin of the port. The `stipple` is tiled across the drawing. `stipple` is ignored if a `pattern` is given. If no `fill-style` is given, or it is specified as `:solid`, when a `stipple` is given, then `fill-style` defaults to `:opaque-stippled`.
`fill-style`	Determines how the drawing is done. The value should be one of `:solid`, `:tiled, :opaque-stippled` or `:stippled`. The default value `:solid` means that the `foreground` is used everywhere. `:tiled` means that the `pattern` is repeated over across the drawing. Additionally on X11/Motif `:opaque-stippled` means that the `stipple` bitmap is used with stipple 1s giving the `foreground` and 0s the `background`. `:stippled` means that the `stipple` bitmap is used with `foreground` where there are 1s and where the are 0s, no drawing is done. If you specify a stipple but no `fill-style`, or a `fill-style` of `:solid`, it defaults to `:opaque-stipple`.
`pattern`	An image the same depth as the `port`, or `nil`. If non-nil, `pattern` is used as the source of color for drawing instead of the `foreground` and `background` parameters. A pattern is not transformed by the `transform` parameter. The `pattern` is tiled across the drawing. When `pattern` is specified, the `stipple` value is ignored.The default value of `pattern` is `nil`. See 13.10 Working with images for information on creating an image.
`thickness`	A number (defaulting to 1) specifying the thickness of lines drawn. If `scale-thickness` is non-nil, the value `thickness` is in `port` (transformed) coordinates, otherwise `thickness` is in pixels.
`scale-thickness`	A boolean, defaulting to `t` which means interpret the `thickness` parameter in transformed port coordinates. If `scale-thickness` is `nil`, `thickness` is interpreted in pixels.
`dashed`	A boolean, defaulting to `nil`. If `dashed` is `t` then lines are drawn as a dashed line using `dash` as the mark-space specifier.
`dash`	A list of two or more integer, or `nil`. A list of integers specifies the alternate mark and space sizes for dashed lines. These mark and space values are interpreted in pixels only. The default value of `dash` is `(4 4)`.
`line-end-style`	The value should be one of `:butt`, `:round` or `:projecting` and specifies how to draw the ends of lines. The default value is `:butt`.
`line-joint-style`	The value should be one of `:bevel`, `:miter` or `:round` and specifies how to draw the areas where the edges of polygons meet. The default value is `:miter`.
`mask`	`nil`, or a list specifying a shape. The mask clips the drawing, so that drawing occurs only inside it. `mask` should be `nil` (the default), a list of the form (`x` `y` `width` `height`), defining a rectangle inside which the drawing is done or a list of the form (`:path` `path` `:fill-rule` `fill-rule`) specifying a path inside which the drawing is done. The mask is not tiled. In the latter case `path` should be a path specification (see draw-path). The `fill-rule` specifies how overlapping regions are filled. Possible values are `:even-odd` and `:winding`. The `mask` will be transformed by the `mask-transform` parameter. There some examples of path masks in: (example-edit-file "capi/graphics/paths")
`mask-x`	An integer specifying in window coordinates where in the port the X coordinate of the mask origin is to be considered to be. The default value is 0. The `mask-x` parameter works only when the `drawing-mode` is `:compatible` and the platform is GTK+ or X11/Motif. `mask-x` is deprecated.
`mask-y`	An integer specifying in window coordinates where in the port the Y coordinate of the mask origin is to be considered to be. The default value is 0. The `mask-y` parameter works only when the `drawing-mode` is `:compatible` and the platform is GTK+ or X11/Motif. `mask-y` is deprecated.
`mask-transform`	A transform object which determines the coordinate transformation use for the mask in `drawing-mode` `:quality`. `mask-transform` is used only in `drawing-mode` `:quality`. It is ignored in `drawing-mode` `:compatible`. The default value is the unit transform, which can also be specified as `nil`. Other allowed values include anything returned by the transform functions, described in 13.6 Graphics state transforms. The other allowed value of `mask-transform` is the keyword `:dynamic` which is replaced by the current value of the `transform` graphics state parameter when the drawing operation uses the mask.
`font`	Either `nil` or a font object to be used by the draw-character and draw-string functions. The default value is `nil`. Note that `font` cannot be a font-description. Use find-best-font to convert a font-description to a font.
`text-mode`	A keyword controlling the mode of rendering text, most importantly anti-aliasing (see below).
`shape-mode`	A keyword controlling the mode of drawing shapes, that is, anything except text (see below).
`compositing-mode`	A keyword controlling the combining of new drawing with existing drawing (see below).

Each of text-mode and shape-mode can be one of:

`:plain`	No anti-aliasing.
`:antialias`	With anti-aliasing.
`:fastest`	Fastest rendering. The same as `:plain` except on Windows.
`:best`	Best display.
`:default`	The system default (which is `:antialias`).

Additionally text-mode can be :compatible, which causes text to be drawn the way it would be drawn if drawing-mode was :compatible. This makes a difference only on Microsoft Windows, because on other platforms the default text-mode draws like the :compatible one.

The default of both text-mode and shape-mode is :default.

compositing-mode is a keyword or an integer controlling the compositing mode, that is the way that a new drawing is combined with the existing value in the target of the drawing to generate the result.

Two values of compositing-mode are supported on all platforms other than Motif:

`:over`	Draw over the existing values. If the source is a solid color, then the result is simply the source. If the source has alpha value `alpha`, then it is blended with the destination, with the destination multiplied by the remainder of the alpha, that is (- 1 `alpha`).
`:copy`	The source is written to the destination ignoring the existing values. If the source has alpha and the target does not, that has the effect of converting semi-transparent source to solid.

The default value of compositing-mode is :over.

The value :copy of compositing-mode is especially useful for creating a transparent or semi-transparent pixmap-port, which can be displayed directly or converted to an image by make-image-from-port.

On Cocoa 10.5 and later and GTK+ 2.8 or later, these additional keyword values of compositing-mode are supported: :clear, :over, :in, :out, :atop, :dest-over, :dest-in, :dest-out, :dest-atop, :xor and :add. These correspond to the CAIRO_OPERATOR_* operators in Cairo, which are documented in cairographics.org/operators and the CGBlendMode values which are documented in the CGContext Reference at developer.apple.com .

Note: on GTK+, the "unbounded" operators (:in, :out, :dest-in and :dest-atop) do not work properly for shape drawings. They can only be used for image drawing and copying operations.

Both Cocoa and GTK+ also allow compositing-mode to be an integer, which is simply passed through to the underlying system. This allows using modes that are not available via keywords, but it is not portable. For Cocoa, it is a CGBlendMode as documented in the CGContext Reference. For GTK+ it is cairo_operator_t, as documented in the entry for cairo_t in the Gnome documentation for Cairo.

Note: For drawing images on Cocoa, only values that corresponding to available keywords work properly.

Notes

operation is not supported for drawing text on Microsoft Windows.
stipple is supported only on X11/Motif.
mask-x and mask-y are supported only on GTK+ and X11/Motif, and only when the drawing-mode is :compatible.
pattern is supported only on Microsoft Windows, GTK+ and X11/Motif.
operation is not supported by Cocoa/Core Graphics so this slot or argument is ignored on Cocoa.
operation is ignored when the port's drawing-mode is :quality.
text-mode and shape-mode are supported only on Cocoa, Cairo and GDI+, which are used on Macintosh, GTK and Windows respectively when the drawing-mode is :quality. For more information about drawing-mode, see 13.2.1 The drawing mode and anti-aliasing.

Examples

(example-edit-file "capi/graphics/compositing-mode-simple")

(example-edit-file "capi/graphics/compositing-mode")