Mercurial > cgi-bin > hgwebdir.cgi > POP > oldRepo
diff 1__Development/6__Website/visualizer_project.html @ 0:a8cd65eca9a9
Initial add
| author | Me@portablequad |
|---|---|
| date | Sun, 25 Dec 2011 14:39:36 -0800 |
| parents | |
| children |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/1__Development/6__Website/visualizer_project.html Sun Dec 25 14:39:36 2011 -0800 1.3 @@ -0,0 +1,197 @@ 1.4 +<html> 1.5 +<head> 1.6 +<title>Untitled Document</title> 1.7 +<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 1.8 +</head> 1.9 + 1.10 +<body bgcolor="#FFFFFF"> 1.11 + 1.12 +<h1>The Visualizer Project</h1> 1.13 +<p> </p> 1.14 +<p>This file describes the first Visualizer project </p> 1.15 +<p>========== </p> 1.16 +<p>Steps in the project</p> 1.17 +<p> It looks like a good way to go is to start with some simple examples, then 1.18 + work toward harder ones. This will be easier for you and at the same time let 1.19 + me develop the data structures over time, as the project proceeds. </p> 1.20 +<p>A good way to organize the project is to do a number of smaller, mini-projects. 1.21 + The first is just visualizing a syntax graph for "A + B", and having it paint 1.22 + in the Display. </p> 1.23 +<p>Please be aware that the syntax-graph data structures and the custom properties 1.24 + for EQNLang will change as more experience is gained in using them and it becomes 1.25 + clear that they have to be modified. This will cause the code you write to be 1.26 + modified, even after it is already working. </p> 1.27 +<p>========== </p> 1.28 +<p>Theory behind the syntax graph </p> 1.29 +<p>The theory behind the way I want to do the syntax graph will probably seem 1.30 + a bit "strange" to you at first, especially if you have any experience with 1.31 + compilers. It's a bit abstract; the reason is to allow the same data structures 1.32 + to be re-used for any CTOS language that can be designed. </p> 1.33 +<p>The best file to look at first is the "SyntacticElement.java" file, which has 1.34 + a very long comment that talks a bit about the thinking behind the data structures. 1.35 +</p> 1.36 +<p>To summarize the idea behind the syntax data structures: Syntax is a pattern 1.37 + that correlates to the visual pattern that humans look at. Each element of the 1.38 + visual pattern has a corresponding element in the syntactic pattern. </p> 1.39 +<p>So, that is the only thing that the data structures need to support: an element 1.40 + in the syntax for each visual cue. Visual cues are shapes and physical position. 1.41 + Physical position determines which visual pattern a given shape belongs to (more 1.42 + on this in the comment). </p> 1.43 +<p>So, there are only three kinds of thing in the syntax graph: </p> 1.44 +<p>Syntactic element </p> 1.45 +<p>Syntactic link </p> 1.46 +<p>Syntactic property </p> 1.47 +<p>plus, a set of property-types, and a set of property values, for links and 1.48 + elements </p> 1.49 +<p>To summarize the data structures.. I have only two main syntactic data types: 1.50 + elements and links. Each of these has a list of properties attached to it. </p> 1.51 +<p>The element properties state what kind of element it is (for EQNLang), such 1.52 + as a root of a syntactic pattern, and/or a structural element, and/or a shape 1.53 + containing element. </p> 1.54 +<p>The link properties state what kind of link it is (for EQNLang) such as a "back" 1.55 + link to the root of a syntactic pattern, or a link that indicates that data 1.56 + flows from one syntactic pattern to another..</p> 1.57 +<p> =========== </p> 1.58 +<p>Property Names and Property Values </p> 1.59 +<p>I have decided to make all property names and all property values be integers. 1.60 + I have included, in "EQNLangSyntaxSpecialization" a bunch of files that have 1.61 + static constants in them. These constants define the property names and property 1.62 + values. I also have a skeleton of how to use the properties in EQNLangSrcVisualizer.java 1.63 +</p> 1.64 +<p>That file shows how to use the constants inside switch statements. The switch 1.65 + statements steer, to code that takes some action on the DisplayList. Each piece 1.66 + of code is only invoked if some set of things is true. For example, the method 1.67 + "foobar" is called when "Currently processing a SyntacticElement, and it is 1.68 + a command-type" is true, and only when that is true.</p> 1.69 +<p> If you want to use a different code structure, write me an e-mail that makes 1.70 + a case for why you view the alternative structure as better. </p> 1.71 +<p>You will find in EQNLangSrcHolder a test syntax graph that has been built in 1.72 + the code. This is the first syntax graph that you will visualize. </p> 1.73 +<p>The next project after this one will add multiple syntactic patterns, positioning 1.74 + of them, and scaling of them. For now, just a single command with two variables.</p> 1.75 +<p> ============ </p> 1.76 +<p>What the Visualizer does</p> 1.77 +<p> Each command in EQNLang has not only a shape but "ports". Each port is either 1.78 + an input or an output. They are placed visually around the shape. </p> 1.79 +<p>The Visualizer must place an expression in the position of each port. If the 1.80 + input position in the syntax graph is empty, then the visualizer places an empty 1.81 + box in that input port's position. If the input position links to another command-rooted 1.82 + syntax pattern, then that entire syntax-pattern goes in the input-port's position. 1.83 +</p> 1.84 +<p>The plus command in "A + B" has both input ports filled, and the command has 1.85 + no explicit output port. By "no explicit output port" I mean that, upon evaluation, 1.86 + the expression will be replaced by whatever it evaluates to. An expression's 1.87 + visual placement implies where it's output goes to. Syntax patterns with implied 1.88 + output ports are placed inside the input ports of other syntax patterns. </p> 1.89 +<p>In the expression "A + B", the input ports of the "+" are filled by the "A" 1.90 + and "B". These are both "Name" patterns of memProcessor type. Name patterns 1.91 + have no visual input ports, and implied output ports. </p> 1.92 +<p>What this all means is that information is needed about the position of input 1.93 + ports for each command. This additional information is what the Visualizer will 1.94 + use to place the syntax-patterns. </p> 1.95 +<p>========== </p> 1.96 +<p>Details of the Visualizer project </p> 1.97 +<p>Here is what I would like (most of this is also in comments in the code): </p> 1.98 +<p>-- The Visualizer will generate a DisplayList, which is a linked list of DisplayElements. 1.99 +</p> 1.100 +<p>-- It first places a virtual shape for each syntactic element on a virtual 1.101 + grid, then generates a DisplayElement for each virtual shape. </p> 1.102 +<p>-- The Visualizer doesn't know what the actual shapes are, it only knows the 1.103 + name of the shape and a bounding box for it. The Visualizer works with the bounding 1.104 + boxes. </p> 1.105 +<p>-- The Visualizer places shapes onto a virtual grid. The grid is continuous, 1.106 + so each position is a float value. </p> 1.107 +<p>-- the Display will create its own version of the virtual grid, and set "0,0" 1.108 + of its virtual grid to the lower left corner of its window (to start with.. 1.109 + the User can then pan and zoom). </p> 1.110 +<p>-- Each syntactic element has associated layout information that is looked 1.111 + up via some mechanism. </p> 1.112 +<p>-- The look-up info is loaded from disk during initialization of the Visualizer. 1.113 +</p> 1.114 +<p>-- The layout information is a shape plus a list of ports. </p> 1.115 +<p>-- The shape is a shape-name plus a bounding-box. </p> 1.116 +<p>-- a bounding box consists of an origin x,y value and width plus height value.</p> 1.117 +<p> -- The bounding box for a shape is the "minimum enclosing bounding box". The 1.118 + origin of the shape, when looked up, is always 0,0 </p> 1.119 +<p>-- a port has a bounding box too, but it has no shape.. instead, it's bounding 1.120 + box represents a constraint on how big the collection of shapes inside that 1.121 + port can grow. </p> 1.122 +<p>-- The origin of a port bounding box is relative to the origin of the shape's 1.123 + BB (bounding box). It's as if the shape defined its own mini-grid, and the ports 1.124 + are placed on the shape's mini-grid. Thus, the origins of the ports are actually 1.125 + offsets from the origin of the shape. </p> 1.126 +<p>-- The layout information for a "variable" in the syntax-graph comes from two 1.127 + sources: the type of variable is used to look up a font plus font-size, while 1.128 + the syntax-graph node has an attached text-string as a property-value. </p> 1.129 +<p>-- Generate the shape's bounding box by calculating it. First look up the bounding 1.130 + box for each character in the string (from information about the font). Then 1.131 + calculate the smallest bounding box that encloses the entire string. Make the 1.132 + origin of the calculated enclosing bounding box be 0,0. A variable has no ports, 1.133 + so done. </p> 1.134 +<p>-- do two passes when placing shapes. The first pass generates a tree of bounding 1.135 + boxes, the second pass scales and translates the bounding boxes, placing them 1.136 + onto the virtual grid. </p> 1.137 +<p> </p> 1.138 +<p>First pass: </p> 1.139 +<p>-- walk the syntax-graph (in a spanning tree fashion) and build up a tree of 1.140 + BoundingBoxTreeNode. </p> 1.141 +<p>-- start with a root BBChildLink. Set it to be the current BBChildLink. </p> 1.142 +<p>-- set the root of the syntax-graph to be the current syntactic element. </p> 1.143 +<p>-- Generate a BoundingBoxTreeNode for the current syntactic element. </p> 1.144 +<p>-- Set the link in the current parent BBChildLink to the newly created BoundingBoxTreeNode. 1.145 +</p> 1.146 +<p>-- look up the type of syntactic element to get its shape info and port list. 1.147 +</p> 1.148 +<p>-- If the syntactic element has ports, then make a BBChildLink for each port 1.149 + on the port-list. Make the BBChildLink's BB be the bounding box information 1.150 + that was in the port-info. This is a constraint bounding box. </p> 1.151 +<p>-- Each port corresponds to a child in the syntax graph, go to each child and 1.152 + make a BoundingBoxTreeNode, connect the corresponding BBChildLink to it, and 1.153 + repeat the above process. </p> 1.154 +<p>-- There are two kinds of bounding box here. One kind is the minimum size box 1.155 + that completely encloses a shape. The other kind is a constraint. When the second 1.156 + pass is performed, the shapes will be scaled, such that the shape bounding box 1.157 + gets as big as possible while still completely enclosed by some constraining 1.158 + bounding box. </p> 1.159 +<p>-- See the comments in the skeleton code for BoundingBoxTreeNode and BBChildLink. 1.160 +</p> 1.161 +<p>-- Once all the syntactic elements have been added to the bounding-box tree, 1.162 + go to the second pass, which performs scaling and translation of bounding boxes, 1.163 + which places them onto the virtual grid. </p> 1.164 +<p> </p> 1.165 +<p>Second pass: </p> 1.166 +<p>-- start with a default root bounding box that represents the entire graph. 1.167 + This is the "root" bounding box. It's origin is at 0,0 on the virtual grid. 1.168 +</p> 1.169 +<p>-- this root BB is made the parent constraining BB </p> 1.170 +<p>-- set the root node of the bounding-box tree as the current BoundingBoxTreeNode 1.171 + and begin: </p> 1.172 +<p>-- <loop><loop point> </p> 1.173 +<p>-- generate the minimum enclosing bounding box for the BoundingBoxTreeNode's 1.174 + shape together with all of its child nodes. Leave the BoundingBoxTreeNode's 1.175 + shape where it is, so the generated enclosing BB will have its origin placed 1.176 + relative to the shape's origin, but possibly shifted due to the ports around 1.177 + the shape. </p> 1.178 +<p>-- calculate the scaling factor that will make the enclosing bounding box as 1.179 + large as possible while still being enclosed by the parent constraining bounding 1.180 + box. </p> 1.181 +<p>-- apply the scaling factor (which moves the origins, as well as changes the 1.182 + sizes of the BBs) </p> 1.183 +<p>-- calculate the translation to apply to the resized minimum enclosing BB to 1.184 + shift its origin to match the origin of the parent constraining BB </p> 1.185 +<p>-- apply that translation to the shape's enclosing bounding box and each of 1.186 + its children's constraining bounding boxes. Those bounding boxes are now at 1.187 + their final placement on the virtual grid, at their final size. </p> 1.188 +<p>-- generate the DisplayElement for the BoundingBoxTreeNode's shape, and add 1.189 + it to the DisplayList. </p> 1.190 +<p>-- now, repeat the process for the contents of each child constraining BB: 1.191 + In turn, set the child constraining BB to be the parent constraining BB.. and 1.192 + set the BBChildLink's node as the current BoundingBoxTreeNode.. and go to the 1.193 + <loop point> </p> 1.194 +<p>-- (Note, out of interest, that as one descends the bounding-box tree, the 1.195 + scaling factors multiply, and translations add..) </p> 1.196 +<p> </p> 1.197 +<p>-- When this process is complete for the entire syntax-graph, send the DisplayList 1.198 + to the Display.</p> 1.199 +</body> 1.200 +</html>