adsoda/adsoda-docs.factor

   1 ! Copyright (C) 2008 Jeff Bigot
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax ;
   4 IN: adsoda
   5
   6 ! --------------------------------------------------------------
   7 ! faces
   8 ! --------------------------------------------------------------
   9 ARTICLE: "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
  35 HELP: 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 ;
  46 HELP: <face>
  47 { $values { "v" "an halfspace equation" } { "tuple" "a face" }  }   ;
  48 HELP: flip-face
  49 { $values { "face" "a face" } { "face" "flipped face" } }
  50 { $description "change the orientation of a face" }
  51 ;
  52
  53 HELP: 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  ;
  62 HELP: 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 ! --------------------------------------------------------------
  70 ARTICLE: "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
 100 HELP: solid
 101 { $class-description "dimension" $nl "silhouettes" $nl "faces" $nl "corners" $nl "adjacencies-valid" $nl "color" $nl "name"
 102 }
 103 ;
 104
 105 HELP: add-face
 106 { $values { "solid" "a solid" } { "face" "a face" } }
 107 { $description "reshape a solid with a face. The face truncate the solid." } ;
 108
 109 HELP: cut-solid
 110 { $values { "solid" "a solid" } { "halfspace" "an halfspace" } }
 111 { $description "like add-face but just with halfspace equation" } ;
 112
 113 HELP: 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
 119 HELP: 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
 126 HELP: 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
 133 HELP: 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
 140 HELP: 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 ! --------------------------------------------------------------
 148 ARTICLE: "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
 177 HELP: space
 178 { $class-description
 179 "dimension" $nl " solids" $nl " ambient-color" $nl "lights"
 180 }
 181 ;
 182
 183 HELP: suffix-solids
 184 "( space solid -- space )"
 185 { $values { "space" "a space" } { "solid" "a solid to add" } }
 186 { $description "Add solid to space definition" } ;
 187
 188 HELP: 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
 193 HELP: clear-space-solids
 194 "( space -- space )"
 195 { $values { "space" "a space" } }
 196 { $description "remove all solids in space" } ;
 197
 198 HELP: space-ensure-solids
 199 { $values { "space" "a space" } }
 200 { $description "rebuild corners of all solids in space" } ;
 201
 202
 203
 204 HELP: space-transform
 205 { $values { "space" "a space" } { "m" "a matrix" } }
 206 { $description "Transform a space using a matrix" } ;
 207
 208 HELP: space-translate
 209 { $values { "space" "a space" } { "v" "a vector" } }
 210 { $description "Translate a space following a vector" } ;
 211
 212 HELP: describe-space
 213 { $values { "space" "a space" } }
 214 { $description "return a description of space" } ;
 215
 216 HELP: space-project
 217 { $values { "space" "a space" } { "i" "an integer" } }
 218 { $description "Project a space along ith coordinate" } ;
 219
 220 ! --------------------------------------------------------------
 221 ! 3D rendering
 222 ! --------------------------------------------------------------
 223 ARTICLE: "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
 235 HELP: face->GL
 236 { $values { "face" "a face" } { "color" "3 3 values array" } }
 237 { $description "display a face" } ;
 238
 239 HELP: solid->GL
 240 { $values { "solid" "a solid" } }
 241 { $description "display a solid" } ;
 242
 243 HELP: space->GL
 244 { $values { "space" "a space" } }
 245 { $description "display a space" } ;
 246
 247 ! --------------------------------------------------------------
 248 ! light
 249 ! --------------------------------------------------------------
 250
 251 ARTICLE: "light-page" "Light in ADSODA"
 252 "explanation of light"
 253 $nl
 254 "link to functions"
 255 ;
 256
 257 ARTICLE: { "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
 283 ARTICLE: { "adsoda" "halfspace" } "ADSODA : halfspace"
 284 " defined by the concatenation of the normal vector and a constant"
 285  ;
 286
 287
 288
 289 ARTICLE:  "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
 307 ABOUT: "adsoda-main-page"