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