README

Notes on the Autodesk Cyberspace Developer Kit 1.0.1
====================================================


INCOMPATIBILITIES
-----------------

IMPORTANT:  This release, CDK 1.0.1, is incompatible with release 1.0
in several areas, including displays, solids, and DSCVR.  To use this
new release, it is necessary to recompile any of your code that refers
to CDK header files.


HIGHLIGHTS OF THIS RELEASE
--------------------------

This is an update of CDK Release 1.0.  Some bugs have been fixed
(most notably in the SPEAdisp and VESAdisp display classes), and
some features added (particularly in the CDF reader).

Also, this release supports the MetaWare C++ compiler release 3.1, the
Phar Lap DOS Extender release 5.1, and the FTP Software release 2.2,
in addition to previously supported releases of these products.  The
Zortech C++ compiler release 3.0 is supported as well.

This README.TXT document also contains a complete summary of
environment variable settings needed for compilation and linking,
and for displays and sensors.


INSTALLATION
------------

The documentation discusses a cdk\drivers directory.  This directory
is not created by the install routine, nor is it necessary for the
user to create it.

The former \cdk\examples\conehead directory has been changed to
\cdk\examples\network.

For Spea or Division cards, follow the vendor's software installation
instructions.  Also perform the installation of the CDK Spea/Division
code from disk E1.  Then, for Spea, copy the file SPSERVER from its
installed location (default \vendor\spea) into the same directory as
the Spea GDC files such as GDCINI.DAT.  See also the section below on
Environment Variables for displays.


COMPILING AND LINKING
---------------------

The CDK currently supports the following compilers:

    MetaWare High C/C++ 3.03, 3.04, 3.1.  Problems with some early
    versions of 3.1 have been largely resolved with version 3.1@25.
    The version number is displayed by the compiler when it runs.
    If you experience difficulties with an early version of MetaWare
    3.1, you may need to contact MetaWare regarding an update.

    Zortech 386 C++ 3.0. (The CDK does not currently support Zortech
    3.1.)

The CDK currently supports the Phar Lap 386|DOS Extender SDK, versions
3.0, 3.1, 4.0, 4.1, and 5.1.  (The corresponding version of BUILD386
can optionally be used to make redistributable .EXE files.)

The CDK networking features now support FTP Software versions 2.05
through 2.2.


ENVIRONMENT VARIABLES
---------------------

The following sections describe the environment variables you  must
set for compiling and linking, and for use of sensors and displays in
the example programs provided with the CDK.  This supplements the
descriptions in the CDK Manual.

COMPILING AND LINKING

Set the following environment variables for compiling and linking.

    HEAD = CDK head directory;
    LINK = PharLap linker.

When used with the CDK, some debuggers work best in privileged mode.
If you have trouble running the debugger, set the LINKOPTS environment
variable as follows and rebuild your application:

    LINKOPTS = -PRIV

For PharLap 5.1:
    LINKOPTS = -BACKCOMPAT
    or, for debugging (see above), LINKOPTS = -BACKCOMPAT -PRIV

(The -BACKCOMPAT switch directs PharLap 5.1 to make .exp files, like
previous PharLap releases.)  For details of linker options, see the
Phar Lap documentation.)

For MetaWare:
    MWLIB = MetaWare library directory;
    PROFILE = MetaWare profile file. This is installed into the CDK
              root directory.

For Zortech:
    ZTCLIB = Zortech library directory.


DISPLAYS

When running the examples provided with the CDK, set the following
environment variables for displays.

 ( brackets [] denote optional parameters;
     braces {} denote alternatives)

ADI:
    DISPLAY={adidisp,CyADIdisp}
    RDPADI= Protected mode ADI Renderer driver
    ADICFG= directory where ADI configuration is stored.

SPEA: 

    DISPLAY={spea,CySPEAdisp}
    GDC= cdk\vendor\spea directory (directory containing the files
        SPSERVER and GDCINI.DAT)
    SPEAVM = Spea output video mode (an integer between 1 and 12;
        see page 515 of the CDK User's Guide for a table of
        video modes)
    SPEAFLAT = something (if set, all models will be flat shaded;
        if not, the Spea display will use Gouraud shading.
    SPEADIFF = something (if set, only diffuse lighting will be 
        enabled; if not, the Spea display will use specular 
        lighting).

Division:

    DISPLAY={dview,CyDViewdisp}
    DVVERSION={1,2,3} (1 for the old three-board set, 2 for the 
        new three-board set, and 3 for the two-board set.)
    DVBASE = cdk\vendor\dview\bin1 directory
    DVNUMEYES = {1,2} number of image boards in the system. (This
        is 2 when doing stereo rendering. It is, however, 
        possible to render only one image.) Default is 2.
    DVMEMSIZE = {4,16} The amount of memory on the card set. 
        Default is 4.
    LOFF = Left offset (a real number) See CDK User's Guide pg.305
        for a discussion of Division offsets and shifts.
    ROFF = Right offset (a real number)
    LSHIFT = Left Shift (a real number)
    RSHIFT = Right Shift (a real number)
    BACKGROUND = RED GREEN BLUE (where RED, GREEN, and BLUE are 
        real numbers between 0.0 and 1.0, inclusive). Default
        is black.

VESA: (Note: If you do not have a vesa driver installed, you will 
    be unable to load a display.)

    DISPLAY={vesadisp,CyVESAdisp}[,xres][,yres][,bits][,{f,q}]
            -or-
    DISPLAY={vesadisp,CyVESAdisp}[,mode mode_num][,{f,q}]

    Where xres and yres are integers representing the size of the
        VESA display (e.g. xres=640, yres=480), bits is an
        integer representing the depth of color in this 
        resolution, f represents a full-page display, q
        represents a quarter page display, and mode_num is
        the VESA mode number desired.

    Note: Some VESA drivers may return incorrect information about
        whether they support double-buffering. If your VESA display
        flashes, then you can set the environment variable
        "VESAVPAGE=on" and the CDK will do the buffering for the
        driver.


SENSORS

The example programs create sensors based on the information in the
    environment variables SENSOR1 and SENSOR2. Set them as needed,
    according to the examples below. The syntax is the same for all
    environment variable descriptions of sensors.
Below, SENSORN = {SENSOR1,SENSOR2,...} as appropriate; CySensor6d is
           the default.
       COMPORT = {COM1,COM2,COM3...} for the appropriate serial port.
       BAUD_RATE = {300,600,1200,2400,4800,9600,19200,38400} for the
           baud rate of the serial device.

Keypad:
    SENSORN = {keypad,CyKeypad6d}   (Unshifted, Unscrolled keypad)
                    -or-
    SENSORN = {shiftkeypad,CyShiftKeypad6d} (shifted, unscrolled)
                    -or-
    SENSORN = {scrollkeypad,CyScrollKeypad6d} (unshifted, scrolled)
                    -or-
    SENSORN = {scrollshiftkeypad,CyScrollShiftKeypad6d} 
                (shifted, scrolled)
                    -or-
    SENSORN = {shiftscrollkeypad,CyShiftScrollKeypad6d}
                (shifted, scrolled)

Sensor6d:
    SENSORN = {sensor6d,CySensor6d}

Sensor6d_2d:
    SENSORN = {sensor6d2d,CySensor6d_2d} [sensor2d 2DSENSOR]
        where 2DSENSOR is a string representing a 2d sensor.

MsMouse:
    SENSORN = {msmouse,CyMSMouse}

2d ADI Sensor:
    SENSORN = {sensadi2,CyADISensor2d}
    DGPADI = Proteced mode ADI digitizer driver
    ADICFG = directory where ADI configuration is stored.

6d ADI Sensor:
    SENSORN = {sensadi6,CyADISensor6d}
    DGPADI = Proteced mode ADI digitizer driver
    ADICFG = directory where ADI configuration is stored.

6d_2d ADI Sensor:
    SENSORN = {sensadi6_2}
    DGPADI = Proteced mode ADI digitizer driver
    ADICFG = directory where ADI configuration is stored.

Logitech Ltracker:
    SENSORN = {ltracker,CyLTracker} [port COMPORT] [baud BAUDRATE]

Polhemus Isotrak:
    SENSORN = {polhemus,CyPolhemus} [port COMPORT] [baud BAUDRATE]

CIS Dimension6 Geometry Ball:
    SENSORN = {geoball,CyGeoBall} [port COMPORT] [baud BAUDRATE]

Polhemus Fastrak:
    SENSORN ={fastrak,CyFastrak} [port COMPORT:NUM] [baud BAUDRATE]
    Where NUM is the sensor number {1,2,3,4}. 

Fake Space Labs Boom:
    SENSORN = {boom6d,CyBoom6d} [port COMPORT]


CHANGES TO CDK CLASSES AND FUNCTIONS
------------------------------------

AUDIO

CySequencer & CyMPU401:

    The Autodesk CDK provides two kinds of support for MPU-401
    compatible midi interfaces.  The CyMpu401 class is designed for
    low level, UART style access to the device and is useful for
    generating real-time "sound effect" midi events, as well as
    handling realtime midi event input. 

    A related class, CySequencer provides a simple 8-track midi song 
    playback capability.  The sequencer can read standard midi
    version 0 or 1 midi files, and can load multiple files
    simultaneously within the 8 track limit. The sequencer also
    passes through input and real-time midi events to the executable.

    CySequencer and CyMpu401 cannot be used simultaneously.   Only a
    single MPU401 device may be active at one time. 


CHOOSE_ FUNCTIONS

Source code for the choose functions (choose_display, choose_sensor
and choose_gfile) is provided in the cdk\examples\util directory.  We
recommend that you edit these functions, removing the headers (.hpp)
of any displays and/or sensors that will never be used.  Excluding the
#includes for these devices greatly reduces the size of executable
files produced using the CDK.

If these functions are changed, the new .obj files must appear in the
linker response files ahead of all of the CDK libraries.


DECK AND SPACE

CyCursor:

    Constructor no longer causes printout.

CyDeck, CyKeypad6d:

    ProcessFrame() function modified so that CyKeypad6d now works
    properly with modifier keys.


DISPLAYS

choose_display():

    now has an alternate mechanism for specifying a VESA display with
    a mode number in addition to the previous resolution and bitdepth
    specification.  See also Choose_ Functions, above.

CyDisplay3d:

    There is an undocumented method in class CyDisplay3d:

        virtual Bool DisplayOK()

        This method, which is overloaded by the derived classes, can
        be called to verify that the display instance has been
        initialized properly. 

    The CanDoSegments() function has been added:

        virtual Bool CanDoSegments()

        Returns TRUE if the display supports segments (i.e. is a
        "retained mode" display), otherwise FALSE.

    CyDisplay3d and derived classes CyADIdisp, CyDViewdisp, CySPEAdisp,
    CyVESAdisp now set the displaytype in their constructors or
    initialization code; CyDisplay3d deallocates it in its destructor.

    Some drawing methods (in CyLeaf) have been changed to support both
    retained-mode and non-retained-mode displays.

    Classes which you derive from CyDisplay3d should, in their
    constructor or initialization method, deallocate the displaytype
    string (if not null), and strdup() a string that is equivalent
    to their class name and assign it to the displaytype member.
    Derived classes should NOT deallocate the string in their
    destructor; CyDisplay3d does this.

CySPEAdisp:

    The SetBackFaceReject method has been added to the CDK library; it
    functions as described in the Manual for CyDisplay3d.

    The destructor now calls spend().

    The CDK Manual incorrectly states that the CySPEAdisp driver is
    capable of displaying CyLights of type CY_SPOT.  In addition, the
    board's firmware is capable of supporting only 32 material
    surfaces (colors).

    SetView(CyMatrix &m) does not correctly set the display's viewpoint.
    SetView( CyVertex3 &from, CyVertex3 &to, CyVector3 &up) does
    correctly set the display's viewpoint, and the following work-around
    can be used to set a CySPEAdisp's viewpoint from a matrix M:

    SetView(M.T(),M.T()-M.N(),M.V());


CyVESAdisp:

    _CyV prefix has been put on all vendor code symbols.

    CyVESAdisp::CyVESAdisp( int mode_number, CyVesaViewsize vs ) has
    been added.

    CyVESAdisp::CyVESAdisp( char *s ) has been added.

    "searching for alternate" and "couldn't find alternate" messages 
    have been removed from initialization code.

    CyVESAdisp now detects the VESA version of the display, and
    responds appropriately.

    A problem which could cause system hangups after using a VESA 1.0
    driver has been fixed.

    If two parallel planes were very close, a Z-buffering problem
    would sometimes cause the rear one to appear in front.  This has
    been improved, though it may still occur in some cases. 

    Redundant error messages in initialization have been suppressed.

    Default for vesa_bits is now 8.

    The CDK's driver for VESA compatible SVGA boards is VESA
    compliant.   Its functionality is dependent upon a driver supplied
    by the manufacturer of the board.  The CDK VESA driver has been
    thoroughly tested on a number of manufacturers' cards.  However,
    we cannot guarantee its functionality for all cards.  If you have
    trouble driving your SVGA card, contact the board's manufacturer
    for the latest version of their VESA driver.


DSCVR AND CDF

CDF maker:

    There are now CDF maker functions for CyMouseView and
    CyParasiteView, and for all solids except CySolFac.

    The CDF maker database entry for CySolCon now permits a
    specification of rtop or rbottom to be 0.

    Fixes to maker functions for CyPhysical, CySimObj, CySpring, and
    CyGravity.

    The keywords "color", "surf", and "surface" are all recognized,
    and have the same meaning, corresponding to the "surf" or
    "surface" parameter in the Manual.

    CDF specifiers for arguments to CDK classes now agree in
    spelling and type with their counterparts in the class
    documentation.

    The CDF is built on top of DSCVR.  Accordingly the CDF is "type
    safe" and no automatic casting occurs from ints to reals.  If a
    CDF maker function expects a real number, an int will not serve.
    Several of the built-in CDF maker functions will return an
    "Underspecified" error if an integer is substituted for a real.

CyCDFMgr:

    Process() is now more tolerant of spurious characters in input.

CyCstMgr:

    pLoadSpace() now loads specified viewers even if there are no
    simulated objects in the space.

CyDSCVRReader:

    ReadDSCVRFromFile() and ReadDSCVRFromString() no longer fail on
    the deletion of the last token.

CyValName:

    Fprint() now only prints double quotes around strings with spaces.


EXAMPLES

Example applications that take the name of a graphics file as an
argument expect the file name to have the extension .dxf or .3ds, as
appropriate; they will fail otherwise.

The "coneheads" example was removed from the distribution.

Three new network examples were added to the distribution.

tut:

    deck.cdf now handles VESAdisp and has VESAdisp as default.

cdfchain:

    deck.cdf has VESAdisp as default.
    main.cpp deletes display on exit.
    space.cdf wbball is now CySolRed.

monster:

    This program uses the PATHDXF environment variable, which must
    be set to point to the cdk\dxfs directory.

    The application now waits when changing back into graphics mode.

tut7:

    In order for this application to compile and link the environment
    variable ADSHEAD must point to the user's ACAD\ADS directory.  In
    addition, the original shipping version of AutoCAD R12 did not
    include ADS libraries for some current compilers.  These libraries
    are available on CompuServe as M30ADS.LIB (for MetaWare 3.0 or 3.1)
    and ZTCAD30.LIB (for Zortech 3.0).

    The "tut-7" ADS application can only be entered once from AutoCAD.
    If you wish to reenter it after quitting it in the same AutoCAD
    session, you must (xunload "tut-7") and reload it: (xload "tut-7").

vmodes:

    The "vmodes" utility program now uses a different mechanism to
    detect view modes.


GEOMETRY

CySolFac:

    The CySolFac class takes a CyRigidBody and turns it into a
    CySolid, upon which boolean operations can be performed.  Some
    modeling packages, including AME 1.0, can produce models that
    CySolFac is unable to process. 


IMPORT AND EXPORT

Export of objects with a distance policy has been modified to use the
representation currently being displayed.

CyGfile:

    The CyGfile class has the following virtual methods implemented
    that are not documented. 

        virtual CyDqueue& GetMaterialNames();
        virtual CyDqueue& GetMaterials();

    These methods will return the material names CyDqueue and the
    materials CyDqueue that are generated from a call to the Process
    method.  These methods are currently redefined for CyGFile3DS only.  


CyGfile3DS:

    Process() changed so that materials info is returned correctly.

CyGfileADS:

    Fix to export of rigid-motion matrix.

CyGfileDXF:

    Fix to export of rigid-motion matrix.

    Changes so that colors imported from r12 DXF files are exported
    correctly. 

    Exported angles are now converted from radians to degrees when
    appropriate.

    3D faces with only 3 vertices are now written out correctly.


LINEAR ALGEBRA

CyMatrix:

    RollPitchYaw method returns identity matrix if all arguments are 0.

    RollPitchYaw method sets translation terms to 0.


MISCELLANEOUS

Syntax or style changes have been made to event.hpp, geom.hpp,
linalg.hpp, and viewer.hpp.


NETWORK

The compiler and linker flags required for use of the Networking
classes differ slightly from other classes.  The following flags
are required (see also the makefiles for the networking examples):

    -realbreak rmend
    -callbufs 5


PHYSICS

CySpring:

    Simulate() - metric is only simulated if use_metric is set.

    Link() now mirrors CyGravity::Link().

Deriving from CyPhysics:

    The only requirement for a class derived from CyPhysics is that
    the derived class's Simulate method should inform the CyMetric
    about the current CyPhysics::frametime and run the
    CyMetric::Simulate method, if the derived class operates on pairs
    of objects (as do CySpring and CyGravity). This is not necessary
    if the derived class only operates on one CyPhysical object at a
    time (as do CyPGravity and CyFriction). 

    The following code is an example:

    void
    ClassXYZ::Simulate( void )
    {
        metric.SetNow(GetFrametime());
        metric.Simulate();

        // ClassXYZ does its thing from here on...
    }


SCHEDULING

Using the Deck and Space paradigm, your program must Read every sensor
once each Deck frame.  In general, sensors are read in the Simulate
method of a viewer, and are thus guaranteed to be read once per frame.
However, sensors not generally associated with viewers, such as gloves,
may not automatically be read each deck frame.  Failure to read a
sensor each frame can cause the serial port buffer to throw away bytes,
making communication with the device impossible.


VIEWERS

The documentation of the CyTrackerView class is incorrect.  There is
only one constructor.  Its syntax is:
 
    CyTrackerView(  CyVertex3& f, CyVertex3& t, CyVector3& u, 
                    CySimObj *so, CyDisplay3d *d, CySensor6d *s =
                    NULL) 
