update fully from DWD to Panda3D--remove old pf references and unused syntax descriptions

panda/src/doc/eggSyntax.txt

@@ -1,14 +1,45 @@
+THE PHILOSOPHY OF EGG FILES (vs. bam files)
 
-Egg files can, naturally, describe many properties of a scene: simple
+Egg files are used by Panda3D to describe many properties of a scene:
-geometry, including special effects and collision surfaces, characters
+simple geometry, including special effects and collision surfaces,
-including skeletons, morphs, and multiple-joint assignments, and
+characters including skeletons, morphs, and multiple-joint
-character animation tables.  Traditionally the scene descriptions,
+assignments, and character animation tables.  
-character descriptions, and animation tables have been stored in three
-different kinds of egg files (and, in the old player, parsed by
-different egg loaders, which didn't even accept the same syntax); this
-distinction is no longer as important.  There is only one egg loader,
-and a single egg file can contain elements of all three.
 
+Egg files are designed to be the lingua franca of model manipulation
+for Panda tools.  A number of utilities are provided that read and
+write egg files, for instance to convert to or from some other
+modeling format, or to apply a transform or optimize vertices.  The
+egg file philosophy is to describe objects in an abstract way that
+facilitates easy manipulation; thus, the format doesn't include
+information such as polygon connectivity or triangle meshes.  Egg
+files are furthermore designed to be human-readable to help a
+developer diagnose (and sometimes repair) problems.  Also, the egg
+syntax is always intended to be backward compatible with previous
+versions, so that as the egg syntax is extended, old egg files will
+continue to remain valid.
+
+This is a different philosophy than Panda's bam file format, which is
+a binary representation of a model and/or animation that is designed
+to be loaded quickly and efficiently, and is strictly tied to a
+particular version of Panda.  The data in a bam file closely mirrors
+the actual Panda structures that are used for rendering.  Although an
+effort is made to keep bam files backward compatible, occasionally
+this is not possible and we must introduce a new bam file major
+version.
+
+Where egg files are used for model conversion and manipulation of
+models, bam files are strictly used for loading models into Panda.
+Although you can load an egg file directly, a bam file will be loaded
+much more quickly.
+
+Egg files might be generated by outside sources, and thus it makes
+sense to document its syntax here.  Bam files, on the other hand,
+should only be generated by Panda3D, usually by the program egg2bam.
+The exact specification of the bam file format, if you should need it,
+is documented within the Panda3D code itself.
+
+
+GENERAL EGG SYNTAX
 
 Egg files consist of a series of sequential and hierarchically-nested
 entries.  In general, the syntax of each entry is:
@@ -55,9 +86,10 @@ nesting only.
   names are meaningful in different contexts.  The value is either a
   numeric or a (quoted or unquoted) string value; the interpretation
   as a number or as a string depends on the nature of the named
-  attribute.  Because of a syntactic accident with the way Egg
+  attribute.  Because of a syntactic accident with the way the egg
-  evolved, <Scalar> and <Char*> are lexically the same and both can
+  syntax evolved, <Scalar> and <Char*> are lexically the same and both
-  represent either a string or a number.
+  can represent either a string or a number.  <Char*> is being phased
+  out; it is suggested that new egg files use only <Scalar>.
 
 
 
@@ -78,7 +110,9 @@ appear before they are referenced.
   is the same as Z-up-right.)
 
   By convention, this entry should only appear at the beginning of the
-  file.  If it is omitted, Y-up is assumed.
+  file, although it is technically allowed anywhere.  It is an error
+  to include more than one coordinate system entry in the same file.
+  If it is omitted, Y-up is assumed.
 
 
 <Texture> name { filename [scalars] }
@@ -90,10 +124,9 @@ appear before they are referenced.
   separate <Texture> entry is the only way to specify anything other
   than the default texture attributes.
 
-  The filename may be a relative path, in which case it is relative to
+  If the filename is a relative path, the current egg file's directory
-  the directory in which the current egg file was found.  If no
+  is searched first, and then the texture-path and model-path are
-  directory prefix is specified, the current egg file's directory is
+  searched.
-  searched first, and then $PFPATH is searched.
 
   The following attributes are presently implemented for textures:
 
@@ -134,16 +167,17 @@ appear before they are referenced.
     This specifies the type of filter applied when minimizing or
     maximizing.  Filter-type may be one of:
 
-      POINT
+      NEAREST
       LINEAR
-      BILINEAR
+      NEAREST_MIPMAP_NEAREST
-      TRILINEAR
+      LINEAR_MIPMAP_NEAREST
-      MIPMAP_POINT
+      NEAREST_MIPMAP_LINEAR
-      MIPMAP_LINEAR
+      LINEAR_MIPMAP_LINEAR
-      MIPMAP_BILINEAR
+
-      MIPMAP_TRILINEAR
+    There are also some additional filter types that are supported for
-      ADD_DETAIL
+    historical reasons, but each of those additional types maps to one
-      MODULATE_DETAIL
+    of the above.  New egg files should use only the above filter
+    types.
 
   <Scalar> envtype { environment-type }
 
@@ -464,7 +498,7 @@ appear before they are referenced.
     supplied:
 
 
-    <Char*> continuity-type { type }
+    <Scalar> continuity-type { type }
 
     This has meaning for a Bezier curve only.  It indicates the type
     of continuity that should be forced for the given CV: cut, free,
@@ -485,6 +519,9 @@ appear before they are referenced.
   multiple characters.  Each dynamic vertex pool creates a DynVerts
   object within the character by the same name; this name is used
   later when matching up the corresponding <VertexAnim>.
+
+  At the present time, the DynamicVertexPool is not implemented in
+  Panda3D.
   
 
 
@@ -603,9 +640,10 @@ GEOMETRY ENTRIES
   <Scalar> visibility { hidden | normal }
 
     If the visibility of a primitive is set to "hidden", the primitive
-    is not generated as a normally visible primitive.  If the Configrc
+    is not generated as a normally visible primitive.  If the
-    variable egg-suppress-hidden is set to true, the primitive is not
+    Config.prc variable egg-suppress-hidden is set to true, the
-    converted at all; otherwise, it is converted as a "stashed" node.
+    primitive is not converted at all; otherwise, it is converted as a
+    "stashed" node.
 
     This, like the other rendering flags alpha, draw_order, and bin,
     may be specified at the group level, within the primitive level,
@@ -699,7 +737,7 @@ surfaces.  Non-player tools, however, may respect them.
 
   The following attributes may be defined:
 
-  <Char*> type { curve-type }
+  <Scalar> type { curve-type }
 
     This defines the semanting meaning of this curve, either XYZ, HPR,
     or T.  If the type is XYZ, the curve will automatically be
@@ -723,7 +761,7 @@ surfaces.  Non-player tools, however, may respect them.
   entries do not apply to Bezier vertices.
 
   Each control vertex may optionally be given a continuity type,
-  defined with a "<Char*> continuity-type { type }" within the
+  defined with a "<Scalar> continuity-type { type }" within the
   <Vertex> entry.  The type may be one of Cut, Free, G1, or Smooth.
   This enforces the respective continuity restriction on the
   neighboring vertices.
@@ -910,10 +948,12 @@ GROUPING ENTRIES
 
 <Group> name { group-body }
 
-  A <Group> node is the primary means of providing structure to the egg
+  A <Group> node is the primary means of providing structure to the
-  file.  Groups can contain vertex pools and polygons, as well as
+  egg file.  Groups can contain vertex pools and polygons, as well as
   other groups.  The egg loader translates <Group> nodes directly into
-  pfGroup nodes in the scene graph.  In addition, the following
+  PandaNodes in the scene graph (although the egg loader reserves the
+  right to arbitrarily remove nodes that it deems unimportant--see the
+  <Model> flag, below to avoid this).  In addition, the following
   entries can be given specifically within a <Group> node to specify
   attributes of the group:
 
@@ -954,26 +994,18 @@ GROUPING ENTRIES
   <Global> { boolean-value }
 
     These two attributes are lexically equivalent, and indicate that
-    this group begins a character.  An xpfCharacter node will be created
+    this group begins a character.  A Character node will be created
     for this group.
 
-  <Dart> { dart-type }
-
-    This is another syntax for the <Dart> flag.  The dart-type string
-    should be one of either "async" or "sync".  This tells the egg
-    loader to optimize the character for asynchronous or synchronous
-    animation, respectively.  In the absence of this dart-type, the
-    egg loader will choose the most general.
-
   <Switch> { boolean-value }
 
     This attribute indicates that the child nodes of this group
     represent a series of animation frames that should be
     consecutively displayed.  In the absence of an "fps" scalar for
-    the group (see below), the egg loader creates a pfSwitch node, and
+    the group (see below), the egg loader creates a SwitchNode, and it
-    it the responsibility of the show code to perform the switching.
+    the responsibility of the show code to perform the switching.  If
-    If an fps scalar is defined and is nonzero, the egg loader creates
+    an fps scalar is defined and is nonzero, the egg loader creates a
-    a pfSequence node instead, which automatically cycles through its
+    SequenceNode instead, which automatically cycles through its
     children.
 
 
@@ -981,15 +1013,9 @@ GROUPING ENTRIES
 
   <Scalar> fps { frame-rate }
 
-    This specifies the rate of animation for a pfSequence (created
+    This specifies the rate of animation for a SequenceNode (created
     when the Switch flag is specified, see above).  A value of zero
-    indicates a pfSwitch should be created instead.
+    indicates a SwitchNode should be created instead.
-
-  <Scalar> no_fog { boolean-value }
-
-    This specifies that geometry at or below this node should not be
-    affected by fog.  It will be created with the appropriate GeoState
-    to have fog disabled.
 
   <Scalar> bin { bin-name }
 
@@ -1011,23 +1037,6 @@ GROUPING ENTRIES
     true, the primitives are not converted at all; otherwise, they are
     converted as a "stashed" node.
 
-  <Scalar> write_through { boolean-value }
-
-    If this is present and boolean-value is non-zero, it places the
-    geometry at this level and below in a special drawing bin that is
-    drawn first and with the z-buffer set to write-through.  This is
-    an optimization to avoid the initial screen clear when rendering a
-    completely enclosed scene; the flag should be set on the enclosing
-    geometry, which must be convex.
-
-  <Scalar> post_lp { boolean-value }
-
-    If this is present and boolean-value is non-zero, it places the
-    geometry at this level and below in a drawing bin that is drawn
-    after everything else in the scene, including light points.  This
-    must be done particularly for semitransparent geometry which must
-    not obscure light points.
-
   <Scalar> decal { boolean-value }
 
     If this is present and boolean-value is non-zero, it indicates
@@ -1083,10 +1092,8 @@ GROUPING ENTRIES
     level of detail for a particular model.  Sibling nodes represent
     the additional levels of detail.  The geometry at this node will
     be visible when the point (x, y, z) is closer than "in" units, but
-    further than "out" units, from the camera.  If "fade" is
+    further than "out" units, from the camera.  "fade" is presently
-    specified, it enables fade-LOD, and specifies the distance over
+    ignored.
-    which to fade between this level of detail and the next-closer
-    one.
 
 
   <Collide> name { type [flags] }
@@ -1153,29 +1160,6 @@ GROUPING ENTRIES
       collision surface; create both an invisible collision surface
       and the visible geometry.
 
-    solid
-
-      This has meaning only when the type is Polygon or Polyset.  This
-      creates the polygon(s) as "solid" polygons, meaning no mover is
-      allowed to occupy the space immediately behind them.  In the
-      absence of this flag, once a mover passes completely through a
-      polygon it is considered no longer intersecting with it.
-
-    center
-
-      Sets the collide-center property on the collision solid, so that
-      it collides with the center point of each mover, disregarding
-      the mover's radius.  This implies "solid".
-
-    turnstile
-
-      Sets the turnstile property on the collision solid, so that
-      movers approaching from behind the solid will smoothly pass
-      through instead of being forcefully yanked to the front.  This
-      is intended to implement a one-way wall, through which players
-      can go forwards but not back.  Presently, this is only
-      implemented for planes, polygons, and polysets.
-
     level
 
       Stores a special effective normal with the collision solid that
@@ -1200,42 +1184,18 @@ GROUPING ENTRIES
       geometry defined at this root and below defines an invisible
       collision solid.
 
-    solidpoly
-
-      This is equivalent to <Collide> { Polyset descend solid }.  See
-      the description of the "solid" property, above.
-
-    turnstile
-
-      This is equivalent to <Collide> { Polyset descend turnstile }.  See
-      the description of the "turnstile" property, above.
-
     trigger
 
       This is equivalent to <Collide> { Polyset descend intangible }.
       The geometry defined at this root and below defines an invisible
       trigger surface.
 
-    eye-trigger
-
-      Equivalent to <Collide> { Polyset descend intangible center }.
-      This defines a trigger polygon whose point of collision is the
-      center of the mover; presumably this polygon will be used to
-      trigger visibility events.
-
     bubble
 
       Equivalent to <Collide> { Sphere keep descend }.  A collision
       bubble is placed around the geometry, which is otherwise
       unchanged.
 
-    missile
-
-      Equivalent to <Collide> missile { Sphere keep descend event }.  The
-      geometry defined at this root and below defines a missile
-      object, which will be surrounded by a collision sphere and named
-      "missile".
-
     ghost
 
       Equivalent to <Scalar> collide-mask { 0 }.  It means that the
@@ -1247,8 +1207,11 @@ GROUPING ENTRIES
       This has no equivalent; it is treated as a special case.  It
       means that the geometry at this node and below should not be
       translated.  This will normally be used on scale references and
-      other modelling tools.
+      other modeling tools.
 
+    There may also be additional predefined egg object types not
+    listed here; see the *.pp files that are installed into the etc
+    directory for a complete list.
 
   <Transform> { transform-definition }
 
@@ -1311,8 +1274,13 @@ GROUPING ENTRIES
   This is particularly useful in conjunction with a <File> entry, to
   load external file references at places other than the origin.
 
+
   A special syntax of <Instance> entries does actually create shared
-  geometry in the scene graph.  The syntax is:
+  geometry in the scene graph.  However, please note that this special
+  syntax is not supported by Panda3D at this time.  It is documented
+  here against the day that it will be supported.
+
+  The syntax is:
 
 <Instance> name {
   <Ref> { group-name } 
@@ -1377,8 +1345,8 @@ GROUPING ENTRIES
   the tree as a whole.
 
   Bundles may only contain tables; tables may contain more tables,
-  bundles, or any one of the following (<Scalar> and <Char*> entries
+  bundles, or any one of the following (<Scalar> entries are optional,
-  are optional, and default as shown):
+  and default as shown):
 
   <S$Anim> name { 
       <Scalar> fps { 24 }
@@ -1391,8 +1359,8 @@ GROUPING ENTRIES
 
   <Xfm$Anim> name {
       <Scalar> fps { 24 }
-      <Char*> order { sphrt }
+      <Scalar> order { sphrt }
-      <Char*> contents { ijkabcphrxyz }
+      <Scalar> contents { ijkabcphrxyz }
       <V> { values }
   }
 
@@ -1421,7 +1389,7 @@ GROUPING ENTRIES
 
   <Xfm$Anim_S$> name {
       <Scalar> fps { 24 }
-      <Char*> order { sphrt }
+      <Scalar> order { sphrt }
       <S$Anim> i { ... }
       <S$Anim> j { ... }
       ...
@@ -1462,8 +1430,6 @@ MISCELLANEOUS
   The extension ".egg" is implied if it is omitted.
 
   As with texture filenames, the filename may be a relative path, in
-  which case it is relative to the directory in which the current egg
+  which case the current egg file's directory is searched first, and
-  file was found.  If no directory prefix is specified, the current
+  then the model-path is searched.
-  egg file's directory is searched first, and then $PFPATH is
-  searched.