P3D DESCRIPTION AND DEFINITIONS by Joel Welling 15 January 1993 18:03 Copyright (C) 1993 Pittsburgh Supercomputing Center, Carnegie Mellon Universit Permission is granted to duplicate and distribute this document without fee, so long as the above copyright notice is preserved in all copies. 1. Introduction The Pittsburgh Supercomputing Center 3D Metafile (P3D) is intended to serve as a storage format for three dimensional models. The goal of the project is to develop a representation that will be compact, portable, and flexible, and can be created and examined or modified by a variety of software packages on a variety of platforms. Although P3D is extensible to allow all the functionality of model languages intended for photorealistic rendering (e.g. Pixar's proposed Renderman standard), it is not intended for the production of photorealistic images, or even to insure that different renderers will produce identical images from a given P3D model. Rather, it is designed to provide a format for the storage and transport of models which can be viewed on a variety of platforms with a variety of rendering capabilities. In order to provide maximum flexibility, it was decided that P3D would be a complete programming language. This allows it to be used in the same fashion as Postscript, with the creating application determining the structure of the metafile based on its internal view of the model. Lisp provides a well- known language which can be interpreted or compiled and is well-suited to describing the directed acyclic graphs (DAGs) common in three dimensional modelling. Hence, it was decided that P3D would be written as a set of extensions to Common Lisp. This document makes no attempt to describe Common Lisp itself. For details on that language, see any of a number of texts, for example "Common Lisp - the Language" by Guy Steele Jr. (Digital Press 1984). In practice, current implementations of P3D (as of May 1989) run on a subset of Common Lisp called Alisp. For details on this lisp, see Chris Nuuja's document on Alisp. This provides a basis for P3D that can be easily distributed, plus some benefits in security, at some cost in functionality. 2. Overview A P3D model consists of graphical objects, called 'gobs' for short. These objects may be primitives like spheres or triangle lists, or they may be built up of simpler objects. The internal structure of a gob may (and probably will) be a directed acyclic graph or DAG, the internal nodes of which are also gobs and the leaf nodes of which are gobs consisting of geometrical primitives. P3D supports sphere, cylinder, torus, polygon, polyline, polymarker, triangle list, generalized mesh, spline surface, and text geometrical primitives. In addition, light sources are treated as geometrical primitives and occupy leaf nodes of the DAG. Gobs are defined either by involking a function which returns a primitive gob, or by listing the 'children' and possibly the attributes the new gob is to have. A gob can be saved either by binding it to a name (for example, via a lisp 'setq' function) or by including it directly into the list of children of another gob. Color, material type, and backface cullability are examples of attributes which might be associated with a gob. P3D also defines primitive structures needed to support simple geometrical and graphical entities like points, vectors, vertices, colors, and materials. There is a structure used to represent a camera, which can be used within the metafile to define a point of view. Transformations are represented as four by four lisp matrices. Rendering of a given view is triggered by the 'snap' function, which takes two gobs and a camera structure as parameters. One gob supplies the geometrical primitives, while the other supplies the lights; they can in fact both be instances of the same gob. The camera structure defines the viewing parameters. One of two possible actions may be triggered to perform rendering, depending on the functionality of the underlieing renderer. If the renderer cannot support a hierarchical geometry, the geometry DAG may be traversed within the Lisp itself so that calls to the renderer are only made when geometric primitives are found. If the renderer will support a hierarchical geometry database, a call to the renderer can be made as each gob is defined, so that at rendering time the DAG traversal is done entirely within the renderer. When the rendering process begins, a certain set of default attributes for the model are assumed. As the DAG is traversed, each new gob may have attributes or transformations associated with it. A gob's attributes are added to those in effect above it on the DAG, superceeding the previous values of attributes of the same type. Transformations are multiplied together in such a way that at any given level a local coordinate system exists, and the transformation from that coordinate system to the coordinate system of the top-level gob (where rendering began) is the product of all the transformations in between. Thus, for example, any gob can set a color to be inherited by its children; if no gob farther down the DAG resets the color (and the vertices used have no color of their own) geometrical primitives below that gob will ultimately be drawn with the color given. Likewise, a transformation associated with any gob can be used to change the ultimate position at which the structures below it in the DAG will be drawn. Any gob may be instanced arbitrarily many times in the geometry DAG; each instance will inherit attributes and transformations independently from its parents. Note that the DAG must remain acyclic or severe problems may result. It is the programmer's responsibility to make sure that no gob is its own decendent. 3. Syntax Rules and Special Conventions The syntax of P3D is exactly that of Lisp. Each P3D metafile should begin with the Lisp comment: ;P3D nnn left justified on the first line of the metafile, where nnn is the release number of the P3D specification to which the metafile conforms (for example, 2.1). This serves to identify the metafile as P3D rather than arbitrary lisp code. 4. Coordinate Conventions and Orientation Rules P3D assumes that all coordinate systems are right-handed. For example, if the x axis of a coordinate system points to the right of a viewer and the y axis points up, the z axis will point toward the viewer. The signs of rotations are also assumed positive in the right-handed direction. For example, a positive rotation of 90 degrees about the z axis will move a vector initially pointing along the x axis into alignment with the y axis. Coordinate transformations are represented by four by four matrices, as follows: rotation: [ R11 R12 R13 0 ] [ R21 R22 R23 0 ] [ R31 R32 R33 0 ] [ 0 0 0 1 ] translation: [ 1 0 0 Tx ] [ 0 1 0 Ty ] [ 0 0 1 Tz ] [ 0 0 0 1 ] scale: [ Sx 0 0 0 ] [ 0 Sy 0 0 ] [ 0 0 Sz 0 ] [ 0 0 0 1 ] where R11 through R33 are appropriate rotation components, Tx, Ty, and Tz are translation components in the x, y, and z directions respectively, and Sx, Sy, and Sz are scaling factors in the x, y, and z directions respectively. With these conventions, a point in three dimensional space will be represented by a column vector, the first three components of which are the x, y, and z coordinates of the point and the fourth component of which is always unity. Transforming that point to a new coordinate system then corresponds to left multiplying the column vector by the appropriate transformation matrix. Note that it is never necessary to explicitly construct these transformation matrices. P3D provides functions that construct them, as described in the section on Geometric Transformations below. The 'front' face of a polygon is also determined by a right hand rule. For example, the front face of the triangle with vertices ( 0, 0, 0), ( 1, 0, 0), and (0, 1, 0) is the face on the z>0 side. If the vertices of a polygon have local normals (see below), and those normals are inconsistant with the facing direction of the polygon as derived from the right hand rule, unpredictable results may occur on rendering. Polygon facing may be used for backface culling. All text is drawn in a plane, the orientation of which is specified by the 'u' and 'v' vectors provided in the text primitive. The front face of the text is derived by applying the right hand rule to these two vectors. If the 'u' vector lies in the x direction and the 'v' vector lies in the y direction, the front face of the text will be on the positive z side. 5. Memory Management Rules The programmer need not worry about freeing memory associated with most P3D structures, as the normal garbage collection mechanisms of Lisp will handle the task. This is not always possible for gobs, however, as a gob may have associated with it data structures in the renderer, and those data structures must be freed when the gob is freed. Thus, several special functions are needed to handle the memory management of gobs. A gob is freed if and only if the following conditions apply. It must have no parents which have not been freed, it must not be 'held' (see below), and it or its last surviving parent must be explicitly freed. Functions to hold and release a gob, and to free it, are described in the section on Geometrical Objects below. It is important to use these functions when destroying a gob which is no longer needed, so that memory within the renderer will be reclaimed. 6. Primitive Objects 6.1. Point The structure used to hold the coordinates of a point in 3-space is defined as follows: (defstruct point (x 0.0) ;x coordinate (y 0.0) ;y coordinate (z 0.0)) ;z coordinate It can be created via the function 'make-point', which can take the options ':x', ':y', and ':z', all of which are floating point numbers defaulting to 0.0. For example, (setq origin (make-point)) is the definition of the standard symbol 'origin'. 6.2. Vector The structure used to hold a vector in 3-space is defined as follows: (defstruct vector (x 0.0) ;x coordinate (y 0.0) ;y coordinate (z 0.0)) ;z coordinate It can be created via the function 'make-vector', which can take the options ':x', ':y', and ':z', all of which are floating point numbers defaulting to 0.0. For example, (setq x-vec (make-vector :x 1.0 :y 0.0 :z 0.0)) is the definition of the standard symbol 'x-vec'. 6.3. Color The structure used to hold a color is defined as follows: (defstruct color (r 0.8) ;red intensity (g 0.8) ;green intensity (b 0.8) ;blue intensity (a 1.0)) ;opacity It can be created via the function 'make-color', which can take the options ':r' for red intensity, ':g' for green intensity, ':b' for blue intensity, and ':a' for opacity (sometimes called the alpha channel). All of these values are assumed to be floating point values in the range 0.0 to 1.0 inclusive, with 0.0 being no intensity in that color or complete transparency. The defaults are 0.8 for each of the red, green, and blue values, and 1.0 or complete opacity for the alpha value. For example, (setq red (make-color :r 1.0 :g 0.0 :b 0.0)) is the definition of the standard symbol 'red'. 6.4. Vertex The structure used to hold a vertex (a position in 3 dimensional space, possibly with an associated color and/or normal vector) is defined as a struct containing at least the following fields: (defstruct vertex (x 0.0) ;x coordinate (y 0.0) ;y coordinate (z 0.0) ;z coordinate (clr nil) ;local color (normal nil)) ;local surface normal It can be created via the function 'make-vertex', which can take the options ':x' for x coordinate, ':y' for y coordinate, ':z' for z coordinate (these three being floating point numbers), ':clr' (a color, as returned by 'make-color') for local color, and ':normal' (a vector, as returned by 'make-vector') for local surface normal. The coordinate values default to 0.0, so the default location is the origin. The local color defaults to nil, so that the vertex will be drawn with a color inherited from its parents in the DAG. The local normal also defaults to nil; the renderer will attempt to calculate a normal by interpolating the orientations of adjacent polygons if this is the case. For example, (setq red-origin (make-vertex :clr red)) will define a vertex located at the origin with a color of 'red' (as defined above) and no normal. 6.5. Material The structure used to hold a material (a set of properties used with attributes like color to determine the appearance of an object) is represented as a structure with at least the following fields: Field Type Meaning :ka float ambient light weighting factor :kd float diffuse light weighting factor :ks float specular light weighting factor :exp float specular exponent :reflect float reflection coefficient :refract float index of refraction :energy color energy density (for radiosity) Other structure fields may exist, but they are maintained by P3D and should not be modified by the programmer. A material should always be created with the 'def-material' function. ( def-material :ka ka-value :kd kd-value :ks ks-value :exp exp-value :reflect reflect-value :refract refract-value :energy energy-color ) parameters: :ka ka-value (optional): ambient light weighting factor :kd kd-value (optional): diffuse light weighting factor :ks ks-value (optional): specular light weighting factor :exp exp-value (optional): specular exponent :reflect reflect-value (optional): reflection coefficient :refract refract-value (optional): index of refraction :energy energy-color (optional): energy density for radiosity returns: material with the given characteristics All the keyword-field pairs are optional. Fields which are not specified are assigned specific default values; see the specification of the 'default- material' predefined symbol at the end of this document for the default values of each field. A material can be used to describe the way light interacts with an object, and thus its appearance. For example, (setq aluminum-material (def-material :ka 0.25 :kd 0.25 :ks 0.75 :exp 6.0 :reflect 0.75)) is the definition of the standard material symbol 'aluminum-material'. This material is quite reflective, but has a relatively low specular exponent, so it will appear shiny but not polished. 6.6. Camera The structure used to hold a camera is defined as follows: (defstruct camera (lookfrom origin) ;eye point (lookat origin) ;point to look at (up y-vec) ;view's 'up' direction (fovea 56.0) ;view included angle (hither -0.01) ;hither clipping distance (yon -100.0) ;yon clipping distance (background black)) ;background color Camera structs are used to define viewing characteristics for rendering. It is created via the function 'make-camera', which can take the following options: Option Type Meaning :lookfrom point location of camera :lookat point location at which camera is to point :up vector direction from bottom to top of view :fovea float camera opening angle in degrees :hither float distance to hither clipping plane :yon float distance to yon clipping plane :background color background color Both the lookat and lookfrom points default to the origin, so at least one must be set to produce a valid camera. The camera's 'up' direction defaults to the y direction. The fovea angle defaults to 56 degrees, and the hither and yon distances default to -0.01 and -100.0 respectively. (Note that because the coordinate system of the camera is required to be right-handed, the ':lookat' point will lie in the negative z direction from the origin, so the hither and yon clipping distances must be negative). The background color defaults to black. The following example defines a camera at the coordinates (0.0, 0.0, 20.0) looking at the origin, with all other characteristics left at their defaults. (setq this-camera (make-camera :lookat origin :lookfrom (make-point :z 20.0))) 7. Geometric Transformations P3D provides functions to generate transformation matrices, as described in the Coordinate Conventions section above. The functions are: ( make-translate Tx Ty Tz ) parameters: Tx, Ty, Tz: floating point numbers giving distance to translate in the x, y, and z directions respectively. returns: a transformation matrix encoding the translation ( make-rotate axis angle ) parameters: axis: vector providing the axis about which to rotate angle: angle in degrees of the rotation returns: a transformation matrix encoding the rotation ( make-scale Sx Sy Sz ) parameters: Sx, Sy, Sz: floating point numbers giving factors by which to scale the x, y, and z directions respectively returns: a transformation matrix encoding the scaling ( make-identity ) parameters: none returns: a transformation matrix encoding the identity transformation ( compose-transform trans1 trans2 ) parameters: trans1, trans2: transformation matrices returns: trans1 x trans2 (remember that subsequent transformations should left multiply existing transformations) ( compose-transforms trans1 trans2 trans3 ... transn ) parameters: trans1 ... transn: transformation matrices returns: trans1 x trans2 x ... x transn (remember that subsequent transformations should left multiply existing transformations). compose-transforms is somewhat slower than compose-transform. 8. Geometrical Object (Gob) A gob is represented as a structure with at least the following options: Option Type Meaning :attr assoc-list attribute-value pairs for this gob :transform transformation coordinate transformation :children list list of gobs to be children Other structure slots may exist, but they are maintained by P3D and should not be modified by the programmer. All of the fields default to nil. A gob should always be created with 'def-gob', or with one of the geometrical primitive generators (see below). If 'def-gob' is used, the definition should include a ':children' option or the gob will have no decendents in the DAG and thus be useless. ( def-gob :attr attrlist :transform transformation :children childlist ) parameters: :children childlist (required): list of children of this gob :transform transformation (optional): coordinate transformation for this gob :attr attrlist (optional): association list of attribute and value pairs for this gob returns: gob with the given children, coordinate transformation, and attributes If old_gob_1 and old_gob_2 are previously created gobs, the following will create a gob called new_gob which includes a coordinate transformation, and has the two other gobs as children. (setq new_gob (def-gob :transform (make-translate 1.0 0.0 0.0) :children (list old-gob-1 old-gob 2))) As described in the Memory Management section above, a gob can be 'held' to guarantee that it will not be freed, and 'unheld' to permit reclaimation of its memory. The 'hold-gob' and 'unhold-gob' functions have the following syntax: ( hold-gob gob ) parameters: gob: gob to be held returns: T ( unhold-gob gob ) parameters: gob: gob to be released returns: Nil Applying 'hold-gob' to a gob which is already held is a null operation, as is applying 'unhold-gob' to a gob which is not held. A gob which is not held and which has no parents can be freed with 'free-gob'. This function causes memory associated with the gob in the renderer to be freed; any future reference to the gob will be an error. The children of the freed gob are checked to see if they have any other parents (which have not themselves been freed); an orphaned child which is not itself held is also freed. The syntax of free-gob is as follows: ( free-gob gob ) parameters: gob: gob to be freed. returns: Nil. 9. Attributes Attributes are data other than geometrical data which is used in rendering. Each gob can have associated with it a list of attribute-value pairs; this list is stored in the gob's ':attr' slot. Attributes are inherited down the geometry DAG, in such a way that a value for a given attribute on a gob which is a close parent of a geometrical primitive (see below) will supersede a value assigned that attribute farther up the DAG. A gob's attributes are stored in an association list, of the sort searched by the Common Lisp 'assoc' function. Association lists are of the form: ( (attr1 . val1) (attr2 . val2) (attr3 . val3) ... ) The following attributes are currently supported by P3D: Attribute Value Default Meaning 'color color opaque white default color below this gob 'backcull T or nil nil enable backface culling 'text-height float 1.0 character height for capital X character 'text-font string "simplex_roman" font in which text will be written 'text-stroke-width-fraction float 0.15 strokes with which text is drawn will be this fraction of text-height 'text-thickness-fraction float 0.1 if the text has thickness (perpendicular to u and v), it will be this fraction of text-height 'material material default-material material type for this gob and its children Any given renderer may ignore some of these attributes. Because the DAG traversal process may reverse the order of attribute-value pairs within a gob, the attribute list for a given gob should have only one occurance of a given attribute. The following example creates a gob with an attribute list setting a default color of blue and enabling backface culling: (setq sample_gob (def-gob :attr (list (cons 'color blue) '(backcull . T)) :children (list old_gob_1 old_gob_2))) 10. Geometrical Primitives P3D defines a number of functions which return geometrical primitive gobs. These gobs are leaf nodes in the rendering DAG; they have no children. These primitives are rendered with the attributes inherited from their parents, except in those cases where the vertices of the primitive specify the attribute explicitly (e.g. color). The funcions which generate primitives are: ( sphere ) parameters: none returns: gob containing a sphere of radius 1, centered at the origin ( cylinder ) parameters: none returns: gob containing a cylinder of radius 1, with the symmetry axis aligned with the z axis. The cylinder ends are at z= 0.0 and z= 1.0 . ( torus bigradius smallradius ) parameters: bigradius: float specifying major radius of torus smallradius: float specifying minor radius of torus returns: gob containing a torus with the given major and minor radii, with the hole in the torus running along the z axis. ( polyline v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices to be connected by the polyline. There must be at least two vertices. returns: gob containing a polyline connecting the given vertices. The polyline is not closed; i.e. vn is not connected to v1. ( polymarker v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices at which markers are to be drawn. There must be at least one vertex. returns: gob containing a polymarker, the markers of which are at the given vertices. The markers are of the current marker type. Depending on the renderer, the marker drawn may or may not be subject to geometric transformations. For example, a marker might be of constant size, or might scale with the projection of the model. ( polygon v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices to form the perimiter of the polygon. There must be at least three vertices. returns: gob containing a polygon with the given vertices. The polygon is closed automatically; i.e. v1 need not equal vn. comments: The appearance of non-planar polygons may vary from renderer to renderer. ( triangle v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices to be used to form the triangle strip. returns: gob containing a triangle strip composed of the given vertices. The strip is a series of triangles, each defined by an adjacent set of three vertices from the vertex list. Thus, the first triangle is composed of v1, v2, and v3; the second of v2, v3, and v4; and so on. The 'front' face of a triangle strip is determined by the right hand rule for odd numbered triangles, and a left hand rule for even numbered triangles. ( mesh vlist flist ) parameters: vlist: list of vertices included in the mesh flist: list of lists of vertices, one list per polygonal facet. returns: gob containing a generalized mesh composed of the given facets, which are polygons the corners of which are in the given list of vertices. comments: The vertices in the facet lists should be the same vertices as those in the vertex list, not simply different vertices at the same coordinate location. For example, if v1, v2, v3, and v4 are vertices, the following is a valid mesh: (mesh (list v1 v2 v3 v4) (list (list v1 v2 v3) (list v2 v3 v4) ) ) ( bezier v1 v2 v3 ... v16 ) parameters: v1 to v16: The control vertices of a 4 by 4 bicubic Bezier patch. returns: gob containing a 4 by 4 bicubic Bezier patch, defined by the control vertices as follows: *-------*--------*--------* |v1 |v2 |v3 |v4 | | | | | | | | *-------*--------*--------* |v5 |v6 |v7 |v8 | | | | | | | | *-------*--------*--------* |v9 |v10 |v11 |v12 | | | | | | | | *-------*--------*--------* v13 v14 v15 v16 The 'up' surface of the patch is defined by the right hand rule circulating in the v1-v4-v16-v13 order, so that the above illustration's 'up' direction is into the page. comments: The patch passes through the corner vertices; returns: Nil. 9. Attributes Attributes are data other than geometrical data which is used in rendering. Each gob can have associated with it a list of attribute-value pairs; this list is stored in the gob's ':attr' slot. Attributes are inherited down the geometry DAG, in such a way that a value for a given attribute on a gob which is a close parent of a geometrical primitive (see below) will supersede a value assigned that attribute farther up the DAG. A gob's attributes are stored in an association list, of the sort searched by the Common Lisp 'assoc' function. Association lists are of the form: ( (attr1 . val1) (attr2 . val2) (attr3 . val3) ... ) The following attributes are currently supported by P3D: Attribute Value Default Meaning 'color color opaque white default color below this gob 'backcull T or nil nil enable backface culling 'text-height float 1.0 character height for capital X character 'text-font string "simplex_roman" font in which text will be written 'text-stroke-width-fraction float 0.15 strokes with which text is drawn will be this fraction of text-height 'text-thickness-fraction float 0.1 if the text has thickness (perpendicular to u and v), it will be this fraction of text-height 'material material default-material material type for this gob and its children Any given renderer may ignore some of these attributes. Because the DAG traversal process may reverse the order of attribute-value pairs within a gob, the attribute list for a given gob should have only one occurance of a given attribute. The following example creates a gob with an attribute list setting a default color of blue and enabling backface culling: (setq sample_gob (def-gob :attr (list (cons 'color blue) '(backcull . T)) :children (list old_gob_1 old_gob_2))) 10. Geometrical Primitives P3D defines a number of functions which return geometrical primitive gobs. These gobs are leaf nodes in the rendering DAG; they have no children. These primitives are rendered with the attributes inherited from their parents, except in those cases where the vertices of the primitive specify the attribute explicitly (e.g. color). The funcions which generate primitives are: ( sphere ) parameters: none returns: gob containing a sphere of radius 1, centered at the origin ( cylinder ) parameters: none returns: gob containing a cylinder of radius 1, with the symmetry axis aligned with the z axis. The cylinder ends are at z= 0.0 and z= 1.0 . ( torus bigradius smallradius ) parameters: bigradius: float specifying major radius of torus smallradius: float specifying minor radius of torus returns: gob containing a torus with the given major and minor radii, with the hole in the torus running along the z axis. ( polyline v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices to be connected by the polyline. There must be at least two vertices. returns: gob containing a polyline connecting the given vertices. The polyline is not closed; i.e. vn is not connected to v1. ( polymarker v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices at which markers are to be drawn. There must be at least one vertex. returns: gob containing a polymarker, the markers of which are at the given vertices. The markers are of the current marker type. Depending on the renderer, the marker drawn may or may not be subject to geometric transformations. For example, a marker might be of constant size, or might scale with the projection of the model. ( polygon v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices to form the perimiter of the polygon. There must be at least three vertices. returns: gob containing a polygon with the given vertices. The polygon is closed automatically; i.e. v1 need not equal vn. comments: The appearance of non-planar polygons may vary from renderer to renderer. ( triangle v1 v2 v3 ... vn ) parameters: v1 ... vn: vertices to be used to form the triangle strip. returns: gob containing a triangle strip composed of the given vertices. The strip is a series of triangles, each defined by an adjacent set of three vertices from the vertex list. Thus, the first triangle is composed of v1, v2, and v3; the second of v2, v3, and v4; and so on. The 'front' face of a triangle strip is determined by the right hand rule for odd numbered triangles, and a left hand rule for even numbered triangles. ( mesh vlist flist ) parameters: vlist: list of vertices included in the mesh flist: list of lists of vertices, one list per polygonal facet. returns: gob containing a generalized mesh composed of the given facets, which are polygons the corners of which are in the given list of vertices. comments: The vertices in the facet lists should be the same vertices as those in the vertex list, not simply different vertices at the same coordinate location. For example, if v1, v2, v3, and v4 are vertices, the following is a valid mesh: (mesh (list v1 v2 v3 v4) (list (list v1 v2 v3) (list v2 v3 v4) ) ) ( bezier v1 v2 v3 ... v16 ) parameters: v1 to v16: The control vertices of a 4 by 4 bicubic Bezier patch. returns: gob containing a 4 by 4 bicubic Bezier patch, defined by the control vertices as follows: *-------*--------*--------* |v1 |v2 |v3 |v4 | | | | | | | | *-------*--------*--------* |v5 |v6 |v7 |v8 | | | | | | | | *-------*--------*--------* |v9 |v10 |v11 |v12 | | | | | | | | *-------*--------*--------* v13 v14 v15 v16 The 'up' surface of the patch is defined by the right hand rule circulating in the v1-v4-v16-v13 order, so that the above illustration's 'up' direction is into the page. comments: The patch passes through the corner vertices; the other vertices define the shape of the spline surface. The treatment of color and normal information associated with the vertices is renderer dependent. ( text point uvec vvec string ) parameters: point: point in 3D space at which the text is to be written. uvec: vector in 3D space specifying the u axis of the plane in which the text is to be drawn vvec: vector in 3D space specifying the v axis of the plane in which the text is to be drawn string: character string to be written. returns: gob containing a written character string. The writing plane and other attributes are determined by the inherited values of the appropriate 'text-' attributes. The text is drawn starting at the given point, in a plane the orientation of which is given by the u and v vectors. 11. Lights P3D provides two function which return light sources. These light sources are gobs which serves as a leaf node of a DAG; they have no children. Light sources can provide directional illumination, or can provide ambient background light which illuminates all surfaces regardless of orientation. The functions which produce these lights are: ( light location lightcolor ) parameters: location: point in 3D space at which to place the light source. (Note that some renderers will retreat the light to infinity along the line from the origin of the current coordinate system through the given point). lightcolor: color of the light to be emitted from this source. returns: gob containing a directional light source specified by the given parameters. ( ambient lightcolor ) parameters: lightcolor: color of the light to be emitted from this source. returns: gob containing an ambient light source of the given color. For example, the following defines a white light source at the coordinates (1, 0, 0) and binds it to the symbol 'new_light'. (setq new_light (light (make-point :x 1.0 ) (make-color :r 1.0 :g 1.0 :b 1.0))) 12. Rendering Once a geometry DAG and a DAG containing light sources has been constructed, and a camera structure has been defined, the P3D 'snap' function can be used to initiate rendering. (It is possible for a single dag containing both geometrical primitives and light sources to be used for both the lighting and geometry DAGs). The snap function has the following format: ( snap object lights acamera ) parameters: object: gob containing the model to be rendered lights: gob containing light sources acamera: camera struct defining the field of view returns: 'T The exact action of 'snap' will depend on the renderer being used. For example, a slow renderer might render the single given frame, while a dynamic renderer might render the object continuously, allowing the point of view to be changed via a knob box, until control was returned to the P3D interpreter. 13. Predefined Symbols P3D predefines some symbols for commonly used constructs for convenience's sake. The predefined symbols include the following: Symbol Meaning Definition origin point at origin (make-point :x 0.0 :y 0.0 :z 0.0) x-vec x unit vector (make-vector :x 1.0) y-vec y unit vector (make-vector :y 1.0) z-vec z unit vector (make-vector :z 1.0) white color white (make-color :r 1.0 :g 1.0 :b 1.0) black color black (make-color :r 0.0 :g 0.0 :b 0.0) red color red (make-color :r 1.0 :g 0.0 :b 0.0) green color green (make-color :r 0.0 :g 1.0 :b 0.0) blue color blue (make-color :r 0.0 :g 0.0 :b 1.0) yellow color yellow (make-color :r 0.0 :g 1.0 :b 1.0) cyan color cyan (make-color :r 1.0 :g 0.0 :b 1.0) magenta color magenta (make-color :r 1.0 :g 1.0 :b 0.0) null-transform identity transform (make-identity) default-material default material (def-material :ka 0.8 :kd 0.8 :ks 0.3 :exp 30.0 :reflect 0.1 :refract 1.0 :energy black) dull-material material type with (def-material :ka 0.9 :kd 0.9 low reflectivity :ks 0.1 :exp 5.0 :reflect 0.1 :refract 1.0 :energy black) shiny-material glossy material (def-material :ka 0.5 :kd 0.5 type :ks 0.5 :exp 50.0 :reflect 0.3 :refract 1.0 :energy black) metallic-material metallic material (def-material :ka 0.1 :kd 0.1 type, like chrome :ks 0.9 :exp 100.0 :reflect 0.7 :refract 1.0 :energy black) matte-material material type with (def-material :ka 1.0 :kd 1.0 no reflectivity :ks 0.0 :exp 0.0 :reflect 0.0 :refract 1.0 :energy black) aluminum-material aluminum (def-material :ka 0.25 :kd 0.25 :ks 0.75 :exp 6.0 :reflect 0.75 :refract 1.0 :energy black) Table of Contents 1. Introduction 1 2. Overview 1 3. Syntax Rules and Special Conventions 1 4. Coordinate Conventions and Orientation Rules 1 5. Memory Management Rules 1 6. Primitive Objects 1 6.1. Point 1 6.2. Vector 2 6.3. Color 2 6.4. Vertex 2 6.5. Material