factor/unmaintained/adsoda/adsoda-docs.factor

! Copyright (C) 2008 Jeff Bigot
! See http://factorcode.org/license.txt for BSD license.
USING: help.markup help.syntax ;
IN: adsoda

! --------------------------------------------------------------
! faces
! --------------------------------------------------------------
ARTICLE: "face-page" "Face in ADSODA"
"explanation of faces"
$nl
"link to functions" $nl
"what is an halfspace" $nl
"halfspace touching-corners adjacent-faces" $nl
"touching-corners list of pointers to the corners which touch this face" $nl
"adjacent-faces list of pointers to the faces which touch this face"
{ $subsections
    face
    <face>
}
"test relative position"
{ $subsections
    point-inside-or-on-face?
    point-inside-face?
}
"handling face"
{ $subsections
    flip-face
    face-translate
    face-transform
}

;

HELP: face
{ $class-description "a face is defined by"
{ $list "halfspace equation" }
{ $list "list of touching corners" }
{ $list "list of adjacent faces" }
$nl
"Touching corners and adjacent faces are defined by algorithm thanks to other faces of the solid"
}


;
HELP: <face> 
{ $values { "v" "an halfspace equation" } { "tuple" "a face" }  }   ;
HELP: flip-face 
{ $values { "face" "a face" } { "face" "flipped face" } }
{ $description "change the orientation of a face" }
;

HELP: face-translate 
{ $values { "face" "a face" } { "v" "a vector" } }
{ $description 
"translate a face following a vector"
$nl
"a translation of an halfspace doesn't change the normal vector. this word just compute the new constant term" }

 
 ;
HELP: face-transform 
{ $values { "face" "a face" } { "m" "a transformation matrix" } }
{ $description  "compute the transformation of a face using a transformation matrix" }
 
 ;
! --------------------------------
! solid
! --------------------------------------------------------------
ARTICLE: "solid-page" "Solid in ADSODA"
"explanation of solids"
$nl
"link to functions"
{ $subsections
    solid
    <solid>
}
"test relative position"
{ $subsections
    point-inside-solid?
    point-inside-or-on-solid?
}
"playing with faces and solids"
{ $subsections
    add-face
    cut-solid
    slice-solid
}
"solid handling"
{ $subsections
    solid-project
    solid-translate
    solid-transform
    subtract
    get-silhouette 
    solid=
}
;

HELP: solid 
{ $class-description "dimension" $nl "silhouettes" $nl "faces" $nl "corners" $nl "adjacencies-valid" $nl "color" $nl "name" 
}
;

HELP: add-face 
{ $values { "solid" "a solid" } { "face" "a face" } }
{ $description "reshape a solid with a face. The face truncate the solid." } ;

HELP: cut-solid
{ $values { "solid" "a solid" } { "halfspace" "an halfspace" } }
{ $description "like add-face but just with halfspace equation" } ;

HELP: slice-solid
{ $values { "solid" "a solid" } { "face" "a face" } { "solid1" "the outer part of the former solid" } { "solid2" "the inner part of the former solid" } }
{ $description "cut a solid into two parts. The face acts like a knife"
}  ;


HELP: solid-project
{ $values { "lights" "lights" } { "ambient" "ambient" } { "solid" "solid" } { "solids" "projection of solid" } }
{ $description "Project the solid using pv vector" 
$nl
"TODO: explain how to use lights"
} ;

HELP: solid-translate 
{ $values { "solid" "a solid" } { "v" "translating vector" } }
{ $description "Translate a solid using a vector" 
$nl
"v and solid must have the same dimension "
} ;

HELP: solid-transform 
{ $values { "solid" "a solid" } { "m" "transformation matrix" } }
{ $description "Transform a solid using a matrix"
$nl
"v and solid must have the same dimension "
} ;

HELP: subtract 
{ $values { "solid1" "initial shape" } { "solid2" "shape to remove" } { "solids" "resulting shape" } }
{ $description  "Substract solid2 from solid1" } ;


! --------------------------------------------------------------
! space 
! --------------------------------------------------------------
ARTICLE: "space-page" "Space in ADSODA"
"A space is a collection of solids and lights."
$nl
"link to functions"
$nl
"Defining words"
{ $subsections
    space
    <space>
    suffix-solids 
    suffix-lights
    clear-space-solids 
    describe-space
}


"Handling space"
{ $subsections
    space-ensure-solids
    eliminate-empty-solids
    space-transform
    space-translate
    remove-hidden-solids
    space-project
}


;

HELP: space 
{ $class-description 
"dimension" $nl " solids" $nl " ambient-color" $nl "lights" 
}
;

HELP: suffix-solids 
"( space solid -- space )"
{ $values { "space" "a space" } { "solid" "a solid to add" } }
{ $description "Add solid to space definition" } ;

HELP: suffix-lights 
"( space light -- space ) "
{ $values { "space" "a space" } { "light" "a light to add" } }
{ $description "Add a light to space definition" } ;

HELP: clear-space-solids 
"( space -- space )"   
{ $values { "space" "a space" } }
{ $description "remove all solids in space" } ;

HELP: space-ensure-solids 
{ $values { "space" "a space" } }
{ $description "rebuild corners of all solids in space" } ;



HELP: space-transform 
{ $values { "space" "a space" } { "m" "a matrix" } }
{ $description "Transform a space using a matrix" } ;

HELP: space-translate 
{ $values { "space" "a space" } { "v" "a vector" } }
{ $description "Translate a space following a vector" } ;

HELP: describe-space
{ $values { "space" "a space" } }
{ $description "return a description of space" } ;

HELP: space-project 
{ $values { "space" "a space" } { "i" "an integer" } }
{ $description "Project a space along ith coordinate" } ;

! --------------------------------------------------------------
! 3D rendering
! --------------------------------------------------------------
ARTICLE: "3D-rendering-page" "The 3D rendering in ADSODA"
"explanation of 3D rendering"
$nl
"link to functions"
{ $subsections
    face->GL
    solid->GL
    space->GL
}

;

HELP: face->GL 
{ $values { "face" "a face" } { "color" "3 3 values array" } }
{ $description "display a face" } ;

HELP: solid->GL 
{ $values { "solid" "a solid" } }
{ $description "display a solid" } ;

HELP: space->GL 
{ $values { "space" "a space" } }
{ $description "display a space" } ;

! --------------------------------------------------------------
! light
! --------------------------------------------------------------

ARTICLE: "light-page" "Light in ADSODA"
"explanation of light"
$nl
"link to functions"
;

ARTICLE: { "adsoda" "light" } "ADSODA : lights"
{ $code """
! HELP: light position color
! <light> ( -- tuple ) light new ;
! light est un vecteur avec 3 variables pour les couleurs\n
 void Light::Apply(Vector& normal, double &cRed, double &cGreen, double &cBlue)\n
 { \n
   // Dot the light direction with the normalized normal of Face.
   register double intensity = -(normal * (*this));
   // Face is a backface, from light's perspective
   if (intensity < 0)
     return;
   
   // Add the intensity componentwise
   cRed += red * intensity;
   cGreen += green * intensity;
   cBlue += blue * intensity;
   // Clip to unit range
  if (cRed > 1.0) cRed = 1.0;
   if (cGreen > 1.0) cGreen = 1.0;
   if (cBlue > 1.0) cBlue = 1.0;
""" }
;



ARTICLE: { "adsoda" "halfspace" } "ADSODA : halfspace"
" defined by the concatenation of the normal vector and a constant"  
 ;



ARTICLE:  "adsoda-main-page"  "ADSODA : Arbitrary-Dimensional Solid Object Display Algorithm"
"multidimensional handler :" 
$nl
"design a solid using face delimitations. Only works on convex shapes"
$nl
{ $emphasis "written in C++ by Greg Ferrar" }
$nl
"full explanation on adsoda page at " { $url "http://www.flowerfire.com/ADSODA/" }
$nl
"Useful words are describe on the following pages: "
{ $subsections
    "face-page"
    "solid-page"
    "space-page"
    "light-page"
    "3D-rendering-page"
} ;

ABOUT: "adsoda-main-page"