

  
                             3D Foundation Classes



                             *** INTRODUCTION ***



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



           Introduction

           Component Architecture
           
           Basic Elements

           Files Format



      --------------
       Introduction
      --------------



           Here are general information about 3DFC.
           
           
           A more detailed information about 3DFC classes can be found
           
           at the beginning of the source files.
           
           
           Note: there is only the implementation of
           
           one C++ class per CC file.



      ------------------------
       Component Architecture
      ------------------------


           
           The basic scenery data structure is an OBJECT.
           
           
           Every thing in scenery is an object: the scenery,

           you (camera), other visible things,...

           Objects can has many things inside it self. Each of

           this things compose one object feature and are
           
           called COMPONENT.

           
           The object has free SLOTS that can be filled by components.

           The scenery is one or more objects composed by a body with
           
           polygons and vertexes. The slot body can be filled by a
           
           polygon mesh.

           
           The camera is an object composed by a camera control
           
           system. The slot camera is filled by the camera system.

           
           Sure, because you don't control the scenery (like the
           
           camera) the slot camera, for the scenery object, is empty.

           See examples:


           One object example:


              Object----------------------------------------------+
              |                                                   |
              |  slot 1                                           |
              |  slot 2                                           |
              |  ...                                              |
              |  slot n                                           |
              |                                                   |
              +---------------------------------------------------+


           In true, slots are identified by names, for example

           SLOT_REFSYS_KB_CTRL (has camera control),
           
           SLOT_BODY (is the slot where the visible object body is):


              Object-----------------------------------------------+
              |                                                    |
              |  slot REFSYS_KB_CTRL                               |
              |  slot BODY                                         |
              |  ...                                               |
              |  slot n                                            |
              |                                                    |
              +----------------------------------------------------+


           Each slot can be filled by any component. Sure
           
           some combinations has bad results.


              Object------------------------------------------------+
              |                                                     |
              |  slot REFSYS_KB_CTRL -> component camera move       |
              |  slot BODY           -> component mesh         |
              |  ...                                                |
              |  slot n                                             |
              |                                                     |
              +-----------------------------------------------------+


           One possible scenery static object:


              Object------------------------------------------+
              |                                               |
              |  slot REFSYS_KB_CTRL -> empty                 |
              |  slot BODY           -> component mesh        |
              |  ...                                          |
              |  slot n                                       |
              |                                               |
              +-----------------------------------------------+


           One possible camera object:


              Object-----------------------------------------------+
              |                                                    |
              |  slot REFSYS_KB_CTRL -> component camera move      |
              |  slot BODY           -> component mesh  (if has a body!) 
              |  ...                                               |
              |  slot n                                            |
              |                                                    |
              +----------------------------------------------------+



      ----------------
       Basic Elements
      ----------------



           In many engines you has one object model that is used

           many times to draw all same objects. For example,

           exist one model for a cubic light source, that is

           used in many scenery rooms.


           3DFC has a close idea: general models that

           can be used to populate the scenerys.


           The general model is called DEFINE. The specific
           
           copy is called OBJECT.
           

           A DEFINE is a generic data store. Is used to store
           
           components (or models). It can has an object mesh or
           
           an light source, for example.
           
           
           An OBJECT is an instance of one or more DEFINES.

           OBJECTS are composed by _copyes_ of one or more DEFINES.


           OBJECTS and DEFINES are composed by components. The

           objects are just a copy for their defines components.


           Example - how one object is created by many defines:
              
              Define 1-----------------------------------+
              |                                          |
              |  slot REFSYS_KB_CTRL -> empty            |
              |  slot BODY           -> component mesh   |
              |  ...                                     |
              |  slot n                                  |
              |                                          |
              +------------------------------------------+
              
              Define 2-----------------------------------+
              |                                          |
              |  slot REFSYS_KB_CTRL -> component camera |
              |  slot BODY           -> empty            |
              |  ...                                     |
              |  slot n                                  |
              |                                          |
              +------------------------------------------+

           The result object:
              
              Object-------------------------------------+
              |                                          |
              |  slot REFSYS_KB_CTRL -> component camera |
              |  slot BODY           -> component mesh   |
              |  ...                                     |
              |  slot n                                  |
              |                                          |
              +------------------------------------------+


           You can't visualize the data stored in a DEFINE. For

           this, is needed instanciate one object that use this data.
           
           The instanciated OBJECT has a copy of the
           
           DEFINE data. DEFINES can be shared by multiple OBJECTS
           
           because their data are copied.


           Is possible specify what defines compose what objects

           using the scenery description linguage: TXE. The TXE

           specification is in file doc/txe-spec.txt



     --------------
      File Formats
     --------------



           3DFC suport many file formats to load bitmaps,

           scenery elements, palettes and general purpose data.

           The standard file separator is the UNIX separator: /.

           For each type of file 3DFC provide a class to

           manipulate it. Above follow the file types

           suported and the classes can be used to access.


            +-----------------------------+---------------+
            |                             |               |
            |           FILE TYPE         |    CLASS      |
            |                             |               |
            +-----------------------------+---------------+
            |                             |               |
            |  RAW (binary), text, ...    |    CFile      |
            |                             |               |
            |    (general purpose         |               |
            |  without specific format)   |               |
            |                             |               |
            +-----------------------------+---------------+
            |                             |               |
            |      remarked text          |   CFileRem    |
            |                             |               |
            |    (text file with /* */    |               |
            |     as coments simbols)     |               |
            |                             |               |
            +-----------------------------+---------------+
            |                             |               |
            |    PCX Z-Soft version 5     |   CFilePCX    |
            |  (with 256 colors palette)  |               |
            |                             |               |
            +-----------------------------+---------------+
            |                             |               |
            |             TXE             |   CFileTXE *  |
            |                             |               |
            |     (scenery elements       |               |
            |     description linguage)   |               |
            |                             |               |
            +-----------------------------+---------------+
            |                             |               |
            |             BPN             |     CBPN      |
            |                             |               |
            |   (store a neural network)  |               |
            |                             |               |
            +-----------------------------+---------------+
            |                             |               |
            |             LTB             |  CLightTable  |
            |                             |               |
            |     (store a light table)   |               |
            |                             |               |
            +-----------------------------+---------------+

            * see doc/txe-spec.txt to learn the TXE linguage
