[Indigo]<CedarGraphics>tempcedargraphics.memo!1

Heading:

The Cedar Graphics Interface

Page Numbers: Yes X: 527 Y: 10.5"

Inter-Office Memorandum

ToCedar InterestDateJanuary 15, 1981

FromDoug WyattLocationPalo Alto

SubjectThe Cedar Graphics InterfaceOrganizationPARC/ISL

XEROX

Filed on: [Ivy]<CedarDocs>User>CedarGraphics.memo

The Graphics interface and the interfaces on which it depends can be found on [Ivy]<Cedar>Graphics>. The implementation is a part of Cedar.bcd.

Definitions files:

Graphics.bcd -- the main interface to Cedar Graphics
Vector.bcd -- definitions for vectors; included by Graphics
Cubic.bcd -- definitions for cubic curves; included by Graphics
Style.bcd -- definitions for drawing style; included by Graphics

Introduction

The Cedar Graphics package provides low level display facilities for Cedar, capable of driving a variety of display devices. A client of the Graphics interface can specify abstract geometrical objects to be displayed (filled areas, lines, and text) without being concerned with the peculiar characteristics of the actual display device in use.

This package is intended as a foundation for the higher level display abstractions implemented by Cedar Documents. The Graphics interface presents a basic graphics machine for a virtual display: it provides fundamental operations for drawing primitive shapes and performing transformations and clipping. Most Cedar programs will not deal directly with the Graphics interface, but will use the Document facilities that are built on top of it.

This memo discusses some of the design principles behind Cedar Graphics, then describes the current interface in detail. The design principles are unlikely to change, but the interface has not reached its final form. Cedar Graphics developed as a Mesa program, apart from Cedar, and does not yet take advantage of many Cedar facilities. In particular, it still uses uncounted storage, and presents an unsafe interface. The performance of current implementation leaves much room for improvement. A major revision of the package which fixes many of these problems is in progress: see CedarGraphicsRevision.memo (also in progress).

Design and Basic Concepts

Device Independence

Display Contexts

Coordinate systems

The Graphics Interface

Display Contexts

This section describes procedures for creating, copying, and destroying display contexts; and procedures for saving and restoring some of the context’s state.

Graphics.DisplayContext: TYPE = Opaque.DisplayContext;

Opaque.DisplayContext: TYPE = LONG POINTER TO <opaque type>;

This represents a particular display context.

Graphics.DeviceHandle: TYPE = Opaque.DeviceHandle;

Opaque.DeviceHandle: TYPE = LONG POINTER TO <opaque type>;

This represents a particular display device. DeviceHandles for non-standard devices are obtained through other interfaces which are not described here.

Graphics.NewContext: PROC[device: Graphics.DeviceHandle ← NIL]
RETURNS[Graphics.DisplayContext];

This creates a new display context for the specified display device. If device=NIL, the context uses the standard Alto display.

Graphics.PushContext: PROC[dc: Graphics.DisplayContext];

Graphics.PopContext: PROC[dc: Graphics.DisplayContext];

A display context maintains a stack which can save and restore some of its state: the transformation, position, style, line width, and font. PushContext pushes a snapshot of the current context state onto the stack. PopContext restores the context state to the state on the top of the stack, and pops the stack.

Graphics.CopyContext: PROC[dc: Graphics.DisplayContext] RETURNS[Graphics.DisplayContext];

This creates a new display context whose state is copied from the specified context.

Graphics.FreeContext: PROC[dcPtr: LONG POINTER TO Graphics.DisplayContext];

This unsafe operation frees the storage occupied by the specified display context. Naturally, this will go away when Cedar Graphics is converted to use Cedar’s counted storage.

Coordinate systems

Description of device, world, and user coordinate systems.

Cedar Graphics defines the world coordinate system as follows: the origin is at the bottom left corner of the display; increasing x moves rightward, and increasing y moves upward. The units of distance are points; there are 72 points to an inch. Points were chosen for convenience in specifying font sizes. Also, a pixel on the Alto display is defined to be 1 point square.

Graphics.Vec: TYPE = Vector.Vec;

Vector.Vec: TYPE = RECORD[x,y: REAL];

A Vec usually represents the x and y coordinates of a location on the display. In a few contexts, a Vec represents a displacement from a location other than the origin; see the descriptions of the individual procedures for details. The Vector interface provides a convenient collection of INLINE procedures for performing operations on Vecs.

Cubic.Coeffs: TYPE = RECORD[c0,c1,c2,c3: Vector.Vec];

These are the coefficients of a parametric cubic curve:

x = c0.x + c1.x t + c2.x t2 + c3.x t3

y = c0.y + c1.y t + c2.y t2 + c3.y t3

where the parameter t ranges from 0 to 1. (Cedar will provide a spline package, which can generate a series of cubics representing a smooth curve passing through specified knots. Most clients will want to use this rather than computing coefficients themselves.)

Lines

These are for drawing lines.

Graphics.GetPosition: PROC[dc: Graphics.DisplayContext] RETURNS[Graphics.Vec];

This returns the current position in user coordinates. Note that a change in the current transformation will change the coordinates returned by GetPosition, even though the current position remains fixed on the display.

Graphics.MoveTo: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];

This changes the current position to v.

Graphics.RelMoveTo: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];

Graphics.DrawTo: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];

Graphics.RelDrawTo: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];

Graphics.SetLineWidth: PROC[dc: Graphics.DisplayContext, w: REAL];

This establishes the width of lines drawn by DrawTo or RelDrawTo. Note that w is interpreted in the user coordinate system; its effect is altered by changes in the current transformation. For example, if the coordinate system is scaled by 2, subsequent lines will be twice as thick.

Graphics.GetLineWidth: PROC[dc: Graphics.DisplayContext] RETURNS[REAL];

This returns the current line width.

Areas

These are for drawing filled areas.

Graphics.StartAreaPath: PROC[dc: Graphics.DisplayContext,
oddeven: BOOLEAN ← FALSE];

Graphics.EnterPoint: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];

This enters the point v into the current path.

Graphics.EnterCubic: PROC[dc: Graphics.DisplayContext, c: POINTER TO Cubic.Coeffs];

Graphics.NewBoundary: PROC[dc: Graphics.DisplayContext];

This closes the current trajectory.

Graphics.DestroyPath: PROC[dc: Graphics.DisplayContext];

Graphics.DrawArea: PROC[dc: Graphics.DisplayContext];

Graphics.DrawRectangle: PROC[dc: Graphics.DisplayContext, ll,ur: Graphics.Vec];

Graphics.DrawScreenArea: PROC[dc: Graphics.DisplayContext];

Paint

Texttexttext.

Graphics.PaintingFunction: TYPE = Style.PaintingFunction;

Style.PaintingFunction: TYPE = {replace, paint, invert, erase};

Graphics.Texture: TYPE = Style.Texture;

Style.Texture: TYPE = CARDINAL;

Graphics.SetPaint: PROC[dc: Graphics.DisplayContext,
p: Graphics.PaintingFunction];

Graphics.GetPaint: PROC[dc: Graphics.DisplayContext]
RETURNS[Graphics.PaintingFunction];

Graphics.SetTexture: PROC[dc: Graphics.DisplayContext, t: Graphics.Texture];

Graphics.GetTexture: PROC[dc: Graphics.DisplayContext] RETURNS[Graphics.Texture];

Transformations

These are for redefining the virtual coordinate system.

Graphics.Translate: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];

Graphics.Scale: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];

Graphics.Rotate: PROC[dc: Graphics.DisplayContext, angle: REAL];

Vector.Matrix: TYPE = RECORD[a11,a12,a21,a22: REAL];

Graphics.Concatenate: PROC[dc: Graphics.DisplayContext, m: Vector.Matrix];

Graphics.Map: PROC[sdc,ddc: Graphics.DisplayContext, sp: Graphics.Vec] RETURNS[dp: Graphics.Vec];

Graphics.ScreenPoint: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec] RETURNS[Graphics.Vec];

Text

Here is an introductory sentence.

Graphics.FontId: TYPE[1];

Graphics.MakeFont: PROC[family: STRING, bold,italic: BOOLEAN ← FALSE]
RETURNS[Graphics.FontId];

Graphics.SetFont: PROC[dc: Graphics.DisplayContext,
font: Graphics.FontId, size: REAL];

Graphics.DisplayChar: PROC[dc: Graphics.DisplayContext, c: CHARACTER];

Graphics.DisplayString: PROC[dc: Graphics.DisplayContext, s: LONG STRING];

Graphics.CharData: TYPE = RECORD[size,origin,width: Graphics.Vec];

Graphics.GetCharBox: PROC[dc: Graphics.DisplayContext, c: CHARACTER,
data: POINTER TO Graphics.CharData];

Graphics.GetStringBox: PROC[dc: Graphics.DisplayContext, s: LONG STRING,
data: POINTER TO Graphics.CharData];

Graphics.GetFontBox: PROC[dc: Graphics.DisplayContext,
data: POINTER TO Graphics.CharData];

Clipping and Bounding Boxes

Here is an introductory sentence.

Graphics.SetClipArea: PROC[dc: Graphics.DisplayContext];

Graphics.IntersectClipArea: PROC[dc: Graphics.DisplayContext];

Graphics.BoundingBox: TYPE = ARRAY [0..4) OF Graphics.Vec;

Graphics.InitBoxer: PROC[dc: Graphics.DisplayContext];

Graphics.StopBoxer: PROC[dc: Graphics.DisplayContext,
bbox: POINTER TO Graphics.BoundingBox];

Graphics.PushClipBox: PROC[dc: Graphics.DisplayContext,
bbox: POINTER TO Graphics.BoundingBox];

Graphics.PopClipBox: PROC[dc: Graphics.DisplayContext];

Graphics.Visible: PROC[dc: Graphics.DisplayContext] RETURNS[BOOLEAN];

Images and other loose ends

Here is an introductory sentence.

Graphics.DrawImage: PROC[dc: Graphics.DisplayContext,
image: Graphics.ImageHandle];

More discussion.