diff --git a/panda/src/doc/eggSyntax.txt b/panda/src/doc/eggSyntax.txt index 322413806b..d1c60b1ceb 100644 --- a/panda/src/doc/eggSyntax.txt +++ b/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 -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, and 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, and are lexically the same and both + can represent either a string or a number. is being phased + out; it is suggested that new egg files use only . @@ -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. name { filename [scalars] } @@ -90,10 +124,9 @@ appear before they are referenced. separate 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. envtype { environment-type } @@ -464,7 +498,7 @@ appear before they are referenced. supplied: - continuity-type { type } + 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 . + + At the present time, the DynamicVertexPool is not implemented in + Panda3D. @@ -603,9 +640,10 @@ GEOMETRY ENTRIES 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: - type { curve-type } + 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 " continuity-type { type }" within the + defined with a " continuity-type { type }" within the 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 name { group-body } - A node is the primary means of providing structure to the egg - file. Groups can contain vertex pools and polygons, as well as + A 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 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 + flag, below to avoid this). In addition, the following entries can be given specifically within a node to specify attributes of the group: @@ -954,26 +994,18 @@ GROUPING ENTRIES { 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-type } - - This is another syntax for the 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. - { 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 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. - - 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. 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. - 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. - - 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. - 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. 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 { Polyset descend solid }. See - the description of the "solid" property, above. - - turnstile - - This is equivalent to { Polyset descend turnstile }. See - the description of the "turnstile" property, above. - trigger This is equivalent to { Polyset descend intangible }. The geometry defined at this root and below defines an invisible trigger surface. - eye-trigger - - Equivalent to { 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 { Sphere keep descend }. A collision bubble is placed around the geometry, which is otherwise unchanged. - missile - - Equivalent to 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 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-definition } @@ -1311,8 +1274,13 @@ GROUPING ENTRIES This is particularly useful in conjunction with a entry, to load external file references at places other than the origin. + A special syntax of 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: name { { 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 ( and entries - are optional, and default as shown): + bundles, or any one of the following ( entries are optional, + and default as shown): name { fps { 24 } @@ -1391,8 +1359,8 @@ GROUPING ENTRIES name { fps { 24 } - order { sphrt } - contents { ijkabcphrxyz } + order { sphrt } + contents { ijkabcphrxyz } { values } } @@ -1421,7 +1389,7 @@ GROUPING ENTRIES name { fps { 24 } - order { sphrt } + order { sphrt } i { ... } 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.