home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / formats / p3d / spec / p3d_desc.txt next >
Text File  |  1994-06-01  |  41KB  |  890 lines
  1.  
  2.  
  3.  
  4.                         P3D DESCRIPTION AND DEFINITIONS
  5.  
  6.  
  7.                                       by
  8.  
  9.                                  Joel Welling
  10.  
  11.                              15 January 1993 18:03
  12.  
  13.  
  14.  
  15. Copyright (C) 1993  Pittsburgh Supercomputing Center, Carnegie Mellon Universit
  16.         Permission is granted to duplicate and distribute this document
  17.       without fee, so long as the above copyright notice is preserved in
  18.                                  all copies.
  19. 1. Introduction
  20.  
  21.   The  Pittsburgh  Supercomputing Center 3D Metafile (P3D) is intended to serve
  22. as a storage format for three dimensional models.  The goal of the  project  is
  23. to  develop  a representation that will be compact, portable, and flexible, and
  24. can be created and examined or modified by a variety of software packages on  a
  25. variety   of   platforms.    Although  P3D  is  extensible  to  allow  all  the
  26. functionality of model languages intended for  photorealistic  rendering  (e.g.
  27. Pixar's  proposed Renderman standard), it is not intended for the production of
  28. photorealistic images, or even to insure that different renderers will  produce
  29. identical  images  from a given P3D model.  Rather, it is designed to provide a
  30. format for the storage and transport of models which can be viewed on a variety
  31. of platforms with a variety of rendering capabilities.
  32.  
  33.   In  order  to provide maximum flexibility, it was decided that P3D would be a
  34. complete programming language.  This allows it to be used in the  same  fashion
  35. as  Postscript,  with the creating application determining the structure of the
  36. metafile based on its internal view of the model.  Lisp provides a well-  known
  37. language  which can be interpreted or compiled and is well-suited to describing
  38. the directed acyclic graphs  (DAGs)  common  in  three  dimensional  modelling.
  39. Hence,  it  was  decided  that  P3D  would be written as a set of extensions to
  40. Common Lisp.
  41.  
  42.   This document makes no attempt to describe Common Lisp itself.   For  details
  43. on  that language, see any of a number of texts, for example "Common Lisp - the
  44. Language" by Guy Steele  Jr.  (Digital  Press  1984).    In  practice,  current
  45. implementations  of  P3D (as of May 1989) run on a subset of Common Lisp called
  46. Alisp.  For details on this lisp, see Chris Nuuja's document on  Alisp.    This
  47. provides  a basis for P3D that can be easily distributed, plus some benefits in
  48. security, at some cost in functionality.
  49.  
  50. 2. Overview
  51.  
  52.   A P3D model consists of graphical objects, called 'gobs' for  short.    These
  53. objects  may be primitives like spheres or triangle lists, or they may be built
  54. up of simpler objects.  The internal structure of a gob may (and probably will)
  55. be  a  directed acyclic graph or DAG, the internal nodes of which are also gobs
  56. and the leaf nodes of which are gobs consisting of geometrical primitives.
  57.  
  58.   P3D supports sphere, cylinder, torus, polygon, polyline, polymarker, triangle
  59. list,  generalized  mesh,  spline surface, and text geometrical primitives.  In
  60. addition, light sources are treated as geometrical primitives and  occupy  leaf
  61. nodes of the DAG.
  62.  
  63.   Gobs  are  defined  either  by involking a function which returns a primitive
  64. gob, or by listing the 'children' and possibly the attributes the new gob is to
  65. have.    A  gob can be saved either by binding it to a name (for example, via a
  66. lisp 'setq' function) or by including it directly into the list of children  of
  67. another  gob.    Color, material type, and backface cullability are examples of
  68. attributes which might be associated with a gob.
  69.  
  70.   P3D also defines primitive structures needed to  support  simple  geometrical
  71. and  graphical  entities like points, vectors, vertices, colors, and materials.
  72. There is a structure used to represent a camera, which can be used  within  the
  73. metafile to define a point of view.  Transformations are represented as four by
  74. four lisp matrices.
  75.  
  76.   Rendering of a given view is triggered by the 'snap'  function,  which  takes
  77. two  gobs  and  a  camera  structure  as  parameters.    One  gob  supplies the
  78. geometrical primitives, while the other supplies the lights; they can  in  fact
  79. both  be  instances  of the same gob.  The camera structure defines the viewing
  80. parameters.  One of two possible actions may be triggered to perform rendering,
  81. depending  on  the  functionality of the underlieing renderer.  If the renderer
  82. cannot support a hierarchical geometry,  the  geometry  DAG  may  be  traversed
  83. within  the  Lisp  itself  so  that  calls  to  the renderer are only made when
  84. geometric primitives are found.  If the renderer will  support  a  hierarchical
  85. geometry  database,  a call to the renderer can be made as each gob is defined,
  86. so that at rendering time  the  DAG  traversal  is  done  entirely  within  the
  87. renderer.
  88.  
  89.   When  the  rendering  process begins, a certain set of default attributes for
  90. the model are assumed.  As  the  DAG  is  traversed,  each  new  gob  may  have
  91. attributes or transformations associated with it.  A gob's attributes are added
  92. to those in effect above it on the DAG, superceeding  the  previous  values  of
  93. attributes of the same type.  Transformations are multiplied together in such a
  94. way that at  any  given  level  a  local  coordinate  system  exists,  and  the
  95. transformation  from  that  coordinate  system  to the coordinate system of the
  96. top-level gob (where rendering began) is the product of all the transformations
  97. in  between.  Thus, for example, any gob can set a color to be inherited by its
  98. children; if no gob farther down the DAG resets the  color  (and  the  vertices
  99. used  have  no  color  of their own) geometrical primitives below that gob will
  100. ultimately  be  drawn  with  the  color  given.    Likewise,  a  transformation
  101. associated  with  any  gob can be used to change the ultimate position at which
  102. the structures below it in the DAG will be drawn.
  103.  
  104.   Any gob may be instanced arbitrarily many times in  the  geometry  DAG;  each
  105. instance  will  inherit  attributes  and transformations independently from its
  106. parents.  Note that the DAG must remain acyclic or severe problems may  result.
  107. It  is  the  programmer's  responsibility  to  make sure that no gob is its own
  108. decendent.
  109.  
  110. 3. Syntax Rules and Special Conventions
  111.  
  112.   The syntax of P3D is exactly that of Lisp.  Each P3D  metafile  should  begin
  113. with the Lisp comment:
  114.  
  115.     ;P3D nnn
  116.  
  117. left  justified  on  the  first  line of the metafile, where nnn is the release
  118. number of the P3D specification to which the metafile  conforms  (for  example,
  119. 2.1).    This serves to identify the metafile as P3D rather than arbitrary lisp
  120. code.
  121.  
  122. 4. Coordinate Conventions and Orientation Rules
  123.  
  124.   P3D assumes that all coordinate systems are right-handed.   For  example,  if
  125. the  x  axis  of  a coordinate system points to the right of a viewer and the y
  126. axis points up, the z axis  will  point  toward  the  viewer.    The  signs  of
  127. rotations  are  also  assumed  positive  in  the  right-handed  direction.  For
  128. example, a positive rotation of 90 degrees about the z axis will move a  vector
  129. initially pointing along the x axis into alignment with the y axis.
  130.  
  131.   Coordinate  transformations  are  represented  by  four  by four matrices, as
  132. follows:
  133.         rotation:
  134.  
  135.                 [ R11 R12 R13 0 ]
  136.                 [ R21 R22 R23 0 ]
  137.                 [ R31 R32 R33 0 ]
  138.                 [  0   0   0  1 ]
  139.  
  140.         translation:
  141.  
  142.                 [  1   0   0  Tx ]
  143.                 [  0   1   0  Ty ]
  144.                 [  0   0   1  Tz ]
  145.                 [  0   0   0  1  ]
  146.  
  147.         scale:
  148.  
  149.                 [ Sx   0   0  0 ]
  150.                 [  0  Sy   0  0 ]
  151.                 [  0   0  Sz  0 ]
  152.                 [  0   0   0  1 ]
  153.  
  154. where R11 through R33 are appropriate rotation components, Tx, Ty, and  Tz  are
  155. translation  components in the x, y, and z directions respectively, and Sx, Sy,
  156. and Sz are scaling factors in the x, y, and z directions  respectively.    With
  157. these  conventions, a point in three dimensional space will be represented by a
  158. column vector, the first three  components  of  which  are  the  x,  y,  and  z
  159. coordinates  of  the  point  and the fourth component of which is always unity.
  160. Transforming that point to a new coordinate system  then  corresponds  to  left
  161. multiplying the column vector by the appropriate transformation matrix.
  162.  
  163.   Note  that it is never necessary to explicitly construct these transformation
  164. matrices.  P3D provides functions that construct  them,  as  described  in  the
  165. section on Geometric Transformations below.
  166.  
  167.   The  'front'  face of a polygon is also determined by a right hand rule.  For
  168. example, the front face of the triangle with vertices ( 0, 0, 0), ( 1,  0,  0),
  169. and  (0,  1, 0) is the face on the z>0 side.  If the vertices of a polygon have
  170. local normals (see below), and those normals are inconsistant with  the  facing
  171. direction  of  the  polygon  as derived from the right hand rule, unpredictable
  172. results may occur on rendering.   Polygon  facing  may  be  used  for  backface
  173. culling.
  174.  
  175.   All  text  is  drawn in a plane, the orientation of which is specified by the
  176. 'u' and 'v' vectors provided in the text primitive.  The front face of the text
  177. is  derived  by  applying the right hand rule to these two vectors.  If the 'u'
  178. vector lies in the x direction and the 'v' vector lies in the y direction,  the
  179. front face of the text will be on the positive z side.
  180.  
  181. 5. Memory Management Rules
  182.  
  183.   The  programmer  need not worry about freeing memory associated with most P3D
  184. structures, as the normal garbage collection mechanisms of Lisp will handle the
  185. task.    This  is  not  always  possible  for  gobs, however, as a gob may have
  186. associated with it data structures in the renderer, and those  data  structures
  187. must  be  freed  when  the  gob  is freed.  Thus, several special functions are
  188. needed to handle the memory management of gobs.
  189.  
  190.   A gob is freed if and only if the following conditions apply.  It  must  have
  191. no parents which have not been freed, it must not be 'held' (see below), and it
  192. or its last surviving parent must be explicitly freed.  Functions to  hold  and
  193. release  a  gob,  and  to  free it, are described in the section on Geometrical
  194. Objects below.  It is important to use these functions when  destroying  a  gob
  195. which  is  no  longer  needed,  so  that  memory  within  the  renderer will be
  196. reclaimed.
  197.  
  198. 6. Primitive Objects
  199.  
  200.  
  201.  
  202. 6.1. Point
  203.  
  204.   The structure used to hold the coordinates of a point in 3-space  is  defined
  205. as follows:
  206.  
  207.     (defstruct point
  208.             (x 0.0)         ;x coordinate
  209.             (y 0.0)         ;y coordinate
  210.             (z 0.0))        ;z coordinate
  211.  
  212.  
  213. It  can  be  created  via the function 'make-point', which can take the options
  214. ':x', ':y', and ':z', all of which are floating  point  numbers  defaulting  to
  215. 0.0.  For example,
  216.  
  217.     (setq origin (make-point))
  218.  
  219. is the definition of the standard symbol 'origin'.
  220.  
  221.  
  222. 6.2. Vector
  223.  
  224.   The structure used to hold a vector in 3-space is defined as follows:
  225.  
  226.     (defstruct vector
  227.             (x 0.0)         ;x coordinate
  228.             (y 0.0)         ;y coordinate
  229.             (z 0.0))        ;z coordinate
  230.  
  231.  
  232. It  can  be  created via the function 'make-vector', which can take the options
  233. ':x', ':y', and ':z', all of which are floating  point  numbers  defaulting  to
  234. 0.0.  For example,
  235.  
  236.     (setq x-vec (make-vector :x 1.0 :y 0.0 :z 0.0))
  237.  
  238. is the definition of the standard symbol 'x-vec'.
  239.  
  240.  
  241. 6.3. Color
  242.  
  243.   The structure used to hold a color is defined as follows:
  244.  
  245.     (defstruct color
  246.             (r 0.8)         ;red intensity
  247.             (g 0.8)         ;green intensity
  248.             (b 0.8)         ;blue intensity
  249.             (a 1.0))        ;opacity
  250.  
  251.  
  252. It  can  be  created  via the function 'make-color', which can take the options
  253. ':r' for red intensity, ':g' for green intensity, ':b' for blue intensity,  and
  254. ':a' for opacity (sometimes called the alpha channel).  All of these values are
  255. assumed to be floating point values in the range 0.0 to 1.0 inclusive, with 0.0
  256. being  no  intensity  in that color or complete transparency.  The defaults are
  257. 0.8 for each of the red, green, and blue values, and 1.0  or  complete  opacity
  258. for the alpha value.  For example,
  259.  
  260.     (setq red (make-color :r 1.0 :g 0.0 :b 0.0))
  261.  
  262. is the definition of the standard symbol 'red'.
  263.  
  264.  
  265.  
  266. 6.4. Vertex
  267.  
  268.   The  structure  used  to  hold  a  vertex (a position in 3 dimensional space,
  269. possibly with an associated color and/or normal vector) is defined as a  struct
  270. containing at least the following fields:
  271.  
  272.     (defstruct vertex
  273.             (x 0.0)         ;x coordinate
  274.             (y 0.0)         ;y coordinate
  275.             (z 0.0)         ;z coordinate
  276.             (clr nil)       ;local color
  277.             (normal nil))   ;local surface normal
  278.  
  279.  
  280. It  can  be  created via the function 'make-vertex', which can take the options
  281. ':x' for x coordinate, ':y' for y coordinate,  ':z'  for  z  coordinate  (these
  282. three   being  floating  point  numbers),  ':clr'  (a  color,  as  returned  by
  283. 'make-color') for  local  color,  and  ':normal'  (a  vector,  as  returned  by
  284. 'make-vector') for local surface normal.  The coordinate values default to 0.0,
  285. so the default location is the origin.  The local color  defaults  to  nil,  so
  286. that  the  vertex  will be drawn with a color inherited from its parents in the
  287. DAG.  The local normal also defaults to  nil;  the  renderer  will  attempt  to
  288. calculate  a  normal  by interpolating the orientations of adjacent polygons if
  289. this is the case.  For example,
  290.  
  291.     (setq red-origin (make-vertex :clr red))
  292.  
  293. will define a vertex located at the origin with a color of  'red'  (as  defined
  294. above) and no normal.
  295.  
  296.  
  297.  
  298. 6.5. Material
  299.  
  300.   The  structure  used  to  hold  a  material  (a  set  of properties used with
  301. attributes like color to determine the appearance of an object) is  represented
  302. as a structure with at least the following fields:
  303.  
  304.         Field             Type                Meaning
  305.  
  306.         :ka              float          ambient light weighting factor
  307.         :kd              float          diffuse light weighting factor
  308.         :ks              float          specular light weighting factor
  309.         :exp             float          specular exponent
  310.         :reflect         float          reflection coefficient
  311.         :refract         float          index of refraction
  312.         :energy          color          energy density (for radiosity)
  313.  
  314. Other structure fields may exist, but they are maintained by P3D and should not
  315. be modified by the programmer.  A material should always be  created  with  the
  316. 'def-material' function.
  317.  
  318.         ( def-material :ka ka-value :kd kd-value :ks ks-value
  319.                   :exp exp-value :reflect reflect-value
  320.                   :refract refract-value :energy energy-color )
  321.  
  322.                 parameters:
  323.                         :ka ka-value (optional): ambient light
  324.                                 weighting factor
  325.                         :kd kd-value (optional): diffuse light
  326.                                 weighting factor
  327.                         :ks ks-value (optional): specular light
  328.                                 weighting factor
  329.                         :exp exp-value (optional): specular exponent
  330.                         :reflect reflect-value (optional):
  331.                                 reflection coefficient
  332.                         :refract refract-value (optional):
  333.                                 index of refraction
  334.                         :energy energy-color (optional): energy
  335.                                 density for radiosity
  336.                 returns:  material with the given characteristics
  337.  
  338.  
  339. All  the  keyword-field pairs are optional.  Fields which are not specified are
  340. assigned specific default  values;  see  the  specification  of  the  'default-
  341. material'  predefined symbol at the end of this document for the default values
  342. of each field.
  343.  
  344.   A material can be used to describe the way light interacts  with  an  object,
  345. and thus its appearance.  For example,
  346.  
  347.     (setq aluminum-material (def-material
  348.                     :ka 0.25 :kd 0.25 :ks 0.75 :exp 6.0 :reflect 0.75))
  349.  
  350. is  the  definition  of the standard material symbol 'aluminum-material'.  This
  351. material is quite reflective, but has a relatively low specular exponent, so it
  352. will appear shiny but not polished.
  353.  
  354.  
  355.  
  356. 6.6. Camera
  357.  
  358.   The structure used to hold a camera is defined as follows:
  359.  
  360.     (defstruct camera
  361.             (lookfrom origin)       ;eye point
  362.             (lookat origin)         ;point to look at
  363.             (up y-vec)              ;view's 'up' direction
  364.             (fovea 56.0)            ;view included angle
  365.             (hither -0.01)          ;hither clipping distance
  366.             (yon -100.0)            ;yon clipping distance
  367.             (background black))     ;background color
  368.  
  369.  
  370. Camera structs are used to define viewing characteristics for rendering.  It is
  371. created via the function 'make-camera', which can take the following options:
  372.  
  373.         Option              Type                Meaning
  374.  
  375.         :lookfrom       point           location of camera
  376.         :lookat         point           location at which camera is to point
  377.         :up             vector          direction from bottom to top of view
  378.         :fovea          float           camera opening angle in degrees
  379.         :hither         float           distance to hither clipping plane
  380.         :yon            float           distance to yon clipping plane
  381.         :background     color           background color
  382.  
  383.  
  384.   Both the lookat and lookfrom points default to the origin, so  at  least  one
  385. must be set to produce a valid camera.  The camera's 'up' direction defaults to
  386. the y direction.  The fovea angle defaults to 56 degrees, and  the  hither  and
  387. yon distances default to -0.01 and -100.0 respectively.  (Note that because the
  388. coordinate system of the camera is required to be right-handed,  the  ':lookat'
  389. point  will  lie in the negative z direction from the origin, so the hither and
  390. yon clipping distances must be negative).  The  background  color  defaults  to
  391. black.
  392.  
  393.   The  following  example  defines a camera at the coordinates (0.0, 0.0, 20.0)
  394. looking at the origin, with all other characteristics left at their defaults.
  395.  
  396.     (setq this-camera (make-camera
  397.                             :lookat origin
  398.                             :lookfrom (make-point :z 20.0)))
  399.  
  400. 7. Geometric Transformations
  401.  
  402.   P3D provides functions to generate transformation matrices, as  described  in
  403. the Coordinate Conventions section above.  The functions are:
  404.  
  405.         ( make-translate Tx Ty Tz )
  406.  
  407.                 parameters:
  408.                         Tx, Ty, Tz:  floating point numbers giving distance
  409.                                 to translate in the x, y, and z directions
  410.                                 respectively.
  411.                 returns:
  412.                         a transformation matrix encoding the translation
  413.  
  414.         ( make-rotate axis angle )
  415.  
  416.                 parameters:
  417.                         axis:  vector providing the axis about which to rotate
  418.                         angle:  angle in degrees of the rotation
  419.                 returns:
  420.                         a transformation matrix encoding the rotation
  421.  
  422.         ( make-scale Sx Sy Sz )
  423.  
  424.                 parameters:
  425.                         Sx, Sy, Sz:  floating point numbers giving factors by
  426.                                 which to scale the x, y, and z directions
  427.                                 respectively
  428.  
  429.                 returns:
  430.                         a transformation matrix encoding the scaling
  431.  
  432.         ( make-identity )
  433.  
  434.                 parameters: none
  435.  
  436.                 returns: a transformation matrix encoding the identity
  437.                         transformation
  438.  
  439.         ( compose-transform trans1 trans2 )
  440.  
  441.                 parameters:
  442.                         trans1, trans2: transformation matrices
  443.  
  444.                 returns:  trans1 x trans2  (remember that subsequent
  445.                         transformations should left multiply existing
  446.                         transformations)
  447.  
  448.         ( compose-transforms trans1 trans2 trans3 ... transn )
  449.  
  450.                 parameters:
  451.                         trans1 ... transn: transformation matrices
  452.  
  453.                 returns:  trans1 x trans2 x ... x transn (remember that
  454.                         subsequent transformations should left multiply
  455.                         existing transformations).  compose-transforms
  456.                         is somewhat slower than compose-transform.
  457.  
  458. 8. Geometrical Object (Gob)
  459.  
  460.   A gob is represented as a structure with at least the following options:
  461.  
  462.         Option              Type                Meaning
  463.  
  464.         :attr           assoc-list      attribute-value pairs for this gob
  465.         :transform      transformation  coordinate transformation
  466.         :children       list            list of gobs to be children
  467.  
  468. Other  structure slots may exist, but they are maintained by P3D and should not
  469. be modified by the programmer.  All of the fields default to nil.
  470.  
  471.   A gob should always be created with 'def-gob', or with one of the geometrical
  472. primitive  generators  (see below). If 'def-gob' is used, the definition should
  473. include a ':children' option or the gob will have no decendents in the DAG  and
  474. thus be useless.
  475.  
  476.         ( def-gob :attr attrlist
  477.                   :transform transformation
  478.                   :children childlist )
  479.  
  480.                 parameters:
  481.                         :children childlist (required):  list of
  482.                                 children of this gob
  483.                         :transform transformation (optional):  coordinate
  484.                                 transformation for this gob
  485.                         :attr attrlist (optional):  association list of
  486.                                 attribute and value pairs for this gob
  487.                 returns:  gob with the given children, coordinate
  488.                         transformation, and attributes
  489.  
  490.  
  491.   If  old_gob_1  and  old_gob_2 are previously created gobs, the following will
  492. create a gob called new_gob which includes a coordinate transformation, and has
  493. the two other gobs as children.
  494.  
  495.     (setq new_gob (def-gob  :transform (make-translate 1.0 0.0 0.0)
  496.                             :children (list old-gob-1 old-gob 2)))
  497.  
  498.   As  described  in the Memory Management section above, a gob can be 'held' to
  499. guarantee that it will not be freed, and 'unheld' to permit reclaimation of its
  500. memory.  The 'hold-gob' and 'unhold-gob' functions have the following syntax:
  501.  
  502.         ( hold-gob gob )
  503.  
  504.                 parameters:
  505.                         gob:  gob to be held
  506.  
  507.                 returns: T
  508.  
  509.         ( unhold-gob gob )
  510.  
  511.                 parameters:
  512.                         gob:  gob to be released
  513.  
  514.                 returns: Nil
  515.  
  516.  
  517. Applying  'hold-gob'  to a gob which is already held is a null operation, as is
  518. applying 'unhold-gob' to a gob which is not held.
  519.  
  520.   A gob which is  not  held  and  which  has  no  parents  can  be  freed  with
  521. 'free-gob'.    This  function  causes  memory  associated  with  the gob in the
  522. renderer to be freed; any future reference to the gob will be an  error.    The
  523. children  of  the  freed  gob are checked to see if they have any other parents
  524. (which have not themselves been freed); an orphaned child which is  not  itself
  525. held is also freed.  The syntax of free-gob is as follows:
  526.  
  527.         ( free-gob gob )
  528.  
  529.                 parameters:
  530.                         gob:  gob to be freed.
  531.  
  532.                 returns: Nil.
  533.  
  534. 9. Attributes
  535.  
  536.   Attributes  are  data other than geometrical data which is used in rendering.
  537. Each gob can have associated with it a list of attribute-value pairs; this list
  538. is  stored  in  the  gob's  ':attr'  slot.    Attributes are inherited down the
  539. geometry DAG, in such a way that a value for a given attribute on a  gob  which
  540. is a close parent of a geometrical primitive (see below) will supersede a value
  541. assigned that attribute farther up the DAG.
  542.  
  543.   A gob's attributes are stored in an association list, of the sort searched by
  544. the Common Lisp 'assoc' function.  Association lists are of the form:
  545.  
  546.     ( (attr1 . val1) (attr2 . val2) (attr3 . val3) ... )
  547.  
  548. The following attributes are currently supported by P3D:
  549.  
  550.     Attribute     Value       Default           Meaning
  551.  
  552.     'color        color       opaque white      default color below this gob
  553.  
  554.     'backcull     T or nil    nil               enable backface culling
  555.  
  556.     'text-height  float       1.0               character height for capital
  557.                                                 X character
  558.  
  559.     'text-font    string     "simplex_roman"    font in which text will
  560.                                                 be written
  561.     'text-stroke-width-fraction
  562.                   float      0.15               strokes with which text is
  563.                                                 drawn will be this
  564.                                                 fraction of text-height
  565.  
  566.     'text-thickness-fraction
  567.                   float      0.1                if the text has thickness
  568.                                                 (perpendicular to u and v),
  569.                                                 it will be this fraction
  570.                                                 of text-height
  571.  
  572.     'material     material   default-material   material type for this gob
  573.                                                 and its children
  574. Any given renderer may ignore some of these attributes.
  575.  
  576.   Because  the  DAG  traversal process may reverse the order of attribute-value
  577. pairs within a gob, the attribute list for a given gob  should  have  only  one
  578. occurance of a given attribute.
  579.  
  580.   The  following example creates a gob with an attribute list setting a default
  581. color of blue and enabling backface culling:
  582.  
  583.     (setq sample_gob (def-gob
  584.                     :attr (list (cons 'color blue)
  585.                                '(backcull . T))
  586.                     :children (list old_gob_1 old_gob_2)))
  587.  
  588. 10. Geometrical Primitives
  589.  
  590.   P3D defines a number of functions which return  geometrical  primitive  gobs.
  591. These  gobs  are leaf nodes in the rendering DAG; they have no children.  These
  592. primitives are rendered with  the  attributes  inherited  from  their  parents,
  593. except in those cases where the vertices of the primitive specify the attribute
  594. explicitly (e.g. color).  The funcions which generate primitives are:
  595.  
  596.         ( sphere )
  597.  
  598.                 parameters:  none
  599.  
  600.                 returns:  gob containing a sphere of radius 1, centered at
  601.                         the origin
  602.  
  603.         ( cylinder )
  604.  
  605.                 parameters: none
  606.  
  607.                 returns:  gob containing a cylinder of radius 1, with the
  608.                         symmetry axis aligned with the z axis.  The cylinder
  609.                         ends are at z= 0.0 and z= 1.0 .
  610.  
  611.         ( torus bigradius smallradius )
  612.  
  613.                 parameters:
  614.                         bigradius:  float specifying major radius of torus
  615.                         smallradius:  float specifying minor radius of torus
  616.  
  617.                 returns:  gob containing a torus with the given major and
  618.                         minor radii, with the hole in the torus running
  619.                         along the z axis.
  620.  
  621.         ( polyline v1 v2 v3 ... vn )
  622.  
  623.                 parameters:
  624.                         v1 ... vn:  vertices to be connected by the polyline.
  625.                         There must be at least two vertices.
  626.  
  627.                 returns:  gob containing a polyline connecting the given
  628.                         vertices.  The polyline is not closed; i.e. vn is
  629.                         not connected to v1.
  630.  
  631.         ( polymarker v1 v2 v3 ... vn )
  632.  
  633.                 parameters:
  634.                         v1 ... vn:  vertices at which markers are to be
  635.                         drawn.  There must be at least one vertex.
  636.  
  637.                 returns:  gob containing a polymarker, the markers of which
  638.                         are at the given vertices.  The markers are of the
  639.                         current marker type.  Depending on the renderer,
  640.                         the marker drawn may or may not be subject to
  641.                         geometric transformations.  For example, a marker
  642.                         might be of constant size, or might scale with
  643.                         the projection of the model.
  644.  
  645.         ( polygon v1 v2 v3 ... vn )
  646.  
  647.                 parameters:
  648.                         v1 ... vn:  vertices to form the perimiter of the
  649.                         polygon.  There must be at least three vertices.
  650.  
  651.                 returns:  gob containing a polygon with the given vertices.
  652.                         The polygon is closed automatically; i.e. v1 need not
  653.                         equal vn.
  654.  
  655.                 comments:  The appearance of non-planar polygons may vary
  656.                         from renderer to renderer.
  657.  
  658.         ( triangle v1 v2 v3 ... vn )
  659.  
  660.                 parameters:
  661.                         v1 ... vn:  vertices to be used to form the triangle
  662.                         strip.
  663.  
  664.                 returns:  gob containing a triangle strip composed of the given
  665.                         vertices.  The strip is a series of triangles, each
  666.                         defined by an adjacent set of three vertices from the
  667.                         vertex list.  Thus, the first triangle is composed
  668.                         of v1, v2, and v3; the second of v2, v3, and v4; and
  669.                         so on.  The 'front' face of a triangle strip is
  670.                         determined by the right hand rule for odd numbered
  671.                         triangles, and a left hand rule for even numbered
  672.                         triangles.
  673.  
  674.         ( mesh vlist flist )
  675.  
  676.                 parameters:
  677.                         vlist: list of vertices included in the mesh
  678.                         flist: list of lists of vertices, one list per
  679.                         polygonal facet.
  680.  
  681.                 returns:  gob containing a generalized mesh composed of the
  682.                         given facets, which are polygons the corners of which
  683.                         are in the given list of vertices.
  684.  
  685.                 comments:  The vertices in the facet lists should be the same
  686.                         vertices as those in the vertex list, not simply
  687.                         different vertices at the same coordinate location.
  688.                         For example, if v1, v2, v3, and v4 are vertices, the
  689.                         following is a valid mesh:
  690.  
  691.                         (mesh (list v1 v2 v3 v4)
  692.                                 (list (list v1 v2 v3) (list v2 v3 v4) ) )
  693.  
  694.         ( bezier v1 v2 v3 ... v16 )
  695.  
  696.                 parameters:
  697.                         v1 to v16: The control vertices of a 4 by 4 bicubic
  698.                         Bezier patch.
  699.  
  700.                 returns:  gob containing a 4 by 4 bicubic Bezier patch,
  701.                         defined by the control vertices as follows:
  702.  
  703.                         *-------*--------*--------*
  704.                         |v1     |v2      |v3      |v4
  705.                         |       |        |        |
  706.                         |       |        |        |
  707.                         *-------*--------*--------*
  708.                         |v5     |v6      |v7      |v8
  709.                         |       |        |        |
  710.                         |       |        |        |
  711.                         *-------*--------*--------*
  712.                         |v9     |v10     |v11     |v12
  713.                         |       |        |        |
  714.                         |       |        |        |
  715.                         *-------*--------*--------*
  716.                          v13     v14      v15      v16
  717.  
  718.                         The 'up' surface of the patch is defined by the
  719.                         right hand rule circulating in the v1-v4-v16-v13
  720.                         order, so that the above illustration's 'up'
  721.                         direction is into the page.
  722.  
  723.                 comments:  The patch passes through the corner vertices;
  724.                         the other vertices define the shape of the spline
  725.                         surface.  The treatment of color and normal
  726.                         information associated with the vertices is
  727.                         renderer dependent.
  728.  
  729.         ( text point uvec vvec string )
  730.  
  731.                 parameters:
  732.                         point:  point in 3D space at which the text is to
  733.                         be written.
  734.                         uvec: vector in 3D space specifying the u axis
  735.                         of the plane in which the text is to be drawn
  736.                         vvec: vector in 3D space specifying the v axis
  737.                         of the plane in which the text is to be drawn
  738.                         string:  character string to be written.
  739.  
  740.                 returns:  gob containing a written character string.  The
  741.                         writing plane and other attributes are determined
  742.                         by the inherited values of the appropriate 'text-'
  743.                         attributes.  The text is drawn starting at the given
  744.                         point, in a plane the orientation of which is given
  745.                         by the u and v vectors.
  746.  
  747. 11. Lights
  748.  
  749.   P3D provides two function which return light sources.   These  light  sources
  750. are  gobs  which  serves as a leaf node of a DAG; they have no children.  Light
  751. sources can provide directional illumination, or can provide ambient background
  752. light  which illuminates all surfaces regardless of orientation.  The functions
  753. which produce these lights are:
  754.  
  755.         ( light location lightcolor )
  756.  
  757.                 parameters:
  758.                         location:  point in 3D space at which to place the
  759.                         light source.  (Note that some renderers will retreat
  760.                         the light to infinity along the line from the origin
  761.                         of the current coordinate system through the given
  762.                         point).
  763.                         lightcolor:  color of the light to be emitted from
  764.                         this source.
  765.  
  766.                 returns:  gob containing a directional light source specified
  767.                         by the given parameters.
  768.  
  769.         ( ambient lightcolor )
  770.  
  771.                 parameters:
  772.                         lightcolor:  color of the light to be emitted from
  773.                         this source.
  774.  
  775.                 returns:  gob containing an ambient light source of the given
  776.                         color.
  777.  
  778.  
  779. For example, the following defines a white light source at the coordinates  (1,
  780. 0, 0) and binds it to the symbol 'new_light'.
  781.  
  782.     (setq new_light (light (make-point :x 1.0 )
  783.                            (make-color :r 1.0 :g 1.0 :b 1.0)))
  784.  
  785. 12. Rendering
  786.  
  787.   Once  a geometry DAG and a DAG containing light sources has been constructed,
  788. and a camera structure has been defined, the P3D 'snap' function can be used to
  789. initiate  rendering.    (It  is  possible  for  a  single  dag  containing both
  790. geometrical primitives and light sources to be used for both the  lighting  and
  791. geometry DAGs).  The snap function has the following format:
  792.  
  793.         ( snap object lights acamera )
  794.  
  795.                 parameters:
  796.                         object:  gob containing the model to be rendered
  797.                         lights:  gob containing light sources
  798.                         acamera:  camera struct defining the field of view
  799.  
  800.                 returns: 'T
  801.  
  802.  
  803. The  exact  action  of  'snap'  will  depend  on  the renderer being used.  For
  804. example, a slow renderer might render the single given frame, while  a  dynamic
  805. renderer might render the object continuously, allowing the point of view to be
  806. changed via a knob box, until control was returned to the P3D interpreter.
  807.  
  808. 13. Predefined Symbols
  809.  
  810.   P3D predefines some symbols for commonly used  constructs  for  convenience's
  811. sake.  The predefined symbols include the following:
  812.   Symbol             Meaning               Definition
  813.  
  814.   origin             point at origin       (make-point :x 0.0 :y 0.0 :z 0.0)
  815.  
  816.   x-vec              x unit vector         (make-vector :x 1.0)
  817.  
  818.   y-vec              y unit vector         (make-vector :y 1.0)
  819.  
  820.   z-vec              z unit vector         (make-vector :z 1.0)
  821.  
  822.   white              color white           (make-color :r 1.0 :g 1.0 :b 1.0)
  823.  
  824.   black              color black           (make-color :r 0.0 :g 0.0 :b 0.0)
  825.  
  826.   red                color red             (make-color :r 1.0 :g 0.0 :b 0.0)
  827.  
  828.   green              color green           (make-color :r 0.0 :g 1.0 :b 0.0)
  829.  
  830.   blue               color blue            (make-color :r 0.0 :g 0.0 :b 1.0)
  831.  
  832.   yellow             color yellow          (make-color :r 0.0 :g 1.0 :b 1.0)
  833.  
  834.   cyan               color cyan            (make-color :r 1.0 :g 0.0 :b 1.0)
  835.  
  836.   magenta            color magenta         (make-color :r 1.0 :g 1.0 :b 0.0)
  837.  
  838.   null-transform     identity transform    (make-identity)
  839.  
  840.   default-material   default material      (def-material :ka 0.8 :kd 0.8
  841.                                                 :ks 0.3 :exp 30.0
  842.                                                 :reflect 0.1 :refract 1.0
  843.                                                 :energy black)
  844.  
  845.   dull-material      material type with    (def-material :ka 0.9 :kd 0.9
  846.                      low reflectivity           :ks 0.1 :exp 5.0
  847.                                                 :reflect 0.1 :refract 1.0
  848.                                                 :energy black)
  849.  
  850.   shiny-material     glossy material       (def-material :ka 0.5 :kd 0.5
  851.                      type                       :ks 0.5 :exp 50.0
  852.                                                 :reflect 0.3 :refract 1.0
  853.                                                 :energy black)
  854.  
  855.   metallic-material  metallic material     (def-material :ka 0.1 :kd 0.1
  856.                      type, like chrome          :ks 0.9 :exp 100.0
  857.                                                 :reflect 0.7 :refract 1.0
  858.                                                 :energy black)
  859.  
  860.   matte-material     material type with    (def-material :ka 1.0 :kd 1.0
  861.                      no reflectivity            :ks 0.0 :exp 0.0
  862.                                                 :reflect 0.0 :refract 1.0
  863.                                                 :energy black)
  864.  
  865.   aluminum-material  aluminum              (def-material :ka 0.25 :kd 0.25
  866.                                                 :ks 0.75 :exp 6.0
  867.                                                 :reflect 0.75 :refract 1.0
  868.                                                 :energy black)
  869.                                Table of Contents
  870.    1. Introduction                                                            1
  871.    2. Overview                                                                1
  872.    3. Syntax Rules and Special Conventions                                    1
  873.    4. Coordinate Conventions and Orientation Rules                            1
  874.    5. Memory Management Rules                                                 1
  875.    6. Primitive Objects                                                       1
  876.        6.1. Point                                                             1
  877.        6.2. Vector                                                            2
  878.        6.3. Color                                                             2
  879.        6.4. Vertex                                                            2
  880.        6.5. Material                                                          2
  881.        6.6. Camera                                                            2
  882.    7. Geometric Transformations                                               2
  883.    8. Geometrical Object (Gob)                                                3
  884.    9. Attributes                                                              3
  885.    10. Geometrical Primitives                                                 3
  886.    11. Lights                                                                 4
  887.    12. Rendering                                                              4
  888.    13. Predefined Symbols                                                     4
  889.  
  890.