

  
                             3D Foundation Classes



                       *** TXE Language Specification ***



     -------------------
      Table of Contents
     -------------------



           What is?

           Blocks

           Read

           Textures

           Palette

           Vertexes

           Polygons

           Portals

           Attributes

			  PolygonsLight

           Instances

           Start

			  LightTable

           Object

           Sector



     ----------
      What is?
     ----------



           TXE is the 3DFC script linguage. Can be used to describe
           
           the scenery, and other objects.

           
           Now you can define using TXE:

              - texture files to be used in scenery

              - palette to be used in scenery

              - vertexes

              - polygons

              - polygons attributes

              - portals

              - scenery sectors

              - view cameras

              - object instances

              - lights

           
           To separate each word, number or simbol can be

           used the characteres: ENTER, TAB, END-OF-LINE.

           The class that implement read of a TXE file is

           CFileTXE.


           TXE use the "/" as directory and file separator.



      --------
       Blocks
      --------



           The linguage use blocks of declarations for

           each data can be defined. Above follow

           all blocks and their use.


             BLOCK-TYPE     USE

             Read           load other TXE files

             Textures       load textures from PCX files

             Palette        load palette from PCX file

             Object         declare an object model

             Sector         declare an sector (sectors describe objects inside)

             Portal         define a portal to destin: object instance and sector

             Polygons       define sector or object polygons

             Vertexes       define sector or object vertexes

             Light          define object light parameters, not on 3DFC v0.0.2

             Attributes     define attributes for polygons

             Instances      declare an object instance

             Start          define engine initial parameters


           Some blocks only can be declared inside others. For example,

           Vertexes, only can be placed inside a Object or Sector block.



      ------
       Read
      ------



             Syntax:
             ------


                Read { file1 [file2 ...] }


             Remarks:
             -------


                Read a TXE file.
                
                
                file1 - the TXE to read
                
                
                After read continue processing

                the original TXE file. If inside file1 or

                file2, ... exists a reference to other files, the path

                of the other files, is relative to location of

                file1 or file2, respectively (see example below).

                A Read block can be placed only outside all other blocks.


             Example:
             -------


                Read {
                  data/textures.txe
                  data/opera.txe
                  data/room.txe
                }


                Read the files data/textures.txe, data/room.txe and

                data/opera.txe.

                If in room.txe you refer the file room100.txe

                automaticaly will be append to file room100.txe

                the path of file room.txe: data/room100.txe

                The same happens when loading other files (textures,...)



      ----------
       Textures
      ----------



             Syntax:
             ------


                Textures { ID file1 scaleX scaleY [...] }


             Remarks:
             -------


                Load a texture from a PCX file.

                
                ID     - the texture ID for internal identification

                file1  - the PCX where the texture is

                scaleX - scale the X coodernate for the loaded image to scaleX

                scaleY - scale the Y coodernate for the loaded image to scaleY


                If scaleX or scaleY are -1 the scale is not performed and the

                original size is not changed.

                A Textures block can be placed only outside all other blocks.
                

             Example:
             -------


                Textures {
                   1 marble.pcx 256 256
                  23 data/rock.pcx 128 128
                }



      ---------
       Palette
      ---------



             Syntax:
             ------


                Palette file


             Remarks:
             -------


                Load a 256 colors palette from a PCX file.

                
                file - the PCX where the palette is


                The palette can be used to reprogramm the VGA palette.

                A Palette block can be placed only outside all other blocks.
                

             Example:
             -------


                Palette rock.pcx



      ----------
       Vertexes
      ----------



             Syntax:
             ------


                Vertexes { x1 y1 z1  [x2 y2 z2 [...]] }


             Remarks:
             -------


                Declare a vertex.

                
                x1, y1, z1 - are the components of the vertex


                Vertexes only can be declared inside a sector or object

                block. The coordenates are relative to the parent reference

                system.

                A Vertexes block can be placed only inside an Object or
                
                Sector block.


             Example:
             -------


                Vertexes {
                   -10 70 30
                     4 10  0
                   -90 63 12
                }



      ----------
       Polygons
      ----------



             Syntax:
             ------


                Polygons { v1 v2 v3 [...] ; [...] }


             Remarks:
             -------


                Declare a polygon, defining what vertexes compose it.

                
                v1, v2, v3 - vertex indexes


                In 3DFC v0.0.2, each polygon can have up to 8 vertexes.

                The ";" is used to separate distinct polygons.

                Polygons only can be declared inside a sector or object

                block. The vertex indexes are acording the position in

                the Vertexes declaration block (the indexing start
                
                in zero).

                A Polygons block can be placed only inside an Object or
                
                Sector block.
                

             Example:
             -------


                Polygons {
                   3 4 2 ;
                   6 5 4 3 5 ;
                }


                Declare two polygons: one with 3 vertexes and other with

                5 vertexes.



      ---------
       Portals
      ---------



             Syntax:
             ------


                Portals { ndx1 ob1 se1 [ndx2 ob2 se2 [...]] }


             Remarks:
             -------


                Define the destin (object, sector) for a portal.

                
                ndx1 - the index of the polygon beeing defined

                ob1  - destin object ID (instance ID)

                se1  - destin sector ID inside object


                A Portal block can be placed only inside an Object or
                
                Sector block.

                Before the Portals block the polygons must be declared.


             Example:
             -------


                Portal {
                   43 8 3  /* polygon 43 has as destin: instance 8, sector 3 */
                }



      ------------
       Attributes
      ------------



             Syntax:
             ------


                Attributes { p c t ndx1 [<;>|<.. ndx2> [...] }


             Remarks:
             -------


                Define polygon attributes.

                
                p    - 0 - polygon is not a portal / 1 - it's a portal

                c    - collision detection type of test:
                       
                           0 - no test (crossable polygon)

                           1 - collison detection test only polygon plan

                           2 - collision detection test plan and if
                           
                               intersection point is inside the polygon.

                t    - texture ID, -1 if no texture

                ndx1 - index of the first polygon to aplly the attributes

                ndx2 - index of the last polygon to aplly the attributes


                The collision detection type can be made with:
                
                "plan collision detection" (type 1), the collision detection

                only test the distance between the camera and the polygon

                plan. The problem is, for example, with exist a portal

                sharing the same plan, the collision would be detected
                
                if the camera collide with the polygon or with the portal.

                "polygon collision detection" (type 2), is more slow than the

                other test, but the collision is detected with polygon
                
                precision, not only plan precission.
                
                If the attribute correspond only of one polygon use:

                ndx1 and follow by ";".

                If the attribute correspond of a range of polygons use:
                
                ndx1, follow by ".." and than ndx2.

                An Attributes block can be placed only inside an Object or
                
                Sector block.

                Before the Attributes block the polygons must be declared.
                

             Example:
             -------


                Attributes {
                   0 2 45 13 .. 19 /* polys 13 to 19: are not portals,
                                      the collision detection is with polygon
                                      precision, the texture ID is 45 */
                   1 0 -1 22 ;     /* poly 22 is a crossable portal, with no
                                      texture */
                }



      ---------------
       PolygonsLight
      ---------------



             Syntax:
             ------


                PolygonsLight { l ndx1 [<;>|<.. ndx2> [...] }


             Remarks:
             -------


                Define polygon light intensity (called light level).

                
                l    - the polygon light level, between 0 (dark) and
					 
					        1 (lighted). The values are in float range, default

							  is 1.

                ndx1 - index of the first polygon to aplly

                ndx2 - index of the last polygon to aplly


                If the light info correspond only of one polygon use:

                ndx1 and follow by ";".

                If the light info correspond of a range of polygons use:
                
                ndx1, follow by ".." and than ndx2.

                A PolygonsLight block can be placed only inside an Object or
                
                Sector block.

                Before the PolygonsLight block the polygons must be declared.
                

             Example:
             -------


                PolygonsLight {
                   0.5 3..59      /* polys 3 to 59: have half light power */
                   1   2 ;        /* poly has full light power */
                }



      -----------
       Instances
      -----------



             Syntax:
             ------


                Instances { i m o s
                
                            x y z
                            
                            ix iy iz
                            
                            jx jy jz
                            
                            kx ky kz
                            
                            c [...] }


             Remarks:
             -------


                Create an object instance.


                i - the instance ID (must be unique between all instances)

                m - source object model (how the instance will look)

                o - object instance where the instance is inside

                s - object sector where the instance is inside

                (x, y, z)    - instance positon

                (xi, yi, zi) - the initial base vector i

                (xj, yj, zj) - the initial base vector j

                (xk, yk, zk) - the initial base vector k

                c - creation method:

                       0 - use model data (share the model with many
                       
                           instances), not available on 3DFC v0.0.2

                       1 - copy model data to this instance (each instance

                           has its own data)
                

                An Instances block can be placed only outside all other
                
                blocks.

                Before define the Instances block the object models used must
                
                be declared.


             Example:
             -------


                Attributes {
                   10 4 15 3
                   100 0 0
                   1 0 0
                   0 1 0
                   0 0 1
                   1
                }



      -------
       Start
      -------



             Syntax:
             ------


                Start cam o s b


             Remarks:
             -------


                Define some initial parameters.


                cam - the instance ID that would be the camera (viewer)

                o   - object instance where the camera is inside

                s   - object sector where the camera is inside

                b   - background color, value between 0 and 255 defining
                 
                      the palette color to be used for frame buffer clear or
                      
                      -1 if don't need clear frame buffer. If the scenery is

                      completely rounded by polygons it's not necessary

                      clear the frame buffer.
                

                A Start block can be placed only outside all other blocks.

                Before define the Start block the instances must be declared.


             Example:
             -------


                Start 7 5 4 -1



      ------------
       LightTable
      ------------



             Syntax:
             ------


                LightTable file levels


             Remarks:
             -------


                Define the light table.


                file   - the light table file (recomend extension LTB)

                levels - number of light levels. If file can't be loaded

					          a new one is created using "levels" light levels.

								 The created light table is automaticaly saved with

								 the "file" as name.
                

                Is better place this block after Palette declaration.


             Example:
             -------


                LightTable demo.tbl 16  /* try load demo.tbl, is can't create
														 a light table with 16 levels and
														 save in file demo.tbl */



      --------
       Object
      --------



             Syntax:
             ------


                Object ID { [...] }


             Remarks:
             -------


                Define a object model.


                ID - object ID (must be unique between all objects)


                Inside a Object block can place the blocks: Vertexes, Light,

                Polygons, Portals, Attributes, Sector.

                The object model must be instanciated in an Instances.
                

             Example:
             -------


                Object 7 {
                   Vertexes {
                      -10 10 10
                       10 10 10
                       10 20 10
                   }

                   Polygons {
                       0 1 2 ;
                   }

                   Attributes {
                       0 0 5 0 ;
                   }
                }

                An Object block can be placed only outside all other blocks.



      --------
       Sector
      --------



             Syntax:
             ------


                Sector ID { [...] }


             Remarks:
             -------


                Define a sector model.


                ID - sector ID (must be unique between all sectors inside the
                
                     object model)

                
                Inside a Sector block can place the blocks: Vertexes, Light,

                Polygons, Portals, Attributes.

                A Sector block can be placed only inside an Object block.
                

             Example:
             -------


                Object 5 {
                
                   Sector 2 {
                      Vertexes {
                         -10 10 10
                          10 10 10
                          10 20 10
                      }

                      Polygons {
                          0 1 2 ;
                      }

                      Attributes {
                          0 0 5 0 ;
                      }
                   }
                }
