13.2 Features

The main features of graphics ports are:

1. Each port has a "graphics state" which holds all the information about drawing parameters such as color, line thickness, fill pattern, line-end-style and so on. A graphics state object can also be created independently of any particular graphics port.
2. The graphics state contents can either be enumerated in each drawing function call, bound to values for the entirety of a set of calls, or permanently changed.
3. The graphics state includes a transform which implements generalized coordinate transformations on the port's coordinates.
4. Off-screen ports can compute the horizontal and vertical bounds of the results of a set of drawing function calls, thus facilitating image or pixmap generation.

13.2.1 The drawing mode and anti-aliasing

Graphics ports has two drawing modes:

The main visible effect is that with drawing-mode :quality, all drawings are transformed properly.

With drawing-mode :compatible, strings and images are not scaled or rotated at all, and ellipses are not rotated correctly. Other shapes are transformed "at the front", that is they are drawn as if the drawing function was called with transformed coordinates. The target of copy-pixels is also transformed "at the front", that is the rectangle can be translated, but not scaled or rotated.

With drawing-mode :quality, all drawings are fully transformed correctly. Shapes are transformed "at the back", that is they are drawn and then the result of the drawing is transformed. Note that clear-rectangle and pixblt are not drawing functions in this sense, and do not take transforms into account.

Another difference is that drawing-mode :quality supports anti-aliasing on Windows, and on GTK+ it adds control over anti-aliasing. See shape-mode and text-mode on the page for graphics-state.

With drawing-mode :quality the operation value in the graphics-state is not supported and is ignored. This is because operations do not combine sensibly with anti-aliasing and colors with alpha components. Instead, there is now compositing-mode. For more information see the page for graphics-state.

On Microsoft Windows with drawing-mode :quality only Truetype fonts are supported.

The drawing-mode of all graphics ports is :quality by default, except when a graphics port is made in association with another graphics ports (for example, by create-pixmap-port), in which case the drawing-mode is inherited from the "parent" graphics port.

All the interfaces that create graphics ports, or modify a graphics port to draw to another place, take keyword argument :drawing-mode. Its value drawing--mode can be :quality, :compatible, or nil which is interpreted as use the default (either inherited or the global default :quality). These interfaces are listed in 13.1.1 Creating instances.

These examples demonstrate features that are available only with drawing-mode :quality:

Rotating a string:

(example-edit-file "capi/graphics/catherine-wheel")

Using compositing-mode.

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

Using compositing-mode.

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

Using compositing-mode, transforming an image.

(example-edit-file "capi/graphics/images-with-alpha")