readme.txt

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

			PANARD VISION
			  3D Realtime Portable Engine

                        SDK 0.95

-------------------------------------------------------------------------
DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT DRAFT
------------------------------------------------------------------------

Opening words
-------------

I release linkable libraries for Panard vision, but of course I've got no
time for writing docs right now :)  I'm really sorry of this.
What you are readding now is far from a draft of a doc but it may enlight
some details and concepts, maybe not.

So I release source of the 3DSVIEW program and sources of the 3DStudio 
drivers (for reading meshes and animations). You should look in these
sources like a tutorial. They are pretty straight forward to understand.
In my opinion all the Panard Vision API is pretty simple. Of course
look in pvision.h.

Don't look for classes, this API is not Object Oriented, maybe one day I will 
encapsulate everything in some nice classes, but when I see the result with 
Direct3D's API ...... It's not planned yet :)

If you want an interface with Java, you're on your own :)

If you code interesting drivers for popular formats (LightWave, Alias or so...)
drop me a line.



DON'T FORGET : This is the first public release of this lib. Hence it's very
likely buggy in some ways. If you find some "undocumented features" please 
contact me (see end of this text). API is subject to changes in future release.


PV is designed for fast processors with fast floating point operations.



---------------------------------------------------------
Panard Vision
---------------------------------------------------------

Usage
-----

It's very simple, include "pvision.h" (eventually 3dsread.h if you plan to use
3DS file, compile, and link with pvision.lib. That's it :)
See included makefiles to see how it is simple.


Working modes
-------------
Panard vision support different working modes. The mode flag is a bit 
field. 
Modes are selected by PV_SetMode()

Options are:

PVM_PALETIZED8      
PVM_RGB16           
PVM_RGB             

     OR

PVM_SBUFFER         
 
     OR

PVM_MIPMAPPING      

PVM_PALETIZED8 is used to generate paletized output (up to 256 colors)
PVM_RGB16 is used to generate 15 or 16 bits images, but coloured lights 
          are ignored (assumed to be white). The textures used for
	  lighted materials *MUST* be 256 colors
PVM_RGB is used to generate true RGB (15,16,24,32 bits) output

These 3 flags are exclusive, you must only specify one of them, and you 
*MUST* set one of these flag before the material compilation (see below)
and not change it after.

You can add PVM_SBUFFER to render from front to back, faster when 
pixel overdraw is important.

You can add PVM_MIPMAPPING to enable MipMapping on mipmapped materials.

Cameras handling
----------------

You can create as much camera as you want, but only one at a time is 
active. You can change active camera by PV_SetCurrentCam(). 
A camera isn't linked with a world, ie you can render two world with
the same camera.

A texture (PVTexture struct)
----------------------------
typedef struct _Texture
{
    unsigned Width,Height;
    unsigned ShiftHeight,ShiftWidth;
    UPVD8 *Texture;
} PVTexture;

Nothing to say here. Just use the API to set each public field (Width, Height and Texture) in order
to maintain Shift???? fields valid.

AND REMEMBER TEXTURES MUST HAVE THEIR SIZE A POWER OF 2 (256*64 but not 53*8)

A material (PVMaterial struct)
-----------------------

typedef struct _BumpInfo
{
    PVD8 nx,ny;
}PVBumpInfo;

typedef struct _BumpMap
{
    unsigned Width,Height;
    PVBumpInfo *Map;
} PVBumpMap;

typedef struct _Mat
{
    char *Name;
    PVFLAGS Type;

    unsigned char NbrMipMaps;
    PVFLAGS TextureFlags;
    RGB *Pal;
    PVTexture *Tex;

    PVTexture AuxiliaryTexture;

    PVBumpMap BumpMap;

    UPVD8  StartingColorIndex,EndingColorIndex;           // for pure colors

    RGBF Diffuse,Specular,Emissive;
    unsigned SpecularPower;

    UPVD8 *PaletteTranscodeTable;
    UPVD16 *RGB16TranscodeTable;

    RGBF Color;

    PVD32 UserData;                                       // Used to handle special FX by users routines

    struct _Mat *Next;
} PVMaterial;

A material is a rendering type, a shading type, a name, eventually a Primary Texture, eventually
an ambiant texture, eventually a BumpMap.

The main thing to understand is the flags used to set rendering and shading type.
Avialable flags are listed in pvision.h.
By example you can combine flags like this: GOURAUD|MAPPING to obtain a surface with a texture 
gouraud shaded.
These flags are stored in the 'Type' field.

NbrMipMaps is the number of desired mipmaps foir this texture (ignored if the MIPMAP flag is not
present in the 'Type' field) by default it's 4.

TextureFlags indicates the type of the texture provided by the user (Paletized or RGB 24 bits) the
Pal fields point to the palettte if the texture is not RGB.

Color, indicates the color of the materials (in non-mapped modes).

UserData, is left to the user wishes.

Don't forget to set an unique name for each material in a world ! This name will be used to attach 
faces to this material during the mesh compilation.

You can also describe specular, diffuse, emissive coefficient to obtain psychedelik materials.

StartingColorIndex and EndingColorIndexFields are used to when rebdering GOURAUD in paletized 
output mode, they indicates the starting color and ending color number of the ramp.

AuxiliaryTexture is used in AmbiantMapping, it's the light texture.
BumpMap is the bump map for BUMP enabled materials (use PV_BuildBumpMap())

Aviallable combination for the Type field are:

(in fake 16 bits modes, PVM_RGB16)

FLAT|NOTHING
PHONG|NOTHING
BUMP|NOTHING

NOTHING|MAPPING
FLAT|MAPPING
GOURAUD|MAPPING
BUMP|MAPPING
PHONG|MAPPING

NOTHING|PERSPECTIVE_MAPPING
FLAT|PERSPECTIVE_MAPPING
GOURAUD|PERSPECTIVE_MAPPING
BUMP|PERSPECTIVE_MAPPING
PHONG|PERSPECTIVE_MAPPING

FLAT|AMBIANT_MAPPING
NOTHING|AMBIANT_MAPPING
GOURAUD|AMBIANT_MAPPING
PHONG|AMBIANT_MAPPING

REMEMBER!!!!! In fake 16 bits mode it's impossible to use texture with
more than 256 colors when using shaded modes. But it's possible when
using not shaded modes.
ie FLAT|MAPPING                 ---> Texture MUST be 256 colors
   NOTHING|PERSPECTIVE_MAPPING  ---> Texture could be 256 colors or more


(in 8 bits modes, ie 256 color modes (PVM_PALETIZED8))

FLAT|NOTHING
GOURAUD|NOTHING
PHONG|NOTHING
BUMP|NOTHING

FLAT|MAPPING
NOTHING|MAPPING
GOURAUD|MAPPING
BUMP|MAPPING
PHONG|MAPPING

FLAT|PERSPECTIVE_MAPPING
NOTHING|PERSPECTIVE_MAPPING
GOURAUD|PERSPECTIVE_MAPPING
BUMP|PERSPECTIVE_MAPPING
PHONG|PERSPECTIVE_MAPPING

FLAT|AMBIANT_MAPPING
NOTHING|AMBIANT_MAPPING
GOURAUD|AMBIANT_MAPPING
PHONG|AMBIANT_MAPPING

(in full RGB modes, PVM_RGB)

FLAT|NOTHING
GOURAUD|NOTHING
PHONG|NOTHING

NOTHING|MAPPING
FLAT|MAPPING
GOURAUD|MAPPING

NOTHING|PERSPECTIVE_MAPPING
FLAT|PERSPECTIVE_MAPPING
GOURAUD|PERSPECTIVE_MAPPING

NOTHING|AMBIANT_MAPPING
FLAT|AMBIANT_MAPPING
GOURAUD|AMBIANT_MAPPING

The flags names are pretty self explanatory, but PHONG is not really
phong shading, but a FakePhong using a kind of environement mapping.
Phong does not take into account lights in the scene, instead the phong
light is positionned at the camera position.

PERSPECTIVE_MAPPING  is  an  affine  mapping  corrected every 16 pixels.
BUMP  mapping  rely  on  FakePhong  shading  and  hence  has  the   same
limitations.

When  using  the  PERSPECTIVE_MAPPING  flag,  you  can add the AUTOMATIC
flag, in this case the engine  will try to determine if the  perspective
correction is needed for each  polygons. Works not very well,  but could