Inter-Office MemorandumToCedar InterestDateJanuary 20, 1981FromDoug WyattLocationPalo AltoSubjectThe Cedar Graphics PackageOrganizationPARC/ISLXEROX DRAFT - DRAFT - DRAFT - DRAFT - DRAFTCaution: this is still an incomplete draft. Several sketchy explanations need to be filled out, and a few omittedones need to be filled in.Filed on: [Ivy]CedarGraphics.memoThe Graphics interface and the interfaces on which it depends can be found on [Ivy]Graphics>.The implementation is a part of Cedar.bcd.Definitions files:Graphics.bcd -- the main interface to Cedar GraphicsVector.bcd -- definitions for vectors; included by GraphicsCubic.bcd -- definitions for cubic curves; included by GraphicsStyle.bcd -- definitions for drawing style; included by GraphicsIntroductionThe Cedar Graphics package provides low level display facilities for Cedar. It is capable of driving awide range of raster display devices while presenting a display-independent interface to its clients.Users of the package can specify abstract geometrical objects to be displayed (filled areas, lines, andtext) without being concerned with the peculiar characteristics of the actual display device in use.Cedar Graphics provides a powerful set of primitive operations for driving a virtual display. It isintended as a foundation for the construction of higher level display abstractions such as the CedarDocuments facilities. Cedar Documents is expected to be the primary client of Cedar Graphics. MostCedar programmers will not deal directly with the Graphics interface, but will use the Documentfacilities that are built on top of it. This memo discusses some of the design principles behind Cedar Graphics, then describes the currentinterface in detail. Future incarnations of the package will adhere to the same principles, but theinterface has not reached its final form. Cedar Graphics developed as a Mesa program, apart fromCedar, and does not yet take advantage of Cedar-specific facilities. In particular, it still uses uncountedstorage, and presents an unsafe interface. The performance of the current implementation leaves muchroom for improvement. A substantial revision of the package which fixes many of these problems is inprogress; see CedarGraphicsRevision.memo (also in progress).Principles and Concepts]gpi c8q]rX -q7Br ]q]r -q7Br Yq]r-q 7BqSsrMt% HYuq F A.r0 <\d :* 86 vF(5xr v)q3rv.q2prv/q /Dt ,r] *U )C$ '/5 $aB! "=' !Y(: (7 Q( &[ [ G a =' ,8  )qr tX ?ZgThe Cedar Graphics Package (DRAFT)2Clients of the Graphics interface deal with an abstraction called a display context. A display contextrepresents a virtual display; its primary function is to decouple the user from the characteristics of theunderlying device. Display contexts also hold certain state information which affects the appearance ofobjects drawn in those contexts.The devices supported may differ in a number of respects. Different displays usually differ inresolution and size. Every display context carries a linear transformation which maps from thecoordinate system perceived by the user into the coordinate system required by the device. Thistransformation is initialized so that the user always sees the same initial coordinate system regardless ofwhat device the display context is driving.Devices may also differ in the amount of information used to represent each pixel. The graphicspipeline provides the device with a high precision description of each shape to be drawn; the device issupposed to produce the best rendition it can. A simple bitmap display may represent colors asdifferent stipple patterns. A gray-level display may represent colors as different gray values and applyanti-aliasing techniques to create the appearance of smooth edges.Cedar Graphics is a low level graphics package. It maintains no history of display actions apart fromthe dots on the display. Operations that alter the state of the display context do not affect the currentpicture on the display, but only items drawn subsequently. Think of the display context as atransducer. Clients are responsible for retaining graphical objects they want to display repeatedly.Several features are designed to facilitate the management of graphical objects.The idea is that the client should have a procedure that takes a display context as a parameter anddraws the appropriate figure in that context. In general, information is communicated by a series ofprocedure calls rather than the passing of large or complex data structures.Description of device, world, and user coordinate systems.Display positions are represented throughout the package as floating point numbers (type REAL). Awide range or coordinates can be accommodated, while high precision is maintained. The performanceof Cedar Graphics relies heavily on an efficient implementation of operations on REALs. Floating pointoperations are now implemented in microcode on both Dolphin and Dorado. Floating point hardware is being built for theDolphin. Note that the transformation to device coordinates does not entail any loss of precision. Though theunits of measurement are those natural to the device (e.g., the pixel size), positions retain the fullprecision of floating point numbers. Truncation or rounding takes place only at the last moment, whenscan conversion determines which pixels are to be changed. Combinations of mapping and clipping operations allow a display context to represent some smallerregion of the display, while preserving the client's illusion that it owns the entire screen. Severalcoexisting display contexts may drive disjoint portions of the display in this manner. This is themechanism that the Documents package uses to implement windows.Also note that the bulk of the Cedar Graphics implementation itself is device-independent. Devicedrivers are (will be) relatively small: they need only know how to scan convert simple convex polygons,and how to interpret colors (and how to set up the initial coordinate system and describe its limits).State held by a display context:Transformation: current transformation matrix and stackPosition: current position on the display. interpretation changes with transformationStyle: painting function, texture, and font still too Alto-specific; need a uniform way to specify color;should always replace; think of characters as masks; textures are synthetic images frqGr b 6ur `M _Y ] Zf^ XZ W^"= U.= TV+ Q+F OV N#[ LM KB Gur) FkZ D N CcX AP >P =/H ;L 8: 5UXwr 3.4 2LIwrq 0_ /r ,_8ur *ura )WurC '; $R #$e !G ?  S l qr&, +; u r)furM ;ur'q6 R2 p?\SThe Cedar Graphics Package (DRAFT)3Clipper: current clipping regionPath: current path in progress and stackBox: bounding box for a sequence of display actionsInterface LayersClient interface: carefully hides the device characteristics. This is intended to be a relatively stableinterface. Clients of this interface should be unaffected by the addition of new devices or changes ininterfaces (such as the Pipe or Device interfaces) internal to the implementation.Device interface: modules implementing different displays export this interface. The device only has tounderstand simple convex polygons and the encoding of color. In the current implementation, the device is alsoassumed to understand fonts; this is a bad idea, and will soon be changed.Internal interfaces: may be useful for other graphics applications. Naturally, clients of these interfacespay the price for a more intimate coupling to the implementation of the package. These relativelyvolatile interfaces are subject to change as new capabilities are added or performance tuning is done.The Graphics InterfaceThe following is a detailed description of the current version of the Graphics interface. Note: this islikely to change in the near future.Display ContextsThis section describes procedures for creating, copying, and destroying display contexts; andprocedures for saving and restoring some of the context's state.Graphics.DisplayContext: TYPE = Opaque.DisplayContext;Opaque.DisplayContext: TYPE = LONG POINTER TO ;A DisplayContext denotes a particular display context. Most of the Graphics procedures take aDisplayContext as a parameter.Graphics.DeviceHandle: TYPE = Opaque.DeviceHandle;Opaque.DeviceHandle: TYPE = LONG POINTER TO ;A DeviceHandle denotes a particular display device. DeviceHandles for non-standard devices are obtainedthrough 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 usesthe standard Alto display. The initial state of the context is as follows:Transformation: world coordinate system (see below).Position: [0,0].Style: PaintingFunction is replace; Texture is black; Font is undefined.Clipper: the entire display.Path: empty.Box: disabled. frqGrbur^ur$[ur0 XuX UprV S+; RhR O=[ M%q1 L5J I rV G10 F,: BtX ?rN u >&$ :X 7r"O# 6K@3 wxXwxwx/wxwxwFxXy x -rx r. ,x r(wxX wxwx %wxwxwFxXy x #jrx r%w q' !6wxX wxwxwx@7wxwx rHxwr [Ju r&ururxrxrxrxrxr wururour  2 (?X5The Cedar Graphics Package (DRAFT)4Cedar Graphics defines the world coordinate system as follows: the origin is at the bottom left cornerof the display; increasing x moves rightward, and increasing y moves upward. The units of distance arepoints; there are 72 points to an inch. Points were chosen for convenience in specifying font sizes. Also, a pixel onthe Alto display is defined to be 1 point square.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 ontothe stack. PopContext restores the context state to the state on the top of the stack, and pops thestack.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 goaway when Cedar Graphics is converted to use Cedar's counted storage.Drawing ShapesGraphics.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. A few procedures take aVec which represents a displacement from a location other than the origin; see the descriptions of theindividual procedures for details. The Vector interface provides a collection of INLINE procedures forperforming 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 t3y = c0.y + c1.y t + c2.y t2 + c3.y t3where the parameter t ranges from 0 to 1. Cedar will provide a spline package, which can generate a series ofcubics representing a smooth curve passing through specified knots. Most clients will want to use this rather than computingcoefficients themselves.The following procedures are used to examine and alter the current position, and to draw straight linesof a given width.Graphics.GetPosition: PROC[dc: Graphics.DisplayContext] RETURNS[Graphics.Vec];This returns the current position in user coordinates. Note that a change in the current transformationwill change the coordinates returned by GetPosition, even though the current position remains fixedon 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]; frqGr b51 `V _ur"qB ]1ZwxX wxwxWwx wxwx U*re S&x r4 R" x r0 PMrwxX wxwx@Kwxwx IrTFkwxX wxwF xXwx DrurHq BE ?duX <8wxwxwx9 wxwxwxwx 6rxrD 51xrG 3'xr$wr  2)xr.wxXwxwx wx ,r7*Nurxrxrurxru*q*Nrxru*q(urxrxrurxru)q(rxru)q &,rurqC $H4 #j ?rS wxX wxwxwxwx 8r@' (x r" 0wxXwxwxwx r%xr wxX wxwxwx :?ZThe Cedar Graphics Package (DRAFT)5This moves the current position by the displacement v.Graphics.DrawTo: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];This draws a straight line beginning at the current position and ending at position v, using the currentline width (see below). The current position is moved to the end of the line.Graphics.RelDrawTo: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];This draws a straight line beginning at the current position and ending at the current position plus v,using the current line width (see below). The current position is moved to the end of the line.Graphics.SetLineWidth: PROC[dc: Graphics.DisplayContext, w: REAL];This establishes the width of lines drawn by DrawTo or RelDrawTo. Note that w is interpreted inthe 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.AreasThe following procedures are for drawing filled areas. A shape to be filled is defined by a path. A pathis a set of one or more polygonal boundaries; the boundaries may intersect themselves or each other.Graphics.StartAreaPath: PROC[dc: Graphics.DisplayContext,oddeven: BOOLEAN _ FALSE];This begins a new path. The display context maintains a stack of pending paths. If an incomplete pathis in progress when StartAreaPath is called, that path is pushed onto the stack. The oddevenparameter affects the treatment of self-intersecting areas. If oddeven is FALSE, points with nonzerowrap number are considered to be in the interior; if oddeven is TRUE, only points with odd wrapnumber are considered to be in the interior. A description of wrap number should go here.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];This extends the current path with the specified curve segment.Graphics.NewBoundary: PROC[dc: Graphics.DisplayContext];This closes the current boundary, connecting the last point to the first point of the boundary. Asubsequent EnterPoint will begin a new boundary.Graphics.DestroyPath: PROC[dc: Graphics.DisplayContext];This disposes of the current path, without drawing it, and pops the path stack.Graphics.DrawArea: PROC[dc: Graphics.DisplayContext];This draws the area defined by the current path, filling it using the current texture and paintingfunction, and then pops the path stack.Graphics.DrawRectangle: PROC[dc: Graphics.DisplayContext, ll,ur: Graphics.Vec]; frqGr b4xr^wxXwxwxwx \rSxr [MWwxX wxwxwx Ur+:xr T!>PwxXwxwxwx Nrxrxr xr Mur U KTHYwxXwxwxwxwx Fr$ Bu ?rN ur >& Y:wxXwxwx@9wwxwx 7rJ 5x rx 4r?xrwr u 2r5xrwrur 1,q--wxX wxwxwx +rxr(`wxX wxwxwFxXwx & r?"wxX wxwx rB  x rwxX wxwx ~rOSwxX wxwx r X w'LwxXwxwxwx ?YiThe Cedar Graphics Package (DRAFT)6This draws the specified rectangle (ll and ur are its lower left and upper right corners), filling it usingthe current texture and painting function. The path stack is unchanged.Graphics.DrawScreenArea: PROC[dc: Graphics.DisplayContext];This is equivalent to calling StartAreaPath, entering a path which surrounds the entire physicalscreen, then calling DrawArea. Since all areas are clipped, the effect of DrawScreenArea is to fillall of the current clipping region, using the current texture and painting function.PaintThe following procedures determine the display context parameters used to fill lines, areas, and text.Graphics.PaintingFunction: TYPE = Style.PaintingFunction;Style.PaintingFunction: TYPE = {replace, paint, invert, erase};These are equivalent to the BitBlt functions of the same names. This is much too Alto-specific.PaintingFunction should go away. Replace can be used all the time if characters are properly treated as masks.Graphics.Texture: TYPE = Style.Texture;Style.Texture: TYPE = CARDINAL;The texture value is interpreted as a 4x4 bit square which tiles the plane. The constants white andblack are Textures defined in the interface. This is even more Alto-specific and awful; Color should be usedinstead. Bitmap devices may substitute textures for colors; clients that really want to express textures should use (synthetic)images.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];TransformationsThese are for redefining the virtual coordinate system. Remember that changing the transformation does not alterobjects previously displayed.Graphics.Translate: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];This translates the origin of the coordinate system by v.Graphics.Scale: PROC[dc: Graphics.DisplayContext, v: Graphics.Vec];This scales the coordinate system by [v.x,v.y].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]; frqGr b$xrxr> `G]nwxXwxwx [rx r, Yxr,x r XT Tu QrFNwxXwxwxKawxwx# I r@q  G,BDZwxX wxwxA.wx wxwx >r6qrxr =Sxrxrq$wq ;3L :7wxX wxwx@6(wx2wx wxwx@1ywxwx.Mwx wxwxwx+"wx wxwxwxwx 'u $r7q8 #j bwxX wxwxwx 7r7xr wxXwxwxwx r%xrwxXwxwxwxwxwxwxwx ^wx wxwxwx  ?ZJThe Cedar Graphics Package (DRAFT)7Graphics.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];TextThese are for defining fonts, displaying text, and determining font metrics.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 BoxesHere is an introductory sentence.Graphics.SetClipArea: PROC[dc: Graphics.DisplayContext];This sets the current clipping region to the area defined by the current path. The path is clipped to thephysical display boundaries, but the current clipper is ignored.Graphics.IntersectClipArea: PROC[dc: Graphics.DisplayContext];This is similar to SetClipArea, but it clips the path with the current clipper. In other words, the newclipping region will be the area that would have been drawn if you had called DrawArea instead ofSetClipArea. This should become the default, and SetClipArea should go away. The recipient of a display contextshould not be allowed to reach outside its clipping region!Bounding boxes may be used to perform quick clipping tests for complex objects. Explanation to come.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]; frqGrbwxXwx wxwx@`wxwx]nwx wxwxwx@[wxwx Xu UrLRhwxXwxO=wx wxwxwxwx@MwxwxJwxwxwx@I wxwxEwx wxwxwxBwxwxwxwF x?wxX wxwxwx<\wx wxwxwx@:wF xXwx 7wx wxwxwF x@6(XwFxXwx 2wx wxwx@1ywF xXwx .Mu +"r!'wxX wxwx %rOq $@ wxXwxwx rx r4 %)xr x rq^  ; rOqwxX wxwxwxwxwx wxwx ^wx wxwx@ wF xXwx  ?\x[The Cedar Graphics Package (DRAFT)8Graphics.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 endsHere is an introductory sentence.Graphics.DrawImage: PROC[dc: Graphics.DisplayContext,image: Graphics.ImageHandle];More discussion. frqGrbwxX wxwx@`wF xXwx ]nwx wxwxZCwx wxwxwxwx Wu Sr!PwxX wxwx@O=wx Lru z L0mmb TIMESROMAN  TIMESROMAN TIMESROMAN LOGO TIMESROMAN  TIMESROMAN  TIMESROMAN HELVETICA HELVETICA   HELVETICA   HELVETICA   t'.46j/9 7TCedarGraphics.memoWyattFebruary 2, 1981 2:33 PM