unmaintained/adsoda/adsoda-docs.factor

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