readme.txt

一个高性能的3D游戏引擎源代码

be useful.
ie:  FLAT|PERSPECTIVE_MAPPING|AUTOMATIC


Camera (PVCam struct)
---------------------

typedef struct _Camera
{
    char *Name;
    float fieldofview;
    unsigned Height,Width;
    float roll,pitch,yaw;
    float xscreenscale,yscreenscale,fscale;
    Point pos;
    Point target;
    Mat3x3 Matrix;                // [0][x]=vright [1][x]=vup [2][x]=vpn
} PVCam;

nothing special here, see 3dsview.c for ideas. The important thing to remenber is to correctly
setup Height,Width and fieldofview according to suit your eyes :)

A camera has 2 positionning system. One wich is based on the camera position and the 
camera's target position (pos and target field) and one wich is based on position and roll, 
pitch yaw. Choose one of these methods and use the appropriates API functions PV_SetCamAngles or 
PV_SetCamTarget. See 3dsview for side-effects when using them simultaneously.

Lights (PVLight struct)
-----------------------

typedef enum _PVLightType {PVL_DIRECTIONAL,PVL_PARALLEL,PVL_INFINITEPOINT,PVL_POINT,PVL_SPOT,PVL_USER_LIGHT} PVLightType;

#define LIGHT_NORMAL 0
#define LIGHT_FORGET 1                  // Switch off the light

typedef struct _TLight
{
    char *Name;
    PVLightType Type;
    PVFLAGS Flags;
    RGBF Color;
    float Intensity;
    float Range;
    float Attenuation0,Attenuation1,Attenuation2;
    float FallOff,Theta,Phi;
    float cosTh,cosPh;
    Point Position;
    Point Direction;
    Point Target;
    struct _TLight *Next;
    void *UserData;
} PVLight;

Very straight forward here. Color field is ignored when not in PVM_RGB mode.
Flags is used to switch off/on lights.

Meshes (PVMesh struct)
----------------------

typedef struct _PVMesh
{
        char *Name;
        PVFLAGS Flags;
        unsigned int NbrFaces,NbrVertexes,NbrVisibles,NbrBoxes;
        Point Pivot;

        char *VertexVisible;
        unsigned nbrclipf,nbrclipv;          // Nombre de faces clipp俿
        PVClippedFace *ClippedOrg;           // pt originaux

        Point OldPos,OldPosv,Pos;
        Mat3x3 OldMatrix,OldMatrixv,Matrix;
        float ScaleX,ScaleY,ScaleZ;

        PVVertex *Vertex;
        PVFace *Face;

        PVMapInfo *Mapping;

        Point         *Rotated;
        PVScreenPoint  *Projected;

        PVFace          **Visible;

        PVShadeInfo *Shading;

        PVBox         *Box;

        void        *UserData;

        struct _PVMesh *Next;
} PVMesh;

[QUICK EXPLANATION MODE ON]

Main fields are: 
ScaleX,ScaleY,ScaleZ, wich are the scaling factors 
to apply to the object regarding the original size (the original mesh
is NOT modified however).

Pivot : which is the pivot point coordinates (center of rotation)
Pos   : which indicates the position of the mesh in the world
Matrix : which is the rotation matrix applied to the mesh (the original mesh
is NOT modified however)..

For other infos see 3DStudio readers.

[QUICK EXPLANATION MODE OFF]

World (PVWorld struct)
----------------------
typedef struct _PVWorld
{
    unsigned     NbrFaces,NbrVertexes,NbrVisibles;
    unsigned     NbrObjs;

    RGBF AmbiantLight;

    PVMaterial *Materials;

    PVFace    **Visible;

    PVMesh *Objs;
    PVLight *Lights;

    UPVD8 ReservedColors;
    RGB *Global256Palette;
} PVWorld;

[QUICK EXPLANATION MODE ON]

AmbiantLight: color of the ambiant light
Global256Palette: When in PVM_PALETIZED8 mode, quantized palette used to 
		  render world.
ReservedColors: When in PVM_PALETIZED8 mode, number of color left 
		to the user at the beginning of Global256Palette.

[QUICK EXPLANATION MODE OFF]

Hierarchy
---------

World
  |
  |------ Lights
  |
  |------ Ambiant Light
  |
  |------ Materials
  |	   |--- Render flags
  |        |--- Textures
  |------ Meshes
	   |
	   |--- Bouding Boxes
	   |--- Faces
	   |--- Vertexes
	   |--- Normals

When you create a world you need to create meshes, material, Lights and attach all these object to
the world (see 3dsread.c to see how it is done).

Once everything is created and linked, you need to 'compile' meshes and materials.


Application skeleton:
---------------------
* World, camera creation
* camera assignation
* mesh creation
* materials creation
* Set RGB modes
* Set PV working mode
* mesh compilation
* material compilation
* enjoy!
* Garbage collection and world destruction



Mesh compilation
----------------

This phase creates links beetwen the 'MaterialName' of each face, and the material which have the same
name in the material list of the world. This set up the 'Filler' field of each face to the adress
of the routine which will handle the correct rendering. The selection is done with the flags 
affected to the material (FLAT|MAPPING by example).

Material Compilation
--------------------

This phase converts material's texture to a format suitable for fast rendering according to the 
value of PVMode (PV_SetMode()), the value fixed by PV_SetRGBIndexingMode() and the ReservedColors 
field in the world struct.
It also computes MipMaps on mipmapped materials.

After these two steps you should *NOT* change one of the parameters linked with display (RGB pixel
format, Rendering Mode and so on).

This process could be very long, especially in paletized mode.

World Rendering
---------------

Very simple first call PV_ComputeWorld(MyWorld), and then PV_RenderWorld(MyWorld,MyBuffer) where 
MyBuffer must be big enough to handle the image rendered. MyBuffer could be the video memory.

Cleaning house
--------------

When finished with PV, destroy all the objects you created (Worlds and Cameras) and call 
PV_GarbageCollector() to free some more memory (rendering buffers allocated 'on fly' during
the rendering stage).
PV_GarbageCollector() could be called wherever you want but be warned that it could decrease 
performance if PV have to recreate the freeed buffers.

User defined lights & triangle filler
-------------------------------------

DOC TO BE DONE
just look at pvision.h for the flags & call back functions :)




---------------------------------------------------------
Panard Motion
---------------------------------------------------------

Usage
-----

include pmotion.h and 3dspm.h if you want to read anim from .3ds and link with pvision.lib.

Overview:
--------

PM is a basic hierarchical animation system.
PM is based on quaternions to interpolate angles in 3D-Space.
ease, cont bias and non linear stuffs are not yet implemented.

Details:
-------

See 3dspm.c :)


-----------------------------------------------------------------------
Contact & Infos
------------------

  - The code for the 3DStudio driver is heavily stolen from the code of
    JARE/IGUANA
  - Additional documentation for 3ds files are taken from
    'The Unofficial 3DStudio 3DS File Format' by Jeff Lewis
    ([e-mail])
  - Useful Help and hints from Adept/Esteem for 3ds ([e-mail])
  - and my brain.

If you find bugs, or have suggestions or just want to tell me what you
think of this, contact me.

You can contact me at:
        [e-mail] (Olivier Brunet)

or visit:
        http://www.efrei.fr/~bruneto/pvision  (Home of Panard Vision)



                                                        Olivier Brunet