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