3dsview.doc

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

                           3DSVIEW DOCUMENTATION FILE
                            (C) 1997, SMKaribou/GMF

----------------------------------------------------------------------------
 BETA BETA BETA BETA BETA BETA BETA BETA BETA BETA BETA BETA BETA BETA BETA
----------------------------------------------------------------------------


I/ What is 3DSVIEW
------------------

  The first purpose of this program is to render 3DStudio file in real-time
(more or less real depending on machines :) including animations.
  But, behind this, this is a demo of the Panard Vision 3D realtime engine.
  This engine will be released in a very near future (see at the end for
pointers).
  Sources of 3DSView will be available very soon too.
  Look at http://www.efrei.fr/~bruneto/pvision/ for more informations and
news


Ibis) Machine Specific Informations
-----------------------------------

ALL SYSTEMS

3DSVIEW automatically adds some coloured lights in the scene just for fun.


DOS

UNIVBE or a VESA BIOS v2.0+ is required for this version to operate. There
is no support for banked modes.


XWINDOW

On XWindow systems (including Linux and XFree) the rendering mode (paletized
or DirectColor) cannot be set by 3DSVIEW, it's determined by the X server. If
you want to start the X server in color table mode try :
        startx -- -bpp 8   (this is often the default when you launch startx
                            without parameters)

to start in RGB mode 16 bits try:
        startx -- -bpp 16     (in this mode it is assumed that the pixel format
                               is 5-6-5, if you have an efficient way to determine
                               what is the right pixel format, please contact me)

to start in RGB mode 32 bits try:
        startx -- -bpp 32     (the pixel format is assumed to be 8-8-8-8)

In all case Red component is first, green second and blue last. It seems that
24 bits modes are *NOT* supported by X-Servers :( (if you have infos,
contact me !)

Under X-System, if you are in DirectColor Modes you *MUST* specify either -r
(fast 16 bits, monochromatic lights) or -z (true RGB) options. Of course -r
is only valid in 16 bits modes.

WARNING: I never tried myself 32 bits on a XServer, but reports said :
'It doesn't work'.

II/ How to use 3DSVIEW
----------------------

3DSVIEW [options] filename.3ds filename.3ds ...

  Available options on command line are:

      -xnnn and -ymmm:  used to specify horizontal and vertical resolution
                        in pixel. By example -x640 -y480.
                        On a not windowed system (ie DOS) the resoltion must
                        match an existing video mode on the video card.

      -f file        :  used to specify a material definition file different
                        from 'material.def'. (see below for a description)

      -r             :  Use fake 16bits rendering mode. Your adapter must
                        support 16 bits display, but you will not be able to
                        render coloured lights (the color attribute of each
                        light will be ignored, and considered as white).
                        Used to be fast but *REALLY* beautifuler than
                        standard 256 colors mode.
                        WARNING: In this mode, it's not possible to have something
                        else than a 256 color texture on a material which is lighted.
                        (see material definitions for details).

      -z xx          :  Used to render in full RGB mode (ie with coloured lights)
                        xx specify number of bits to use (15, 16, 24 or 32).
                        Slow but beautiful.
                        NOTE: On X-Systems there is no need for the xx option,
                        it's determined by the X-Server.

      -a              : Play animation of the 3ds file, instead of letting
                        the user moving around.
                        WARNING ! This option must be specified *BEFORE* the
                        first 3ds file.
                        ex: 3dsview -a test.3ds zob.3ds    is valid
                            3dsview test.3ds -a zob.3ds    is not

      -t              : Enable TV mode. Not really unforgettable.

DOS Specifics options:
      -d              : disable double buffering
      -v              : disable vbl synchro
      -l              : List all available VESA video modes on your machine.
                        NOTE: Display Doctor (formerly known as Univbe) highly
                              recommended.

Keys:
        1,7           : go ahead and go back according to the camera direction.
        o,p
        a,q
        z,s           : rotate camera around.

        j             : activate front to back drawing
        m             : activate mipmapping on textures with the TEXTURE_MIPMAP
                        attribute. see below.

        n             : Back to normal mode. reset m and j.

        x,c           : move one of the lights.
        d,e           : play with ambiant light.

        4,6,2,8       : move camera position around BUT the camera target is set
                        to 0,0,0. I recomend not using these keys :)

        esc           : guess

WARNING:
        These keys are given for a QWERTY keyboard. Azerty keyborads change
        some of them, just try all your keys :)
        On X-Window systems, it seems to be quite ok.

        You may have trouble to see what changes are done (by example the F
        and G keys), this is because screen is refreshed only when objects
        are moving. To be sure, just move the camera after a modification
        (ex: type 1 after pressing G).


III/ Material definition file
-----------------------------

  The 3DStudio driver does NOT load materials recorded in a 3ds file. Instead
you have to define each material you want to use. A typical definition follows:

MATERIAL MY$MARBLE
  GOURAUD|MAPPING

  0.7 0.2 0.3
  0 0 0
  1 1 1
  0 0 0
  40

  TEXTURE_PALETIZED8
  art\plouf.raw
  null

  The first line begins with the keyword MATERIAL which introduces a material
name (note: all spaces in materials names MUST be replaced by the $
character. ie 'MY$MARBLE' stands for 'MY MARBLE').
Then follows type of the material (SHADING_TYPE|RENDERING_TYPE). It can be
one of the following combinations:

(in fake 16 bits modes, -r option)

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, no specific options)

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, -zxx option)

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
be useful.
ie:  FLAT|PERSPECTIVE_MAPPING|AUTOMATIC