/unmaintained/adsoda/adsoda-docs.factor

  1! Copyright (C) 2008 Jeff Bigot
  2! See http://factorcode.org/license.txt for BSD license.
  3USING: help.markup help.syntax ;
  4IN: adsoda
  5
  6! --------------------------------------------------------------
  7! faces
  8! --------------------------------------------------------------
  9ARTICLE: "face-page" "Face in ADSODA"
 10"explanation of faces"
 11$nl
 12"link to functions" $nl
 13"what is an halfspace" $nl
 14"halfspace touching-corners adjacent-faces" $nl
 15"touching-corners list of pointers to the corners which touch this face" $nl
 16"adjacent-faces list of pointers to the faces which touch this face"
 17{ $subsections
 18    face
 19    <face>
 20}
 21"test relative position"
 22{ $subsections
 23    point-inside-or-on-face?
 24    point-inside-face?
 25}
 26"handling face"
 27{ $subsections
 28    flip-face
 29    face-translate
 30    face-transform
 31}
 32
 33;
 34
 35HELP: face
 36{ $class-description "a face is defined by"
 37{ $list "halfspace equation" }
 38{ $list "list of touching corners" }
 39{ $list "list of adjacent faces" }
 40$nl
 41"Touching corners and adjacent faces are defined by algorithm thanks to other faces of the solid"
 42}
 43
 44
 45;
 46HELP: <face> 
 47{ $values { "v" "an halfspace equation" } { "tuple" "a face" }  }   ;
 48HELP: flip-face 
 49{ $values { "face" "a face" } { "face" "flipped face" } }
 50{ $description "change the orientation of a face" }
 51;
 52
 53HELP: face-translate 
 54{ $values { "face" "a face" } { "v" "a vector" } }
 55{ $description 
 56"translate a face following a vector"
 57$nl
 58"a translation of an halfspace doesn't change the normal vector. this word just compute the new constant term" }
 59
 60 
 61 ;
 62HELP: face-transform 
 63{ $values { "face" "a face" } { "m" "a transformation matrix" } }
 64{ $description  "compute the transformation of a face using a transformation matrix" }
 65 
 66 ;
 67! --------------------------------
 68! solid
 69! --------------------------------------------------------------
 70ARTICLE: "solid-page" "Solid in ADSODA"
 71"explanation of solids"
 72$nl
 73"link to functions"
 74{ $subsections
 75    solid
 76    <solid>
 77}
 78"test relative position"
 79{ $subsections
 80    point-inside-solid?
 81    point-inside-or-on-solid?
 82}
 83"playing with faces and solids"
 84{ $subsections
 85    add-face
 86    cut-solid
 87    slice-solid
 88}
 89"solid handling"
 90{ $subsections
 91    solid-project
 92    solid-translate
 93    solid-transform
 94    subtract
 95    get-silhouette 
 96    solid=
 97}
 98;
 99
100HELP: solid 
101{ $class-description "dimension" $nl "silhouettes" $nl "faces" $nl "corners" $nl "adjacencies-valid" $nl "color" $nl "name" 
102}
103;
104
105HELP: add-face 
106{ $values { "solid" "a solid" } { "face" "a face" } }
107{ $description "reshape a solid with a face. The face truncate the solid." } ;
108
109HELP: cut-solid
110{ $values { "solid" "a solid" } { "halfspace" "an halfspace" } }
111{ $description "like add-face but just with halfspace equation" } ;
112
113HELP: slice-solid
114{ $values { "solid" "a solid" } { "face" "a face" } { "solid1" "the outer part of the former solid" } { "solid2" "the inner part of the former solid" } }
115{ $description "cut a solid into two parts. The face acts like a knife"
116}  ;
117
118
119HELP: solid-project
120{ $values { "lights" "lights" } { "ambient" "ambient" } { "solid" "solid" } { "solids" "projection of solid" } }
121{ $description "Project the solid using pv vector" 
122$nl
123"TODO: explain how to use lights"
124} ;
125
126HELP: solid-translate 
127{ $values { "solid" "a solid" } { "v" "translating vector" } }
128{ $description "Translate a solid using a vector" 
129$nl
130"v and solid must have the same dimension "
131} ;
132
133HELP: solid-transform 
134{ $values { "solid" "a solid" } { "m" "transformation matrix" } }
135{ $description "Transform a solid using a matrix"
136$nl
137"v and solid must have the same dimension "
138} ;
139
140HELP: subtract 
141{ $values { "solid1" "initial shape" } { "solid2" "shape to remove" } { "solids" "resulting shape" } }
142{ $description  "Substract solid2 from solid1" } ;
143
144
145! --------------------------------------------------------------
146! space 
147! --------------------------------------------------------------
148ARTICLE: "space-page" "Space in ADSODA"
149"A space is a collection of solids and lights."
150$nl
151"link to functions"
152$nl
153"Defining words"
154{ $subsections
155    space
156    <space>
157    suffix-solids 
158    suffix-lights
159    clear-space-solids 
160    describe-space
161}
162
163
164"Handling space"
165{ $subsections
166    space-ensure-solids
167    eliminate-empty-solids
168    space-transform
169    space-translate
170    remove-hidden-solids
171    space-project
172}
173
174
175;
176
177HELP: space 
178{ $class-description 
179"dimension" $nl " solids" $nl " ambient-color" $nl "lights" 
180}
181;
182
183HELP: suffix-solids 
184"( space solid -- space )"
185{ $values { "space" "a space" } { "solid" "a solid to add" } }
186{ $description "Add solid to space definition" } ;
187
188HELP: suffix-lights 
189"( space light -- space ) "
190{ $values { "space" "a space" } { "light" "a light to add" } }
191{ $description "Add a light to space definition" } ;
192
193HELP: clear-space-solids 
194"( space -- space )"   
195{ $values { "space" "a space" } }
196{ $description "remove all solids in space" } ;
197
198HELP: space-ensure-solids 
199{ $values { "space" "a space" } }
200{ $description "rebuild corners of all solids in space" } ;
201
202
203
204HELP: space-transform 
205{ $values { "space" "a space" } { "m" "a matrix" } }
206{ $description "Transform a space using a matrix" } ;
207
208HELP: space-translate 
209{ $values { "space" "a space" } { "v" "a vector" } }
210{ $description "Translate a space following a vector" } ;
211
212HELP: describe-space
213{ $values { "space" "a space" } }
214{ $description "return a description of space" } ;
215
216HELP: space-project 
217{ $values { "space" "a space" } { "i" "an integer" } }
218{ $description "Project a space along ith coordinate" } ;
219
220! --------------------------------------------------------------
221! 3D rendering
222! --------------------------------------------------------------
223ARTICLE: "3D-rendering-page" "The 3D rendering in ADSODA"
224"explanation of 3D rendering"
225$nl
226"link to functions"
227{ $subsections
228    face->GL
229    solid->GL
230    space->GL
231}
232
233;
234
235HELP: face->GL 
236{ $values { "face" "a face" } { "color" "3 3 values array" } }
237{ $description "display a face" } ;
238
239HELP: solid->GL 
240{ $values { "solid" "a solid" } }
241{ $description "display a solid" } ;
242
243HELP: space->GL 
244{ $values { "space" "a space" } }
245{ $description "display a space" } ;
246
247! --------------------------------------------------------------
248! light
249! --------------------------------------------------------------
250
251ARTICLE: "light-page" "Light in ADSODA"
252"explanation of light"
253$nl
254"link to functions"
255;
256
257ARTICLE: { "adsoda" "light" } "ADSODA : lights"
258{ $code """
259! HELP: light position color
260! <light> ( -- tuple ) light new ;
261! light est un vecteur avec 3 variables pour les couleurs\n
262 void Light::Apply(Vector& normal, double &cRed, double &cGreen, double &cBlue)\n
263 { \n
264   // Dot the light direction with the normalized normal of Face.
265   register double intensity = -(normal * (*this));
266   // Face is a backface, from light's perspective
267   if (intensity < 0)
268     return;
269   
270   // Add the intensity componentwise
271   cRed += red * intensity;
272   cGreen += green * intensity;
273   cBlue += blue * intensity;
274   // Clip to unit range
275  if (cRed > 1.0) cRed = 1.0;
276   if (cGreen > 1.0) cGreen = 1.0;
277   if (cBlue > 1.0) cBlue = 1.0;
278""" }
279;
280
281
282
283ARTICLE: { "adsoda" "halfspace" } "ADSODA : halfspace"
284" defined by the concatenation of the normal vector and a constant"  
285 ;
286
287
288
289ARTICLE:  "adsoda-main-page"  "ADSODA : Arbitrary-Dimensional Solid Object Display Algorithm"
290"multidimensional handler :" 
291$nl
292"design a solid using face delimitations. Only works on convex shapes"
293$nl
294{ $emphasis "written in C++ by Greg Ferrar" }
295$nl
296"full explanation on adsoda page at " { $url "http://www.flowerfire.com/ADSODA/" }
297$nl
298"Useful words are describe on the following pages: "
299{ $subsections
300    "face-page"
301    "solid-page"
302    "space-page"
303    "light-page"
304    "3D-rendering-page"
305} ;
306
307ABOUT: "adsoda-main-page"