The graphics state object, holding default parameters for drawing operations on an associated port.
graphics-ports
t
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
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:
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. | |
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. | |
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 | |
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. | |
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 . | |
Determines how the drawing is done. The value should be one of
Additionally on X11/Motif | |
An image the same depth as the port, or See 13.10 Working with images for information on creating an image. | |
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. | |
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. | |
A boolean, defaulting to nil . If dashed is t then lines are drawn as a dashed line using dash as the mark-space specifier. | |
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) . | |
The value should be one of :butt , :round or :projecting and specifies how to draw the ends of lines. The default value is :butt . | |
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 should be
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 There some examples of path masks in: (example-edit-file "capi/graphics/paths") | |
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 mask-x is deprecated. | |
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 mask-y is deprecated. | |
A transform object which determines the coordinate transformation use for the mask in drawing-mode
mask-transform is used only in drawing-mode | |
Either Note that font cannot be a font-description. Use find-best-font to convert a font-description to a font. | |
A keyword controlling the mode of rendering text, most importantly anti-aliasing (see below). | |
A keyword controlling the mode of drawing shapes, that is, anything except text (see below). | |
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.
:compatible
.:quality
.:quality
. For more information about drawing-mode, see 13.2.1 The drawing mode and anti-aliasing.
(example-edit-file "capi/graphics/compositing-mode-simple")
(example-edit-file "capi/graphics/compositing-mode")
make-graphics-state
set-graphics-state
with-graphics-state
13 Drawing - Graphics Ports
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:33:02