TheCloud/panda3d
1
0
Fork 0
mirror of https://github.com/panda3d/panda3d.git synced 2025-10-03 02:15:43 -04:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
David Rose 2004-11-27 19:07:35 +00:00
parent fd2caab93f
commit e623fb293e
1 changed files with 101 additions and 135 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
panda/src/doc/eggSyntax.txt
View File

@ -1,14 +1,45 @@
THE PHILOSOPHY OF EGG FILES (vs. bam files)
Egg files can, naturally, describe many properties of a scene: simple
geometry, including special effects and collision surfaces, characters
including skeletons, morphs, and multiple-joint assignments, and
character animation tables. Traditionally the scene descriptions,
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 used by Panda3D to describe many properties of a scene:
simple geometry, including special effects and collision surfaces,
characters including skeletons, morphs, and multiple-joint
assignments, and character animation tables.
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
evolved, <Scalar> and <Char*> are lexically the same and both can
represent either a string or a number.
attribute. Because of a syntactic accident with the way the egg
syntax evolved, <Scalar> and <Char*> are lexically the same and both
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
the directory in which the current egg file was found. If no
directory prefix is specified, the current egg file's directory is
searched first, and then $PFPATH is searched.
If the filename is a relative path, the current egg file's directory
is searched first, and then the texture-path and model-path are
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
TRILINEAR
MIPMAP_POINT
MIPMAP_LINEAR
MIPMAP_BILINEAR
MIPMAP_TRILINEAR
ADD_DETAIL
MODULATE_DETAIL
NEAREST_MIPMAP_NEAREST
LINEAR_MIPMAP_NEAREST
NEAREST_MIPMAP_LINEAR
LINEAR_MIPMAP_LINEAR
There are also some additional filter types that are supported for
historical reasons, but each of those additional types maps to one
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
variable egg-suppress-hidden is set to true, the primitive is not
converted at all; otherwise, it is converted as a "stashed" node.
is not generated as a normally visible primitive. If the
Config.prc variable egg-suppress-hidden is set to true, the
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
file. Groups can contain vertex pools and polygons, as well as
A <Group> node is the primary means of providing structure to the
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
it the responsibility of the show code to perform the switching.
If an fps scalar is defined and is nonzero, the egg loader creates
a pfSequence node instead, which automatically cycles through its
the group (see below), the egg loader creates a SwitchNode, and it
the responsibility of the show code to perform the switching. If
an fps scalar is defined and is nonzero, the egg loader creates a
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.
<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.
indicates a SwitchNode should be created instead.
<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
specified, it enables fade-LOD, and specifies the distance over
which to fade between this level of detail and the next-closer
one.
further than "out" units, from the camera. "fade" is presently
ignored.
<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
are optional, and default as shown):
bundles, or any one of the following (<Scalar> entries are optional,
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 }
<Char*> contents { ijkabcphrxyz }
<Scalar> order { sphrt }
<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
file was found. If no directory prefix is specified, the current
egg file's directory is searched first, and then $PFPATH is
searched.
which case the current egg file's directory is searched first, and
then the model-path is searched.