home *** CD-ROM | disk | FTP | other *** search
/ Virtual Reality Zone / VRZONE.ISO / mac / PC / VDF / VDF.ZIP / VDF.TXT < prev    next >
Text File  |  1994-11-21  |  41KB  |  1,045 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.      VDF - A File Format for the Interchange of Virtual Worlds
  8.  
  9.                        Bernie Roehl and Kerry Bonin
  10.                            Version 1.00
  11.                           November 1994
  12.  
  13. Premise
  14.  
  15.       As the Virtual Reality industry matures, there is an increasing need for
  16. standardization.   In particular, there is  a need for a  standard file format
  17. for storing descriptions of both individual objects and entire worlds.
  18.  
  19.       This document proposes  such a  file format, called  VDF (Virtual  world
  20. Description Format).  It  addresses such issues as  the description of  object
  21. geometry, object  hierarchy, material  properties, and various  other elements
  22. that are  typically  used to  describe a  virtual environment.   The  proposed
  23. format is not  intended to replace the  native formats used by  the various VR
  24. systems;  instead, it  is designed to  be a  kind of  "lingua franca"  for the
  25. exchange of world  descriptions.  In this sense, it's similar to the Rich Text
  26. Format often used for the interchange of word processing documents.
  27.  
  28.       The primary purpose of the format is to enable third party developers to
  29. create and  distribute objects and  worlds that can  be used by the  entire VR
  30. community.   Object  creation is  one of  the more  tedious aspects  of world-
  31. building; having a standard  format allows large databases of  virtual objects
  32. to be created more easily than they can be at present.  A standard  format not
  33. only simplifies the work of the world-builder, it also enhances the usefulness
  34. of  all VR systems  since their  users gain access  to a larger  collection of
  35. resources.
  36.  
  37. Some Background
  38.  
  39.       The  specifications for this format  grew out of  an informal discussion
  40. held   at   the  Meckler   Virtual  Reality   Conference   in  May   of  1994.
  41. Representatives  from VREAM,  Superscape, Straylight,  Virtek and  others were
  42. present;  the discussion was lively and open,  and there was general agreement
  43. on the need for a standard file format.
  44.  
  45. Why Not DXF?
  46.  
  47.       The only format that all vendors currently support is DXF.  However, DXF
  48. was never  intended for this purpose;  it was originally designed  to meet the
  49. needs of CAD users.  It therefore has many features which are of no use to  VR
  50. developers,  and lacks  many features  that VR  developers would  find useful.
  51. Many of  the existing DXF translators and input routines support only a subset
  52. of the full  DXF specification,  often forcing world-builders  to "tweak"  the
  53. files after they are imported.  DXF also makes no provision for storing  world
  54. layout or object hierarchy descriptions.
  55.  
  56.  
  57.  
  58.  
  59.                                                                              1
  60.  
  61.  
  62.  
  63.  
  64.  
  65. Basic Syntax
  66.  
  67.       A VDF file is considered  to be a stream of printable  ascii characters.
  68. The advantage  of an  ascii  format is  that it's  human-readable;  it can  be
  69. printed on paper, created or modified using a text editor, sent via email, and
  70. so forth.  It also has the advantage of platform-independence;  concerns about
  71. word lengths, byte-ordering, floating-point formats and so on are eliminated.
  72.  
  73.       The file is  free-format; line  boundaries are ignored.   Spaces,  tabs,
  74. carriage returns and line feeds are all treated simply as whitespace.  The use
  75. of whitespace  to enhance readability  is strongly encouraged;  in particular,
  76. indentation should be used to make clear the structure and organization of the
  77. data.
  78.  
  79.       The file consists simply of a series of tagged items of the format
  80.  
  81.             tagname { ... }
  82.  
  83.       The  { } characters enclose data  that is specific to the  tag.  The '{'
  84. and  '}' characters  must  be  surrounded by  whitespace  on  either side,  to
  85. simplify parsing.   Each tagged item can contain other tagged items, nested to
  86. any level; the resulting file looks somewhat like a C program:
  87.  
  88.             top-level-tagname
  89.                   {
  90.                   second-level-tagname
  91.                         {
  92.                         third-level-tagname
  93.                               {
  94.                               ...
  95.                               }
  96.                         another-third-level-tagname
  97.                               {
  98.                               }
  99.                         }
  100.                   another-second-level tagname
  101.                         {
  102.                         ...
  103.                         }
  104.                   }
  105.  
  106.       Any unrecognized tags are simply ignored, along with any items contained
  107. within  them; this ensures that the format  is extensible and that old parsers
  108. will still be able to deal with newer versions of the format.  Ignoring  a tag
  109. consists  of simply  skipping  everything within  the  matching {  }  markers;
  110. however, see  the description of the  STRING data type later  in this document
  111. for  an important  exception  to this.    The ordering  of  tags is  generally
  112. unimportant, except as specifically noted below.
  113.  
  114.       Comments use  the C++ "//" convention; that  is, anything on the current
  115. line after a pair of  slashes is ignored.  More specifically,  everything from
  116.  
  117.                                                                              2
  118.  
  119.  
  120.  
  121.  
  122.  
  123. the  slashes through the  first carriage return  (0x0D) or linefeed  (0x0A) is
  124. ignored.
  125.  
  126.       The syntax  is designed to  be very easy to  parse; in any  case, sample
  127. parsers will be freely distributed  to any interested parties.  Also  provided
  128. will be a  small "test suite"  of objects  and worlds that  will allow  anyone
  129. developing a parser to verify consistency with the standard.
  130.  
  131.       The vast  majority of tags are  optional; they can be  omitted by world-
  132. builders and  ignored by import and  translate functions.  It  is important to
  133. note that importing an object into a VR system and re-exporting it may involve
  134. a  loss of  information, since  not all  VR systems  support all  the features
  135. specified in the format.  For example, some VR systems only support triangles;
  136. when importing a file containing facets (polygons) with more than three sides,
  137. the facets are decomposed into  triangles.  If the file is  re-exported again,
  138. the original n-sided facet information is no longer available.
  139.  
  140. Fundamental Data Types
  141.  
  142.       There are several data types that are used throughout this document.  In
  143. addition to  the types listed below,  some tags may use  additional types that
  144. are tag-specific.
  145.  
  146. REAL
  147.       A  signed,  single-precision  floating-point  number.   For  example:  -
  148.       137.1294
  149.  
  150. NUM
  151.       An  unsigned decimal integer with 32-bit precision, typically used as an
  152.       array index.  For example: 15
  153.  
  154. STRING
  155.       A character string.   Strings are always surrounded by  double-quote (")
  156.       characters.   If  a double-quote or  a backslash  must be  included in a
  157.       string, it  should be  preceeded by  a backslash.    For  example, "This
  158.       string  contains   a  \"doublequoted\"  string  and   a  backslash  (\\)
  159.       character".
  160.  
  161. ID
  162.       An unsigned 32-bit integer, specified in either decimal or hex (hex uses
  163.       the 0x  prefix).   IDs are  only meaningful within  a single  file; they
  164.       should not be used internally within  an application.  IDs are generated
  165.       when the file is created, and are discarded after parsing.  For example:
  166.       0x9348736
  167.  
  168. HANDLE
  169.       An unsigned 32-bit integer, specified in either decimal or hex (hex uses
  170.       the  0x prefix).  HANDLEs  differ from IDs in that  they are used by the
  171.       application, not the parser.  For example, if  it's anticipated that the
  172.       application may need to  reference a particular facet within  an object,
  173.       the facet can be provided with a HANDLE.
  174.  
  175.                                                                              3
  176.  
  177.  
  178.  
  179.  
  180.  
  181. DATE
  182.       To  avoid  the  ambiguity  associated  with  the  mm/dd/yy  vs  dd/mm/yy
  183.       conventions, a  DATE is specified as YYYYMMDD where YYYY is the year, MM
  184.       is the month (January ==  01), and DD is the date.  This  is followed by
  185.       the time in HHMMSS format,  with the hours ranging from 0 to  23 and the
  186.       minutes and seconds ranging from 0 to 59.  For example: 19941104 130502.
  187.  
  188. BOOLEAN
  189.       Either of the values TRUE or FALSE.  For example: TRUE
  190.  
  191. COLOR
  192.       An RGB  triplet, where each  of R, G  and B is a  REAL in the  range 0.0
  193.       through 1.0 inclusive.  For example: 0.2 0.3 0.2
  194.  
  195. FNAME
  196.       A lowercase  STRING  consisting of  no more  than 12  characters in  the
  197.       format  ????????.???; all  the  characters (except  the  '.') should  be
  198.       alphanumeric, and the first should be alphabetic.  This syntax is chosen
  199.       for reasons of DOS compatability.
  200.  
  201. ANGLE
  202.       A REAL value giving a rotation angle in degrees.
  203.  
  204. UNAME
  205.       A STRING value identifying  a specific user.  The recommended format for
  206.       this  is the full  name of the  user, followed by  his or her electronic
  207.       mail address enclosed in "<>" characters.   For example:  John Q. Public
  208.       <jqpublic@someplace.com>
  209.  
  210. Conventions
  211.  
  212.       The   definition  of   all  object  geometry   and  location/orientation
  213. information is done using a left-handed coordinate system, oriented so that if
  214. X points to the right  and Y points up, then Z points forwards.   All positive
  215. rotations around  an axis are clockwise  when viewed from the  positive end of
  216. the axis looking towards the origin.
  217.  
  218.       Wherever  applicable, rotations are carried out in the order yaw, pitch,
  219. roll; in other words, YXZ.
  220.  
  221. Tags
  222.  
  223.       Tag names  consist  of  alphanumeric characters,  plus  '_';  the  first
  224. character must  be alphabetic.   No  specific length limit  is imposed  on tag
  225. names, but they ought  to be unique in the first 32 characters.  Tag names are
  226. not case-sensitive; "thing", "THING" and "Thing" are all equivalent.
  227.  
  228.       There  are   several  tags  which   are  widely  used   throughout  this
  229. specification; their use is described here:
  230.  
  231.  
  232.  
  233.                                                                              4
  234.  
  235.  
  236.  
  237.  
  238.  
  239.             Identifier { ID }
  240.             Application_handle { HANDLE }
  241.             Name { STRING }
  242.             Count { NUM }
  243.  
  244.       An Identifier allows an entity to subsequently be referenced; it  can be
  245. thought  of as an "address".  Only  entities that will be referenced elsewhere
  246. in the  file should be given  an Identifier.  Identifiers  are only meaningful
  247. within a single file, and are discarded after parsing.
  248.  
  249.       The Application_handle allows an entity to be assigned a handle by which
  250. it can  be referenced  by the application  software.  Any  entity can  also be
  251. assigned a Name; its use is application-dependent.
  252.  
  253.       The Count is used to specify  things like array sizes; if a  Count field
  254. is omitted, the value defaults to 1.  Wherever a Count is used, it must appear
  255. before any of the elements of the array whose size it specifies.
  256.  
  257. File Inclusion
  258.  
  259.       There is one tag that may appear at any point in the file where a tag is
  260. valid:
  261.  
  262.             Include { FILENAME }
  263.  
  264.       Files that are  Included should be treated as if  the entire contents of
  265. the file  had been  inserted in  place of  the Include.    Included files  can
  266. include other  files, but there may  be some limits imposed  by the underlying
  267. operating system as to the number of simultaneously open files.
  268.  
  269. Overall File Structure
  270.  
  271.       The file is made up  of a series of tagged entities.   Additional entity
  272. tags  may  be  defined  later,  but  those  that  are  currently  defined  are
  273. World_information,   Palettes,   Maps,  Materials,   Material_tables,  Shapes,
  274. Objects,  Lights, Cameras, Sounds,  and World_attributes; they  appear in that
  275. order in the file.  In other words, the World_informaton  should appear first,
  276. followed  by the Palette,  followed by  all the  Maps, followed  by Materials,
  277. Material_tables, Shapes, and so on.
  278.  
  279. World Information
  280.  
  281.       This  optional  entity  contains  textual information  about  the  world
  282. described in a VDF file.  
  283.       World_information
  284.             {
  285.             Created_by
  286.                   {
  287.                   Person { UNAME }
  288.                   Date { DATE }
  289.                   Comment { STRING }
  290.  
  291.                                                                              5
  292.  
  293.  
  294.  
  295.  
  296.  
  297.                   }
  298.             Modified_by
  299.                   {
  300.                   Person { UNAME }
  301.                   Date { DATE }
  302.                   Comment { STRING }
  303.                   }
  304.             Copyright_message { STRING }
  305.             Usage_restrictions { STRING }
  306.             Title { STRING }
  307.             Comment { STRING }
  308.             }
  309.  
  310. The Modified_by tag can appear more than once.
  311.  
  312. Palettes
  313.  
  314.       A palette  has two parts to it:  an array of RGB  triplets that give the
  315. colors  for individual hardware palette entries, and  a hue map that relates a
  316. hue and brightness to a palette entry.
  317.  
  318.       Palette
  319.             {
  320.             Color_table
  321.                   {
  322.                   Count { NUM }
  323.                   Color_entry { COLOR }
  324.                   Color_entry { COLOR }
  325.                   ...
  326.                   }
  327.             Hue_table
  328.                   {
  329.                   Count { NUM }
  330.                   Hue_entry { NUM NUM }
  331.                   Hue_entry { NUM NUM }
  332.                   ...
  333.                   }
  334.             }
  335.  
  336. The use  of palettes is  entirely optional, and  on non-paletted systems  they
  337. will  be ignored.   However, on paletted  systems, a material will  have a hue
  338. value  associated with it which is used to index the Hue_table.  The Hue_table
  339. in turn gives the range of palette entries associated with that hue; the first
  340. NUM is the index into the Color_table of the darkest color of the hue, and the
  341. second is the index of the lightest.
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.                                                                              6
  350.  
  351.  
  352.  
  353.  
  354.  
  355. Maps
  356.  
  357.       A map is mechanism for relating a  string to a filename.  For example, a
  358. particular  Material may  reference an  image map  called "wood  grain", which
  359. could be associated (through a Map) with the file "wgrain01.pcx".  A Sound may
  360. refer  to  a   sample  called  "door   chime",  which  might   be  Mapped   to
  361. "dingdong.wav".
  362.  
  363. A Map entry has the following format:
  364.  
  365.             Map
  366.                   {
  367.                   Name { STRING }
  368.                   Filename { FNAME }
  369.                   }
  370.  
  371.       Both the Name and Filename tags  are required, since the only purpose of
  372. a  Map entity is to provide the correspondance  between the two.  Map entities
  373. only  provide a  means of  connecting a  platform-independent map name  with a
  374. local filename; typically, an  Include tag is used  to provide a set  of local
  375. Maps for a world.
  376.  
  377. Materials
  378.  
  379.       A Material is a definition of what  a surface looks like; it can contain
  380. a great  deal of information (needed  on some systems), but  the only required
  381. tags are the Identifier  and either the Diffuse_color  or the Hue.  All  other
  382. tags can be omitted when creating  the file, and ignored during parsing.   The
  383. format of a Material is as follows:
  384.  
  385.             Material
  386.                   {
  387.                   Identifier { ID }
  388.                   Name { STRING }
  389.                   Rendering_mode { type }
  390.                   Hue { NUM }
  391.                   Albedo { REAL }
  392.                   Diffuse_color { COLOR }
  393.                   Ambient_color { COLOR }
  394.                   Transparency_color { COLOR }
  395.                   Specular_color { COLOR }
  396.                   Specular_exponent { REAL }
  397.                   Refractive_index { REAL }
  398.                   Texture_map { Name { STRING } }
  399.                   Bump_map { Name { STRING } }
  400.                   Opacity_map { Name { STRING } }
  401.                   Reflection_map { Name { STRING } }
  402.                   Reflection_blur { REAL }
  403.                   Transparency_falloff { REAL }
  404.                   }
  405.  
  406.  
  407.                                                                              7
  408.  
  409.  
  410.  
  411.  
  412.  
  413.       The Rendering_mode type can be one of WIREFRAME, UNLIT, FLAT, GOURAUD or
  414. PHONG.  The default should be FLAT if it's  available, otherwise UNLIT.  UNLIT
  415. Materials always have the  same color, regardless of lighting;  FLAT Materials
  416. have a  constant color across  their surface,  the brightness of  which varies
  417. depending on lighting.  Many of the parameters are included just  for the sake
  418. of completeness,  and for  VR  systems that  pre-compute much  of the  surface
  419. property information.  The Hue is only used  in paletted systems, to select an
  420. entry from  the Hue_table  (and ultimately,  a color from  the palette).   The
  421. Albedo is the overall reflectivity coefficient of the surface.
  422.  
  423.       The  various maps  (texture,  bump, etc)  are  identified by  name;  for
  424. example:
  425.  
  426.             Texture_map { Name { "wood grain" } }
  427.  
  428.       The idea is to allow a single map to be used repeatedly, and in a number
  429. of ways by  different Materials.  There  should be a Map entry  earlier in the
  430. file that  relates "wood grain" to the  name of a file  from which the texture
  431. map can be loaded.
  432.  
  433.       Texture  should be  stored in  external files  as rectangular  arrays of
  434. numeric values that can be used as a regular texture (by systems which support
  435. texture mapping)  or as a  bump or  opacity map (for  those few systems  which
  436. support such  things).  Image maps  in a variety of formats  can be supported;
  437. the type  of map, as  well as its dimensions  and "depth", are  all determined
  438. from the external  file in which the map  is stored.  Recommended  map formats
  439. are PCX  (for  8-bit-deep maps),  TGA  (for  24-bit-deep maps)  and  FLC  (for
  440. animated maps).
  441.  
  442.       Note that on  some systems, there may  be support for  "procedural" maps
  443. that are defined  by code rather than  data.  For those maps,  no Map entities
  444. are required.
  445.  
  446.       There is  some potential  for confusion here,  since the  word "map"  is
  447. being used  to refer to  both a mapping  from a string  to a filename,  and to
  448. refer to an image  map.  It should be clear from context which is the intended
  449. use.
  450.  
  451.             Note that a Material can be very simple:
  452.  
  453.             Material
  454.                   {
  455.                   Identifier { 0x782938 }
  456.                   Diffuse_color { .5 .3 .1 }
  457.                   }
  458.  
  459.       When converting any COLOR  value to a fixed  palette, the palette  entry
  460. with the minimum "distance" from the specified RGB color should be used.  This
  461. mapping can  be done when  the Material is  processed.  Better results  may be
  462. obtained by "weighting" the colors; the expression would be something like
  463.  
  464.  
  465.                                                                              8
  466.  
  467.  
  468.  
  469.  
  470.  
  471.             distance    = 0.3 * (red - palette[i].red)
  472.                         + 0.6 * (green - palette[i].green)
  473.                         + 0.1 * (blue - palette[i].blue)
  474.  
  475.       Needless to say, there's no need  to compute the square root since we're
  476. just choosing a palette entry which gives the minimum distance.
  477.  
  478. Material_tables
  479.  
  480.       References to Materials are  kept in a Material_table, which in  turn is
  481. referenced by any number of different Shapes or Objects.  A Material_table has
  482. the following format:
  483.  
  484.             Material_table
  485.                   {
  486.                   Identifier { ID }
  487.                   Application_handle { HANDLE }
  488.                   Count { NUM }
  489.                   Material_reference { ID }
  490.                   Material_reference { ID }
  491.                   ...
  492.                   }
  493.  
  494.       Every Material_table should have an Identifier.  Each Material_reference
  495. tag contains the ID of the corresponding Material.
  496.  
  497. Shapes
  498.  
  499.       A  Shape is  a  geometric description,  consisting  of a  collection  of
  500. vertices and facets.   It is not the same as an Object, which stores location,
  501. orientation and attachment information.
  502.  
  503.       The format of a Shape is as follows:
  504.  
  505.             Shape
  506.                   {
  507.                   LOD_size { NUM }
  508.                   LOD_replaces { ID }
  509.                   Identifier { ID }
  510.                   Name { STRING }
  511.                   Is_convex { BOOLEAN }
  512.                   Application_handle { HANDLE }
  513.                   Bounding_box { REAL REAL REAL REAL REAL REAL }
  514.                   Uses_material_table { ID }
  515.                   Vertex_list
  516.                         {
  517.                         Count { n }
  518.                         Vertex { ... }
  519.                         Vertex { ... }
  520.                         ...
  521.                         }
  522.  
  523.                                                                              9
  524.  
  525.  
  526.  
  527.  
  528.  
  529.                   Facet_list
  530.                         {
  531.                         Count { n }
  532.                         Facet { ... }
  533.                         Facet { ... }
  534.                         ...
  535.                         }
  536.                   }
  537.  
  538.       The Uses_material_table tag is optional; if present, it specifies the ID
  539. of a  Material_table used by this  Shape.  Note that the  Material_table for a
  540. Shape  is a kind  of default value,  which is only  used if an  Object doesn't
  541. specify  one.  The  conversion to an  internal format can,  of course, be done
  542. once at load time.
  543.  
  544.       The  Bounding_box is entirely  optional, and is intended  only to give a
  545. rough  idea of  how the  vertex values  should be  scaled.   It specifies  the
  546. minimum X,  Y, and Z values  followed by the maximum  X, Y, and  Z values; the
  547. actual bounding information can  (and should) be derived from  the coordinates
  548. of the vertices comprising the Shape.
  549.  
  550.       The Is_convex tag is optional; the default value is FALSE.  Some systems
  551. take advantage  of object convexity  for hidden-surface  removal or  collision
  552. detection; if an object is known to be convex, it should be flagged as such.
  553.  
  554.       The LOD_size and LOD_replaces  tags have to do with  automatic level-of-
  555. detail switching.  Systems that don't support automatic LOD should just ignore
  556. any Shapes that  have an LOD_replaces  field set; to simplify  processing, the
  557. LOD tags (if used) should be the first tags in a Shape.  The  LOD_replaces tag
  558. gives the ID of the Shape that this Shape is a replacement for when the Object
  559. is  greater than a given on-screen size.   The LOD_size is the approximate on-
  560. screen size of the Object in pixels at which this version  of the Shape should
  561. become  the replacement.   Replacement  Shapes should  be specified  after the
  562. Shapes they're  replacing;  in other  words,  the Shapes  should  be given  in
  563. increasing order of detail level.
  564.  
  565. Vertices
  566.  
  567.       A Vertex always contains an X, Y, Z triple; it may also  have additional
  568. information associated with it.  The format for a Vertex is:
  569.  
  570.             Vertex
  571.                   {
  572.                   Point3D { REAL REAL REAL }
  573.                   Normal3D { REAL REAL REAL }
  574.                   Color { COLOR }
  575.                   Application_handle { HANDLE }
  576.                   }
  577.  
  578.       The Point3D  contains the X, Y  and Z values of  the vertex coordinates.
  579. The  Normal3D  tag  contains a  vertex  normal  (used  for Gouraud  and  Phong
  580.  
  581.                                                                             10
  582.  
  583.  
  584.  
  585.  
  586.  
  587. shading); this normal need  not be of unit magnitude.   The Color tag  is used
  588. for  systems   that  do  a  kind  of  Gouraud  shading  without  the  lighting
  589. calculation.
  590.  
  591.       A very simple vertex list might look like this:
  592.  
  593.             Vertex_list
  594.                   {
  595.                   Count { 3 }
  596.                   Vertex { Point3D { 15 12 17 } }
  597.                   Vertex { Point3D { 27  5 18.6 } }
  598.                   Vertex { Point3D { 2 129 27.9 } }
  599.                   }
  600.  
  601.  
  602. Facets
  603.  
  604.       A  Facet (also called a "face" or a  "polygon") is defined to be a flat,
  605. convex shape with  an arbitrary number of vertices.  "Flat" means that all the
  606. vertices in the  Facet are co-planar; "convex" means the  corners of the Shape
  607. all "point" outwards.  Facets are not permitted to have holes in them.
  608.  
  609.       The format for a Facet is as follows:
  610.  
  611.             Facet
  612.                   {
  613.                   Vertex_data
  614.                         {
  615.                         Count { n }
  616.                         Vertex_info { Index { NUM } }
  617.                         Vertex_info { Index { NUM } }
  618.                         ...
  619.                         }
  620.                   Is_doublesided { BOOLEAN }
  621.                   Is_interior { BOOLEAN }
  622.                   Base_facet { ID }
  623.                   Front_material { NUM }
  624.                   Back_material { NUM }
  625.                   Normal3D { REAL REAL REAL }
  626.                   Identifier { ID }
  627.                   Application_handle { HANDLE }
  628.                   }
  629.  
  630.       Only the  Vertex_data  tag  is  required.   Each  of  the  Index  values
  631. references an  element of the Shape's Vertex array.  The vertices are numbered
  632. starting from zero,  and are  listed in  a clockwise  order as  seen from  the
  633. "front"  of the Facet.   If the Count  is 1, a point  should be created rather
  634. than a Facet; similarly, a Count of 2 defines a line.
  635.  
  636.       If Is_doublesided  is TRUE (the default value  is FALSE), then the Facet
  637. can be seen  from both sides; the Back_material is used to paint the back side
  638.  
  639.                                                                             11
  640.  
  641.  
  642.  
  643.  
  644.  
  645. of the Facet.  The Front_material and Back_material are both  indices into the
  646. Materials table for the Object or Shape.  If  the Back_material is omitted, it
  647. defaults to the value of the Front_material.
  648.  
  649.       A  Facet flagged  as being  Is_interior is  on the  inside of  a concave
  650. Shape; for example,  a cup would  have all  the inside surfaces  (the ones  in
  651. contact  with  liquid if  the cup  were full)  flagged as  interior.   Not all
  652. systems will make  use of  this flag, but  object designers  would do well  to
  653. include it since it's easy to set and is potentially of great benefit to those
  654. VR systems which do make use of it.
  655.  
  656.       If a Base_facet  tag is specified, then  the current Facet is  a kind of
  657. "decal" that appears only on the surface of the Base_facet.  If the Base_facet
  658. is not visible (i.e.,  is backfacing or completely clipped) then no processing
  659. needs to  be done on  the current Facet.   The current  Facet is  always drawn
  660. immediately  after its  Base_facet; no  additional sorting  is required.   The
  661. Base_facet must be defined prior to being referenced.
  662.  
  663.       The Normal3D tag, if  specified, contains a vector perpendicular  to the
  664. plane of the Facet  and pointing outward  from the "front" of  the Facet.   It
  665. need not be a unit vector.
  666.  
  667.       A minimal Facet might look like this:
  668.  
  669.             Facet
  670.                   {
  671.                   Vertex_data
  672.                         {
  673.                         Count { 5 }
  674.                         Vertex_info { Index { 3 } }
  675.                         Vertex_info { Index { 2 } }
  676.                         Vertex_info { Index { 8 } }
  677.                         Vertex_info { Index { 7 } }
  678.                         Vertex_info { Index { 5 } }
  679.                         }
  680.                   Front_material { 7 }
  681.                   }
  682.  
  683.       This would define a  5-sided Facet, using vertices 3, 2, 8, 7 and 5.  It
  684. would use Material number 7 in an Object's Material_table; if  the Object does
  685. not have a Material_table, the Material_table  for the Shape is used.   If the
  686. Shape has no Material_table either, then the Object is invisible.
  687.  
  688.       In  a very  simple  system (fixed  256-color  palette, no  lighting,  no
  689. Material_tables  at runtime,  etc) then  the Front_material  would be  used to
  690. index an array  of bytes  that contain  the offsets  into the  palette of  the
  691. various colors.
  692.  
  693.       Note that edge information is not explicitly stored in the file, but can
  694. easily be derived for those systems that require it.
  695.  
  696.  
  697.                                                                             12
  698.  
  699.  
  700.  
  701.  
  702.  
  703. Objects
  704.  
  705.       An Object  consists of a pointer to a Shape, a specification of location
  706. and  orientation,  an  optional Material_table  and  other  information.   The
  707. complete format is:
  708.  
  709.             Object
  710.                   {
  711.                   Name { STRING }
  712.                   Identifier { ID }
  713.                   Instance_of_shape { ID }
  714.                   Scaled_by { REAL REAL REAL }
  715.                   Uses_material_table { ID }
  716.                   Location { REAL REAL REAL }
  717.                   Rotation { REAL REAL REAL }
  718.                   Attached_to { ID }
  719.                   Contained_within { ID }
  720.                   Is_invisible { BOOLEAN }
  721.                   Layer { NUM }
  722.                   Text { STRING }
  723.                   Facet_behind { ID }
  724.                   Application_handle { HANDLE }
  725.                   }
  726.  
  727.       The Instance_of_shape tag specifies the ID of the Shape this Object uses
  728. for its geometry information.  The Scaled_by tag specifies the scaling factors
  729. to be  applied to the basic  shape for this object in  each of the X,  Y and Z
  730. axes; if omitted, the values are  1,1,1.  The Location tag gives  the location
  731. in X, Y and  Z of the  origin of the  Object in world  coordinates, or in  the
  732. coordinate system of the Object it's  Attached_to (if any); the default  value
  733. is [0,0,0].  The Rotation  tag gives the angles of rotation around X,  Y and Z
  734. (although they are not performed in that order); the default is [0,0,0].
  735.  
  736.       The Attached_to tag  gives the ID of the Object to  which this Object is
  737. attached,  to establish  a hierarchy.   The  parent  Object should  be defined
  738. before its  children.  The  Contained_within tag  gives the ID  of the  Object
  739. inside  which  this Object  is contained;  the  container should  be specified
  740. before the contents.
  741.  
  742.       The Uses_material_table tag  references a Material_table  to be used  by
  743. this Object; this tag is optional, and if it's omitted then the material table
  744. from the Shape is used  instead.  If the  Shape has no material table  either,
  745. the Object should be invisible.
  746.  
  747.       The Is_invisible tag indicates  whether the Object  can be seen or  not.
  748. By default, all Objects are visible.  Another  way to make an Object invisible
  749. is to  omit its  Instance_of_shape tag;  this is  useful for grouping  Objects
  750. together, or  for providing location  and orientation information  for Cameras
  751. and Lights that are not associated with a visible Object.
  752.  
  753.  
  754.  
  755.                                                                             13
  756.  
  757.  
  758.  
  759.  
  760.  
  761.       The Layer is simply a number, and the Text is simply a string; their use
  762. is application-dependent.  The Facet_behind tag is used as a hint for sorting;
  763. it specifies  the ID of an already-specified Facet on another Object, to which
  764. this Object should  be attached for purposes of visibility  determination.  If
  765. the Facet  is visible (i.e., not  backfacing), this Object is  drawn after the
  766. one the Facet belongs to; otherwise, this Object is drawn first.
  767.  
  768. Lights
  769.  
  770.       A world can contain any number of Lights; however, they should be listed
  771. in  order of  importance since  most systems  impose some  kind of  limit. The
  772. format of a Light is:
  773.  
  774.             Light
  775.                   {
  776.                   Name { STRING }
  777.                   Application_handle { HANDLE }
  778.                   Type { TYPE }
  779.                   Associated_with { ID }
  780.                   Color { COLOR }
  781.                   Hotspot { ANGLE }
  782.                   Falloff { ANGLE }
  783.                   Is_on { BOOLEAN }
  784.                   Casts_shadows { BOOLEAN }
  785.                   }
  786.  
  787.       The  Type  is  one  of  DIRECTIONAL,  POINT  or  SPOT;  the  default  is
  788. DIRECTIONAL.  The Associated_with tag contains the ID of the  Object that this
  789. Light  uses for position and  orientation information.   Remember that Objects
  790. can be  flagged as  being invisible,  and need  not specify  a Shape.   Lights
  791. default to being "on", and their color defaults to 1, 1, 1.
  792.  
  793.       The default value for the  Is_on tag is TRUE; it need  only be specified
  794. if the Light should  be off initially.   Most systems can  ignore most of  the
  795. information,  including  anything  related   to  shadows;  it's  included  for
  796. completeness, and for renderers  that precompute much of the  surface material
  797. information.
  798.  
  799. Cameras
  800.  
  801.       A world can contain any number of Cameras; the first Camera specified in
  802. the  file should be  active when the  world is  initialized.  The  format of a
  803. Camera is:
  804.  
  805.             Camera
  806.                   {
  807.                   Name { STRING }
  808.                   Application_handle { HANDLE }
  809.                   Field_of_view { ANGLE }
  810.                   Aspect_ratio { REAL }
  811.                   Associated_with { ID }
  812.  
  813.                                                                             14
  814.  
  815.  
  816.  
  817.  
  818.  
  819.                   Projection_type { TYPE }
  820.                   }
  821.  
  822.       The Field_of_view is measured horizontally; the Aspect_ratio can be used
  823. to  compute the  vertical field  of  view.   The default  Field_of_view is  45
  824. degrees,  and the  default  Aspect_ratio is  1.33.   The  Associated_with  tag
  825. specifies  which Object this Camera  is associated with;  the Camera uses that
  826. Object's location and orientation  information.  Remember that Objects  can be
  827. flagged as being  invisible, and need not specify a Shape.  A Camera without a
  828. visible   Object   should  still   use  an   invisible   Object  to   get  its
  829. location/orientation/attachment  information from.  The Projection_type is one
  830. of PERSPECTIVE or PARALLEL, the default being PERSPECTIVE.
  831.  
  832. Sounds
  833.  
  834.       A  world can contain any  number of sound sources, some  of which may be
  835. associated with specific Objects.
  836.  
  837.             Sound
  838.                   {
  839.                   Name { STRING }
  840.                   Application_handle { HANDLE }
  841.                   Associated_with { ID }
  842.                   Is_on { BOOLEAN }
  843.                   Volume { REAL }
  844.                   Sample_name { STRING }
  845.                   }
  846.  
  847. The  Associated_with tag is optional;  if present, the  Sound should appear to
  848. come from the Object with the specified ID.  The STRING in the Sample_name tag
  849. is mapped by a Map entry to a filename which sound data should be loaded from;
  850. that file will also contain type  and other information (such as sampling rate
  851. and bits per sample).
  852.  
  853. World Attributes
  854.  
  855.       In addition to Objects, Cameras, Lights  and Sounds, a virtual world may
  856. have a  large number of  properties.  The  following list provides  a starting
  857. point:
  858.  
  859.             World_attributes
  860.                   {
  861.                   Gravity_vector { REAL REAL REAL }
  862.                   Ambient_light { COLOR }
  863.                   Has_horizon { BOOLEAN }
  864.                   Sky_color { COLOR }
  865.                   Ground_color { COLOR }
  866.                   Fog_color { COLOR }
  867.                   Scale { REAL }
  868.                   }
  869.  
  870.  
  871.                                                                             15
  872.  
  873.  
  874.  
  875.  
  876.  
  877.       The Scale  is the number of  millimeters per "unit" of  distance in this
  878. world, and defaults  to 1.  Eventually, a Local_attributes  tag may be defined
  879. in  order to allow the  various attributes to vary from  place to place within
  880. the virtual world.
  881.  
  882. An Example
  883.  
  884.  
  885. // Three cubes, a camera and a light
  886.  
  887. Material { Identifier { 0x3A97 } Diffuse_color { 1 0 0 } }  // red
  888. Material { Identifier { 0x4873 } Diffuse_color { 0 1 0 } }  // green
  889. Material { Identifier { 0x9798 } Diffuse_color { 0 0 1 } }  // blue
  890.  
  891. Material_table
  892.        {
  893.        Identifier { 0x1C756 }
  894.        Count { 3 }
  895.        Material_reference { 0x3A97 }
  896.        Material_reference { 0x4873 }
  897.        Material_reference { 0x9798 }
  898.        }
  899.  
  900. Shape
  901.        {
  902.        // two red faces, two green faces, two blue faces
  903.        Identifier { 0x1234 }
  904.        Uses_material_table { 0x1C756 }
  905.        Is_convex { TRUE }
  906.        Vertex_list
  907.               {
  908.               Count { 8 }
  909.               Vertex { Point3d { 100 200 300 } }
  910.               Vertex { Point3d { 700 200 300 } }
  911.               Vertex { Point3d { 700 800 300 } }
  912.               Vertex { Point3d { 100 800 300 } }
  913.               Vertex { Point3d { 100 200 900 } }
  914.               Vertex { Point3d { 700 200 900 } }
  915.               Vertex { Point3d { 700 800 900 } }
  916.               Vertex { Point3d { 100 800 900 } }
  917.               }
  918.        Facet_list
  919.               {
  920.               Count { 6 }
  921.               Facet
  922.                      {
  923.                      Front_material { 0 }
  924.                      Vertex_data
  925.                            {
  926.                            Count { 4 }
  927.                            Vertex_info { Index { 3 } }
  928.  
  929.                                                                             16
  930.  
  931.  
  932.  
  933.  
  934.  
  935.                            Vertex_info { Index { 2 } }
  936.                            Vertex_info { Index { 1 } }
  937.                            Vertex_info { Index { 0 } }
  938.                            }
  939.                      }
  940.               Facet
  941.                      {
  942.                      Front_material { 1 }
  943.                      Vertex_data
  944.                            {
  945.                            Count { 4 }
  946.                            Vertex_info { Index { 2 } }
  947.                            Vertex_info { Index { 6 } }
  948.                            Vertex_info { Index { 5 } }
  949.                            Vertex_info { Index { 1 } }
  950.                            }
  951.                      }
  952.               Facet
  953.                      {
  954.                      Front_material { 1 }
  955.                      Vertex_data
  956.                            {
  957.                            Count { 4 }
  958.                            Vertex_info { Index { 6 } }
  959.                            Vertex_info { Index { 7 } }
  960.                            Vertex_info { Index { 4 } }
  961.                            Vertex_info { Index { 5 } }
  962.                            }
  963.                      }
  964.               Facet
  965.                      {
  966.                      Front_material { 2 }
  967.                      Vertex_data
  968.                            {
  969.                            Count { 4 }
  970.                            Vertex_info { Index { 4 } }
  971.                            Vertex_info { Index { 7 } }
  972.                            Vertex_info { Index { 3 } }
  973.                            Vertex_info { Index { 0 } }
  974.                            }
  975.                      }
  976.               Facet
  977.                      {
  978.                      Front_material { 2 }
  979.                      Vertex_data
  980.                            {
  981.                            Count { 4 }
  982.                            Vertex_info { Index { 7 } }
  983.                            Vertex_info { Index { 6 } }
  984.                            Vertex_info { Index { 2 } }
  985.                            Vertex_info { Index { 3 } }
  986.  
  987.                                                                             17
  988.  
  989.  
  990.  
  991.  
  992.  
  993.                            }
  994.                      }
  995.               Facet
  996.                      {
  997.                      Front_material { 0 }
  998.                      Vertex_data
  999.                            {
  1000.                            Count { 4 }
  1001.                            Vertex_info { Index { 5 } }
  1002.                            Vertex_info { Index { 4 } }
  1003.                            Vertex_info { Index { 0 } }
  1004.                            Vertex_info { Index { 1 } }
  1005.                            }
  1006.                      }
  1007.               }
  1008.        }
  1009.  
  1010. // Now that we've defined the shape, let's instance it three times
  1011.  
  1012. Object { Instance_of_shape { 0x1234 } Location { 0 0 0 } }
  1013.  
  1014. Object { Instance_of_shape { 0x1234 } Location { 1000, 0, 2000 } }
  1015.  
  1016. Object { Instance_of_shape { 0x1234 } Location { 1000, 1000, 3000 } }
  1017.  
  1018. // And finally, here are the light and the camera
  1019.  
  1020. Object { Name { "lightsource" } Identifier { 0x9012 } Location { 0 0 0 } }
  1021.  
  1022. Object { Identifier  { 0x5678 } Location { -1000 -1000 -1000 } Rotation { 0.25
  1023. 0.25 0 } }
  1024.  
  1025. Light { Associated_with { 0x9012 } }
  1026.  
  1027. Camera { Associated_with { 0x5678 } }
  1028.  
  1029.  
  1030. Some Closing Notes
  1031.  
  1032.       This  is a  late-stage draft  of the  standard, and  is not  expected to
  1033. change significantly.   Any comments regarding this document should be sent to
  1034. Bernie Roehl (broehl@uwaterloo.ca).
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.                                                                             18