home *** CD-ROM | disk | FTP | other *** search
/ gondwana.ecr.mu.oz.au/pub/ / Graphics.tar / Graphics / SPD.3.0.shar.gz / SPD.3.0.shar / NFF < prev    next >
Text File  |  1991-01-13  |  9KB  |  242 lines
  1. Neutral File Format,
  2.     by Eric Haines, 3D/Eye Inc, 2359 North Triphammer Road, Ithaca, NY  14850
  3.     email: erich@eye.com, wrath.cs.cornell.edu!eye!erich
  4.  
  5. Draft #1, 10/3/88
  6. Version 2.7, as of 5/22/90 - added information on hither, light color
  7. Version 3.0, 12/17/90 - minor information changes
  8.  
  9. The NFF (Neutral File Format) is designed as a minimal scene description
  10. language.  The language was designed in order to test various rendering
  11. algorithms and efficiency schemes.  It is meant to describe the geometry and
  12. basic surface characteristics of objects, the placement of lights, and the
  13. viewing frustum for the eye.  Some additional information is provided for
  14. esthetic reasons (such as the color of the objects, which is not strictly
  15. necessary for testing the efficiency of rendering algorithms).
  16.  
  17. Future enhancements could include:  circle and torus objects, spline surfaces
  18. with trimming curves, directional lights, characteristics for positional
  19. lights, CSG descriptions, and probably more by the time you read this.
  20. Comments, suggestions, and criticisms are all welcome.
  21.  
  22. At present the NFF file format is used in conjunction with the SPD (Standard
  23. Procedural Database) software, a package designed to create a variety of
  24. databases for testing rendering schemes.  For more information about SPD see
  25. "A Proposal for Standard Graphics Environments," IEEE Computer Graphics and
  26. Applications, vol. 7, no. 11, November 1987, pp. 3-5.  See IEEE CG&A, vol. 8,
  27. no. 1, January 1988, p. 18 for the correct image of the tree database (the
  28. only difference is that the sky is blue, not orange).
  29.  
  30. The SPD package is available via anonymous FTP from:
  31.  
  32.     freedom.graphics.cornell.edu [128.84.247.85]
  33.     weedeater.math.yale.edu [130.132.23.17]
  34.     cs.uoregon.edu [128.223.4.13]
  35.  
  36. among others.  For those without FTP access, write to the netlib automatic
  37. mailer:  research!netlib and netlib@ornl.gov are the sites.  Send a one line
  38. message "send index" for more information, or "send haines from graphics" for
  39. the latest version of the SPD package.  If you're looking for a good scene
  40. description language, see Craig Kolb's RayShade software (found on weedeater).
  41. NFF is meant for testing efficiency schemes and so has minimal support for
  42. lighting and shading.
  43.  
  44. By providing a minimal interface, NFF is meant to act as a simple format to
  45. allow the programmer to quickly write filters to move from NFF to the
  46. local file format.  Presently the following entities are supported:
  47.      A simple perspective frustum
  48.      A background color description
  49.      A positional (vs. directional) light source description
  50.      A surface properties description
  51.      Polygon, polygonal patch, cylinder/cone, and sphere descriptions
  52.  
  53. Files are output as lines of text.  For each entity, the first field defines
  54. its type.  The rest of the line and possibly other lines contain further
  55. information about the entity.  Entities include:
  56.  
  57. "v"  - viewing vectors and angles
  58. "b"  - background color
  59. "l"  - positional light location
  60. "f"  - object material properties
  61. "c"  - cone or cylinder primitive
  62. "s"  - sphere primitive
  63. "p"  - polygon primitive
  64. "pp" - polygonal patch primitive
  65.  
  66.  
  67. These are explained in depth below.
  68.  
  69. --------
  70.  
  71. Viewpoint location.  Description:
  72.     "v"
  73.     "from" Fx Fy Fz
  74.     "at" Ax Ay Az
  75.     "up" Ux Uy Uz
  76.     "angle" angle
  77.     "hither" hither
  78.     "resolution" xres yres
  79.  
  80. Format:
  81.  
  82.     v
  83.     from %g %g %g
  84.     at %g %g %g
  85.     up %g %g %g
  86.     angle %g
  87.     hither %g
  88.     resolution %d %d
  89.  
  90. The parameters are:
  91.  
  92.     From:  the eye location in XYZ.
  93.     At:    a position to be at the center of the image, in XYZ world
  94.        coordinates.  A.k.a. "lookat".
  95.     Up:    a vector defining which direction is up, as an XYZ vector.
  96.     Angle: in degrees, defined as from the center of top pixel row to
  97.        bottom pixel row and left column to right column.
  98.     Hither: distance of the hither plane (if any) from the eye.  Mostly
  99.        needed for hidden surface algorithms.
  100.     Resolution: in pixels, in x and in y.
  101.  
  102.   Note that no assumptions are made about normalizing the data (e.g. the
  103.   from-at distance does not have to be 1).  Also, vectors are not
  104.   required to be perpendicular to each other.
  105.  
  106.   For all databases some viewing parameters are always the same:
  107.     Yon is "at infinity."
  108.     Aspect ratio is 1.0.
  109.  
  110.   A view entity must be defined before any objects are defined (this
  111.   requirement is so that NFF files can be displayed on the fly by hidden
  112.   surface machines).
  113.  
  114. --------
  115.  
  116. Background color.  A color is simply RGB with values between 0 and 1:
  117.     "b" R G B
  118.  
  119. Format:
  120.     b %g %g %g
  121.  
  122.     If no background color is set, assume RGB = {0,0,0}.
  123.  
  124. --------
  125.  
  126. Positional light.  A light is defined by XYZ position.  Description:
  127.     "l" X Y Z [R G B]
  128.  
  129. Format:
  130.     l %g %g %g [%g %g %g]
  131.  
  132.     All light entities must be defined before any objects are defined (this
  133.     requirement is so that NFF files can be used by hidden surface machines).
  134.     Lights have a non-zero intensity of no particular value, if not specified
  135.     (i.e. the program can determine a useful intensity as desired); the
  136.     red/green/blue color of the light can optionally be specified.
  137.  
  138. --------
  139.  
  140. Fill color and shading parameters.  Description:
  141.     "f" red green blue Kd Ks Shine T index_of_refraction
  142.  
  143. Format:
  144.     f %g %g %g %g %g %g %g %g
  145.  
  146.     RGB is in terms of 0.0 to 1.0.
  147.  
  148.     Kd is the diffuse component, Ks the specular, Shine is the Phong cosine
  149.     power for highlights, T is transmittance (fraction of contribution of the
  150.     transmitting ray).  Usually, 0 <= Kd <= 1 and 0 <= Ks <= 1, though it is
  151.     not required that Kd + Ks == 1.  Note that transmitting objects ( T > 0 )
  152.     are considered to have two sides for algorithms that need these (normally
  153.     objects have one side).
  154.  
  155.     The fill color is used to color the objects following it until a new color
  156.     is assigned.
  157.  
  158. --------
  159.  
  160. Objects:  all objects are considered one-sided, unless the second side is
  161. needed for transmittance calculations (e.g. you cannot throw out the second
  162. intersection of a transparent sphere in ray tracing).
  163.  
  164. Cylinder or cone.  A cylinder is defined as having a radius and an axis
  165.     defined by two points, which also define the top and bottom edge of the
  166.     cylinder.  A cone is defined similarly, the difference being that the apex
  167.     and base radii are different.  The apex radius is defined as being smaller
  168.     than the base radius.  Note that the surface exists without endcaps.  The
  169.     cone or cylinder description:
  170.  
  171.     "c"
  172.     base.x base.y base.z base_radius
  173.     apex.x apex.y apex.z apex_radius
  174.  
  175. Format:
  176.     c
  177.     %g %g %g %g
  178.     %g %g %g %g
  179.  
  180.     A negative value for both radii means that only the inside of the object is
  181.     visible (objects are normally considered one sided, with the outside
  182.     visible).  Note that the base and apex cannot be coincident for a cylinder
  183.     or cone.  Making them coincident could be used to define endcaps, but none
  184.     of the SPD scenes currently make use of this definition.
  185.  
  186. --------
  187.  
  188. Sphere.  A sphere is defined by a radius and center position:
  189.     "s" center.x center.y center.z radius
  190.  
  191. Format:
  192.     s %g %g %g %g
  193.  
  194.     If the radius is negative, then only the sphere's inside is visible
  195.     (objects are normally considered one sided, with the outside visible).
  196.     Currently none of the SPD scenes make use of negative radii.
  197.  
  198. --------
  199.  
  200. Polygon.  A polygon is defined by a set of vertices.  With these databases,
  201.     a polygon is defined to have all points coplanar.  A polygon has only
  202.     one side, with the order of the vertices being counterclockwise as you
  203.     face the polygon (right-handed coordinate system).  The first two edges
  204.     must form a non-zero convex angle, so that the normal and side visibility
  205.     can be determined by using just the first three vertices.  Description:
  206.  
  207.     "p" total_vertices
  208.     vert1.x vert1.y vert1.z
  209.     [etc. for total_vertices vertices]
  210.  
  211. Format:
  212.     p %d
  213.     [ %g %g %g ] <-- for total_vertices vertices
  214.  
  215. --------
  216.  
  217. Polygonal patch.  A patch is defined by a set of vertices and their normals.
  218.     With these databases, a patch is defined to have all points coplanar.
  219.     A patch has only one side, with the order of the vertices being
  220.     counterclockwise as you face the patch (right-handed coordinate system).
  221.     The first two edges must form a non-zero convex angle, so that the normal
  222.     and side visibility can be determined.  Description:
  223.  
  224.     "pp" total_vertices
  225.     vert1.x vert1.y vert1.z norm1.x norm1.y norm1.z
  226.     [etc. for total_vertices vertices]
  227.  
  228. Format:
  229.     pp %d
  230.     [ %g %g %g %g %g %g ] <-- for total_vertices vertices
  231.  
  232. --------
  233.  
  234. Comment.  Description:
  235.     "#" [ string ]
  236.  
  237. Format:
  238.     # [ string ]
  239.  
  240.     As soon as a "#" character is detected, the rest of the line is considered
  241.     a comment.
  242.