About coordinate systems in in Common Graphics

This document contains the following sections:

Common Graphics uses various terms to describe different ways that it measures coordinates in various contexts, such as window units and stream units. These terms denote coordinates that differ in two ways:

1. the size of the basic unit of distance
2. the location of the origin point, where x and y are both zero

The following two sections, Section 1.0 Coordinate System Unit of Size, and Section 2.0 Coordinate System Location of Origin, explain each type of difference.

1.0 Coordinate System Unit of Size

Distances, offsets, and sizes in common graphics are usually measured in pixels. For example, the left property of a window is expressed as the number of pixels that fit in a horizontal line between the window's exterior left edge and the interior left edge of its parent window. These pixel-based measurements are referred to as being in device units, since their size depends on the resolution of the display device.

One alternative to measuring in pixel units is to use dialog units, where one dialog unit is equal to one-fourth of a system font character width or one-eighth of a system font character height. Common Graphics allows for the size of a control to be specified in dialog units (by passing the :dialog-units-p initarg to make-instance (or make-window) when creating the control), but we discourage the use of dialog units since the system font (provided by the video display adapter driver) is no longer commonly used, and because common graphics measures arbitrary drawing positions and font sizes and so on in pixels, and it's easier to fit all parts of a graphical interface together if the same units are used for everything.

The other alternative to pixel-size device units is to use a scaling-stream. A scaling stream class is any class that is a subclass of graphical-stream and also a subclass of the scaling-stream mixin class. The basic unit of distance of a scaling stream is initially device units but may be set to any arbitrary size by calling (setf stream-units-per-inch) or (setf stream-units-per-mm).

The only scaling stream class that common graphics supplies is the printer class, but an application may create and use scaling window classes if it is desired to draw in windows using coordinates expressed in some unit other than pixels. It is particularly useful to scale a printer stream to use the same stream-units-per-inch as a window. Then the same drawing code can be used to draw on both the window and the printer at the same size, without the application code needing to scale its own coordinates for each call to a drawing function. This can be achieved by evaluating

(setf (stream-units-per-inch my-printer-stream)
      (stream-units-per-inch my-window))

Note: this technique may cause fatter-than-desired lines since line thicknesses and so on are still limited to integral stream-unit values even though 1 stream-unit of thickness may now be many device pixels thick. Drawing glitches might also occur due to floating-point round-off in the scaling conversion. You also may need to add a fudge factor to this expression, though, since the operating system does not actually know how big the monitor is, and typically estimates it badly. Multiplying by 0.85 is suggested.

The functions device-to-scaling-units and scaling-to-device-units can be used to translate between scaled and non-scaled positions and boxes.

2.0 Coordinate System Location of Origin

Stream coordinates are the application-level coordinates that are normally used for specifying drawing positions on a drawing "stream", which could be either a window or a printer stream or some other two-dimensional output stream. Stream coordinates are also used for specifying child window locations and other application-level positions except where otherwise noted.

Each coordinate indicates the distance rightward or downward from an arbitrary stream-origin. For example, if the stream-origin of a stream is (100, 200), then the leftmost x coordinate in the entire "page" (or canvas) that can be drawn into for the stream will be -100, the topmost y coordinate will be -200, the rightmost x coordinate will be

(- (page-width stream) 100)

and the bottommost y coordinate will be

(- (page-height stream) 200)

The function stream-to-stream-units translates coordinates in one stream to be relative to another stream; this can be done only if the two streams have a common ancestor, such as with windows on a screen, since otherwise no relationship between the two coordinate systems is defined.

Page coordinates are stream coordinates with the arbitrary stream-origin added on, and so each coordinate indicates a distance rightward or downward from the upper-left corner of the entire "page" (or canvas) that is being drawn on. The stream-origin is usually left at its default position of (0, 0) and so page coordinates are usually the same as stream coordinates. But an application may, for example, find it useful to move the stream origin in order to draw a polygon at various places on the page without modifying the individual vertices of the polygon.

Only the origin itself is specified in page coordinates; elsewhere stream coordinates should suffice for "user" positions and device coordinates (introduced next) for "physical" positions.

Device coordinates are page coordinates unscaled and unscrolled; that is, they are always measured in pixels (which are what a "device" such as a screen or printer uses itself), and are relative to the upper-left corner of some "physical" device such as a printed page or window interior. (Actually stream and page coordinates are usually measured in pixels as well, except when the stream is a scaling-stream, for which an arbitrary unit of size may be established. A printer stream is always a scaling-stream, and a window is a scaling-stream if an application has mixed the scaling-stream class into the window's class.)

The functions stream-to-device-units and device-to-stream-units translate between stream and device coordinates.

When working in a window, device coordinates are also called window coordinates and are relative to the upper-left of the physical window interior rather than to the upper-left of the virtual canvas (or page) on which the application draws.

The functions stream-to-device-units and device-to-stream-units translate between stream and window coordinates just as they do with device coordinates generally. The function window-to-window-units translates window coordinates of one window into window coordinates of another window.

When working in a window or on the screen itself, screen coordinates are relative to the upper-left corner of the physical screen. The functions window-to-screen-units and screen-to-window-units translate between window and screen coordinates.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.