3D version 0.45                                            dec 1997
<<preliminary>>

Contents:
-  The programs 3D and Win3D
-  The format of files DAT
-  The internal data structure

--------------------------------------------------------------------
-  The programs 3D and Win3D
--------------------------------------------------------------------
Introduction
------------
This program renders a 3D scene on your 2D monitor. The 3D scene is
described by a text file which specify the objects in 3D space.
You can move in the scene, store your position or record
a path by using the appropriate shortcuts.
There are two version of this program: the first for DOS, called 3D.EXE
and the second for WINDOWS, called WIN3D.EXE

Keyboard commands
-----------------
  Movement

  forward           up arrow key
  backward          down arrow key
  turn right        right arrow key
  turn left         left arrow key
  go up             shift + up arrow key
  go down           shift + down arrow key

  Controls

  save position     S
  load position     L
  record path       R
  play path         P
  exit              ESC (DOS version)

DOS Version
-----------
Program: 3D.PAS
Units used by program: GRAPH3D, DATA3D, FILE3D, VGA256, PROLINEA

  Syntax of the program 3D
  ------------------------
    3D [/16 | /256 | /BW] filename

    /16:  mode 16 colors     (VGA/EGA)
    /256: mode 256 colors    (direct access to memory)
    /BW:  mode grayscale     (direct access to memory)
    filename: file DAT


  System requirement
  ------------------
  CPU:   386+387 or better
  VIDEO: VGA o SVGA
  RAM:   1M

WINDOWS Version
---------------
Program: WIN3D.PAS
Units used by program: GRAPH3D, DATA3D, FILE3D, WVGA256, PROLINEA

  System requirement
  ------------------
  CPU:   486 or better
  VIDEO: VGA o SVGA
  RAM:   4M

--------------------------------------------------------------------
File DAT
--------
The file DAT contains the description of 3D objects.
The object may be either simple or structured.
Simple objects may be either wireframe or faceted.
The materials and the lights present in the scene are defined
in the same file DAT.

It is possible to define types of objects that can be used to
define many objects different in position, scale and rotation. (typedef)

The directive #include can be used to include other files.

It is possible to define the global properties of the scene. (global)
Comments should start with the character '.

--------------------------------------------------------------------
RULES FOR FILES DAT
-------------------
  o  All the elements that will be added in the future 
     according to the following syntax:
     <keyword> '{' contents... '}'

     In this way it is possible to have backward-compatibility.

     Generic syntax used by 3D:

     3DL::=[ [def identifier] entity ]*
     entity::=type_entity '{' [parameter_type parameter_value]* '}'
     type_entity::=<<missing>>
     parameter_type::=<<missing>>
--------------------------------------------------------------------
Examples
--------
  Programs    Description
  --------    -----------
  TEST1.PAS   demo with 4 bouncing spheres (uses TEST1.DAT)
  TEST2.PAS   interactive demo: you can throw an object against
              other objects by using the space bar, but you cannot
              go through other objects.
  ELICA.PAS   creates a file DAT that defines an helix.
  NEWDAT.PAS  creates a file DAT that defines an emisphere.

  Files DAT   Description
  ---------   -----------
  3D.DAT      simple example
  A.DAT e     example with inclusion of other files
  ADEF.DAT 
  TEST1.DAT   used by TEST1.PAS
  COLORS.DAT  object lighted by different colored lights
  FXY.DAT     math function
  ELICA.DAT   helix
  GEAR.DAT    esempio con poligoni concavi
  TEST.DAT    used by TEST.PAS
  CUBO.DAT    a cube with holes
  THING.DAT   a thing...

  COLOR.DAT   contains the definition of basic materials

--------------------------------------------------------------------
PROBLEMS & LIMITATIONS
----------------------

  o  Comparing real numbers is sometimes critical, specially when we
     compare the result of an expression with 0.
     (as an emergency solution we use the costant EPSILON)

  o  Boundary surfaces should be plane. The program does not check
     this condition!

  o  Objects in the scene should be included in not overlapping spheres.
     Anyway the programs works under more general conditions.

  o  The routine <sup_visibile> does not work when all the vertex
     of a polygon are external to the video screen but the
     polygon is visible.

  o  The routine <PointIsIncluded> is based on the sphere that contains
     the object. This does not work well with narrow objects, like
     cylinders.
     The function <DetectCollision> has the same limit.

  o  The statements 'scale' e 'rotation' are partly implemented.
     scale [x y z] assumes that z=y=x
     rotation [a b c] assumes that b=0 and c=0

  o  It is impossible to tilt the view.

  o  The programs does not handle shadows. The lighting model is very
     simple. Materials are very simple. Mirrors are not available.

  o  When all the vertex of a polygon are not visible, but the internal
     part of the polygon is visible, the clipper implemented now
     does not draw the visible part of the polygon.

--------------------------------------------------------------------
Structure of the program 3D (DOS VERSION)
-----------------------------------------

        +---------+  +---------+  +---------+
        | PROLINEA|  | DATA3D  |  | VGA256  |
        +-------+-+  +-+--+--+-+  +-+-------+
                |      |  |  |      |
                V      V  |  V      V
               +--------+ | +---------+
               | FILE3D | | | GRAPH3D |
               +------+-+ | +-+-------+
                      |   |   |
                      V   V   V
                     +---------+
                     |    3D   |
                     +---------+

FILE3D:  Read a file DAT checking its completeness. Creates the
         data structure needed to  represent the 3D scene.
GRAPH3D: Handle the 3D rendering.
DATA3D:  Define basic types and common procedures.
VGA256:  DOS graphic interface with resolution 320x200, 256 colors.
PROLINEA: Parser used to read line-oriented text files.

--------------------------------------------------------------------
-  The format of files DAT
--------------------------------------------------------------------
File DAT
--------
<<preliminary>>

     description_3D::=[ statement_3D | directive | 'global' '{' global_list '}' ]*
       statement_3D::=[('typedef'|'def') identifier] element_3D
       element_3D::='structure' '{' [ statement_3D | identifier ]* '}' |
                    transform |
                    list_vertex3 |
                    material |
                    light |
                    class

         list_vertex3::='coordinate3 '{' 'point' '[' x y z [',' x y z]* ']' '}'
         transform='transform' '{'
                          ['translation' '[' x y z ']'                |
                           'rotation' '[' angolo1 angolo2 angolo3 ']' |
                           'scale' '[' scala_x scala_y scala_z ']' ]*  '}'

         class::='IndexedLineSet' '{' 'coordIndex' list_spezzate '}' |
                 'IndexedFaceSet' '{' 'coordIndex' list_surfaces '}'
           list_spezzate::= '[' spezzata  [ ',' spezzata ]* ']'
           list_surfaces::= '[' surface [ ',' surface ]* ']'
             spezzata::=k [ m ]*
             surface::=k [ m ]*

         material::='material' '{' [ 'diffuseColor' color]
                                   [ 'emissiveColor' color]
                                   [ 'specularColor' color] '}'

         light::='DirectionalLight' '{' 'color' red blue green
                                        'direction' x y z'}'

       global_list::=['sky' color ][ 'ground' color]
         color::=red blue green

       directive::='#include' '"' file_to_include '"'

Symbols:
       scala_x, scala_y e scala_z are real numbers
       angolo1 e angolo2 are in radiants
       x,y,z are the real coordinates of a point in the space
       k,m,n are non negative integers
       red,blue,green are not negative reals less or equal to 1

       * stands for repetition

       Comments must start with the character '

       Note: 'def' defines a name associated to an active entity
             'typedef' defines a name associated to an inactive entity


--------------------------------------------------------------------
-  The internal data structure
--------------------------------------------------------------------
<<missing>>
