GargoyleIndex.tioga
Last edited by Bier on August 18, 1985 11:44:47 pm PDT
The Gargoyle Index
Eric Allan Bier
Introduction
This file lists the modules of Gargoyle, organized by function, along with a description of the state of the code in that module. Beware ye who read herein. Gargoyle has been drawn with bold strokes. Three times again as much work must be done to make Gargoyle into a real tool.
Object Modeling
GGAngle.mesa (small)
Code stolen from Solidviews which implements operations on angle, which are, in a sense, operations on real numbers modulo 360.
GGBoundBox.mesa (small)
The bounding box data abstraction. Creates them. Finds the bounding box which bounds two bounding boxes. Draws them into an Imager.Context. Tells the Imager to use this bounding box as a clipping region.
GGCircles.mesa (medium)
A data abstraction for circles and arcs. Finds intersections of lines and circles. Finds the nearest circle point to a test point. Many procedures are NYI (not yet implemented), including all of the procedures for arcs. Enough are implemented to support circles as alignment objects.
GGDescribe.mesa (small)
Given a gargoyle object, GGDescribe produces a description of that object in English. Useful for debugging and for user feedback. Little use is made of this module currently. DescribeTouchPoints (in the debug menu) uses it though.
GGError.mesa (small)
All messages which gargoyle displays in the message window are sent through GGError. Hence, by modifying GGError one can turn them all off or have them displayed elsewhere. Most of the messages are also sent to the Gargoyle typescript (see Debug Menu/ Typescript to open a Typescript). The Typescript seems to be broken. Text comes out every which-where. I don't know why.
GGLines.mesa (medium)
Code stolen from Solidviews which a straight-line abstraction (similar to GGCircles). Gargoyle lines are fairly heavy-weight data structures. Operatations like distance from point to line are particularly fast, however.
GGModelTypes.mesa
Defines most of the data types used in the modeling part of Gargoyle including:
Basic: Angle, Point, Matrix3by3, Vector, Edge, Line, Circle, Arc
Hierarchy: Scene, Cluster, Outline, Traj, Joint, Sequence, BoundBox, SegmentClass, Camera
Generators: EntityGenerator, TrajGenerator, SequenceGenerator, SegmentGenerator, JointGenerator, BoundBoxGenerator
Touching Constraints: TouchGroup, and TouchItem
GGObjects.mesa (large)
Implements the data abstractions for the entire object hierarchy (except for segments, see GGSegmentImpl). Also implements the generators on the hierarchy. Objects with holes are NYI. Clusters are NYI. Deletion of sequences is NYI.
GGSegment.mesa (large)
Implements all of the segment classes including: Line, Arc, Bezier, Conic, and Spline. The segment classes are defined in GGModelTypes.
GGTouch.mesa (medium)
Maintains a data structure which records which objects are touching each other. This module must be called whenever objects become touching, whenever objects move (in case they have been moved apart), and whenever objects are deleted (so they may be removed from the structures). In practice, much of the work of creating touching relationships is performed by GGCaret. The remainder is done by GGMouseEvent and GGEvent in response to dragging actions and to deletion requests. GGTouch is a pain to debug. The touch entries in the the debug menu are helpful. Touching sequences are NYI (but just copy code from GGCaret.MakeSegmentTouchSegment and GGCaret.MakeJointTouchSegment, and make the obvious modifications). Making two objects touch which were both already touching other things is NYI (I'm working on it).
GGTransform.mesa (tiny)
A veneer over ImagerTransformation to avoid having to convert to VEC all over the place. Should probably be expanded and used throughout Gargoyle.
GGUtility.mesa (tiny)
Some common operations on LIST OF REF ANY.
GGVector.mesa (medium)
Operations on vectors, such as: Make a unit vector in a given direction. Find the angle between two vectors. Add, Subtract, Scale, Dot-Product, Normalize, Magnitude, etc. Largely stolen from Solidviews. Should be all implemented.
The User Interface
GGAlign.mesa (medium)
Figures out what alignment lines should be used for the current action. There is a single procedure in the interface:
AddItemsForAction: PROC [gargoyleData: GargoyleData, objectBag: ObjectBag, action: ATOM];
The atom describes the current action (e.g. $Drag, $Rotate, $SelectPoint). GGAlign uses this atom to decide which scene objects will trigger alignment lines. For each trigger, GGAlign uses the current Menu selection to decide what firing rule to apply to derive alignment lines from that trigger (e.g. if 60 degree slope lines are turned on then vertex triggers will have 60 degree slope lines through them).
The firing rules need some fine tuning. In particular, we need to decide whether or not a trajectory which is being dragged should be allowed to trigger alignment lines. This usually has the undesirable effect of attracting the object back to its starting position. On the other hand, while rubber-banding an object, having non-moving parts be "hot" seems to be useful at times.
GGCaret.mesa (medium)
The caret knows where it is, what object it is sitting on (the chair) and what object it is being attracted to (the attractor). Hence, the caret is in a good position to create touching constraints (see GGTouch.mesa). Caret looks (as in Tioga) are NYI. At present, segments added to a trajectory with wide lines will always have normal lines, and segments added to a spline curve will be straight lines. The anchor (center of rotation. Created with CTRL-A) is also a caret.
GGContainer.mesa (medium)
This is code copied from Solidviews, which in turn was copied from Containers.mesa. It implements the Gargoyle container viewers class. The only part worth playing with is probably the destroy proc. We might use the destroy proc to close the currently open session log (if any) for instance.
GGDrawProcess.mesa (medium)
This is the famous slack process. Some recent additions include: The slack process keeps a record of its last n actions (where an action is either receiving a request to do something, or actually getting around to do it). This log can be dumped on the Gargoyle Typescript from the Slack Log entry of the Debug Menu. The slack process should be modified so that, if the queue gets full, requestors will be told to wait. Currently, requestors are ignored in this situation. Rename to GGSlackProcess when you get a chance.
GGEvent.mesa (large)
Handles all events which are triggered by menu buttons. It's time to split this into ImplA and ImplB.
GGMenus.mesa (large)
Builds the Gargoyle control panel, using button types defined in GGButtons.mesa and Christian Jacobi's pop up menus. It is (almost) true that all button actions now go through the InputNotify pipeline. Actions which create menus, and SessionLog actions are the exceptions.
GGMouseEvent.mesa (large)
Handles all events which are triggered by mouse actions. These include adding segments, SelectPoint/PlaceCaret, drag, rotate, select trajectory, and copy select trajectory.
Recent structural changes: GargoyleData contains an atom representing the action "mode" which the user is in (where modes last only as long as keys are held down). The succession of atoms is monitored (to make sure the user doesn't change operations in the middle). If a switch is detected, the operation is aborted and further mouse motion is ignored.
GGGraphicsButton.mesa (small)
Defines a button class, where the picture displayed is an arbitrary set of Imager calls. (Used for the gravity extent button). Automatically puts the Imager origin in the center of the button. With a little work (e.g. allowing the client pass a callback proc which does the drawing), this could be made into a released package.
GGGravity.mesa (medium)
Given a set of alignment lines and Gargoyle object, and given a test point, find the nearest point on the nearest object, giving preference to points, if desired. Could be released as a separate package if only it weren't so dependent on Gargoyle trajectories (which it uses for efficiency).
GGInterfaceTypes.mesa
Defines the types used in the gargoyle interface, including (the enormous) record GargoyleData which contains all of the state of a single gargoyle viewer. Note that no state is kept in global variables, so having multiple Gargoyle viewers at the same time should be possible. Even dragging objects from one to the other shouldn't be too hard.
GGRefresh.mesa (medium)
A refresh scheme based on caching image parts in bitmaps. A number of parts of GGRefresh never quite got finished. DoubleBuffer off doesn't really turn off double buffering in all cases. Bounding boxes were used to speed refresh for a while, but were disabled to keep refresh simple. Consequently, $PaintEntireScene is the most common atom received by GGRefresh.ActionAreaPaint.
GGSelect.mesa (large)
A hierarchical selection scheme where selected objects are both marked with a boolean and the root of selected subtrees is put on a list. There are 4 different kinds of selection: normal, copy, hot, and active. active was for symmetry groups and is not yet used. A recent addition: Trajectories are never placed on the selected list. Regardless of whether a whole trajectory is selected or some part of it is selected, a Sequence is placed on the list to represent the trajectory. This shows promise. Sequences require a bit of care, however, since the Sequence which represents a trajectory on the "normal" list may not be the same as a Sequence which represents a trajectory on the "hot" list for instance. (Looks like a candidate for a healthy dose of data abstraction).
GGSessionLog.mesa (medium)
Records all user actions which are active on by the slack process in a file (named by selecting a file name and clicking OpenLog). Allows these logs to be played back. Oddly enough, session logs can be used as an interim file format. Much of the parsing code was copied from Solidviews. It is antedilluvian. However, if you want more of same, copy from TFI3dImpl.mesa in Solidmodeler.df.
GGShapes.mesa (small)
Draws cute little shapes into an Imager.Context (e.g. control points, alignment lines, gravity test patterns).
GGUserInput.mesa (small)
All action atoms pass through GGUserInput. It figures out which procedure will eventually handle the action, and passes this information on to GGDrawProcess.
GGWindow.mesa (small)
Calls GGMenu.mesa to make the Gargoyle control panel. Call GGContainer to make the container. Builds the action area. Initializes the world (i.e. gargoyleData).
Gargoyle.tip
Currently contains a lot of silly mappings just used for debugging (e.g. CTRL-G advances the gravity type menu, CTRL-H toggles 90 degree slope lines).
Gargoyle.icons
We need a better icon.
GGToDo.tioga (large)
A list of things that need to be done.
GGScraps.tioga (small)
Old pieces of code which are probably obsolete, but you never know.
GGButtons.mesa (medium)
The beginnings of a package which should eventually replace ChoiceButtons, TiogaButtons, and Menus. This buttons (begin to) obey the principals of the New CSL Interactive Systems Architecture. That is, you tell that what atoms to pass to whom, rather than who to call.
GGViewerOps.mesa (small)
Utilities for reading ROPES from and writing ROPES to TextViewers, Buttons, and Labels.