//----------------------------------------------------------------------
// MetaVR, Inc. MetaDatabase - Extended (MDX) Write API 
// Copyright (C) 1997, 1998, 1999, 2000 MetaVR. All rights reserved. 
// URL: http://www.metavr.com 
// E-Mail: inquiries@metavr.com 
//----------------------------------------------------------------------
 
// The MDX Write API is a C++ class, which facilitates the generation of 
// visual databases for the MetaVR Virtual Reality Scene Generator (VRSG). 
// This specification can be freely distributed. Accompanying platform specific 
// object files require a non-disclosure agreement (NDA) that limits the 
// distribution of the binary files. Please contact MetaVR at 
// inquiries@metavr.com  for the object files for a given platform. Upon 
// completion of the NDA, any MDX databases created can be freely distributed 
// without restriction. 

// The Write API assumes the user is converting from another database format
// or from some other type of source data with which the user is familiar.  The
// Write API accepts convex polygons of an arbitrary number of verticies.

// The following outlines the database generation process:
//   1) Create an instance of the class Mdx
//   2) Invoke one of the overloaded methods "setTransformInfo" to set
//      the coordinate conversion parameters of the database
//   3) Set the database patch size via "setPatchSize".  This step is
//      optional and if not invoked, the patch size defaults to 500 meters.
//   4) Set the extents of the database in meters by invoking the
//      "setNorthExtent" and "setEastExtent" methods.
//   5) Invoke the "setupForStorage" method which prepares the Mdx object
//      to receive polygons
//   6) Store polygons into the database by calling the "storePolygon"
//      method.  Invoke this method for as many polygons as you wish to
//      store in the database
//   7) Write the MDX database to disk by invoking the "writeToDisk" method.
//      After this point, no other method calls are allowed and the database
//      generation process is complete.
//   8) Create a texture library for the database.  This is outlined in the
//      following section.

// Creating Texture Libraries:
// Each MDX database may have its own unique texture library.  A texture
// library must have the same name as the MDX database but with the .tlb
// extension.  Example: hunter.mdx would have a texture library hunter.tlb.
// Texture libraries are stored in the Textures directory and the .mdx 
// databases are stored in the Terrain directory.  Texture libraries are
// ASCII files and have the following syntax:
//
//      number-of-textures
//      texture1.bmp
//      texture2.rgb
//         .
//         .
//         .
//
// When polygons are stored into the Mdx, you must provide a texture ID for the
// polygon.  The texture ID is an integer in the range 0..N where there are
// N entries in the databases texture library (.tlb) file.  The value 0 is
// reserved for non-textured polygons.
// 
// The texture files referenced by the texture library file (.tlb) must
// be present in the Textures directory along with the texture library file.
// The VRSG supports IRIS RGB formats (*.rgb,*.rgba,*.int,*.inta) and Windows
// BMP formats.

#ifndef Mdx_h
#define Mdx_h

#include "MdxList.h"

// Polygons are given to the Write API as a list of instances of the MdxVertex
// data type.  The user is responsible for filling in all the fields of the 
// MdxVertex to include location (x,y,z), color (r, g, b), and texture 
// coordinates (u, v).

// X-Y-Zs are given in meters in a North-East-Down coordinate system which
// is relative to the Southwest corner of the database.  This coordinate
// system may be a UTM projection or a GCS tagent plane.  Vertices are input
// in the native coordinate system of the database (UTM or GCS), which is
// specified by the "setTransformInfo" method.

// Texture coordinates are in the range 0..1, values outside this range cause
// the texture to be repeated along the particular axis.  The U coordinate
// corresponds to the horizontal axis and the V coordinate corresponds to the
// vertical axis of the texture image.   The origin of the texture image
// (U=V=0.0) is the lower left corner and (U=V=1.0) is the upper right corner
// of the texture image.

// Color values are in the range 0..255 where 0 coresponds to minimum intensity
// and 255 corresponds to maximum intensity.

struct MdxVertex
{
    double    x;
    double    y;
    double    z;

    float     u;
    float     v;
 
    float     nx;
    float     ny;
    float     nz;

    unsigned char r, g, b, a;

    unsigned char clip;
    unsigned char mat;
};

// Polygons may contain an arbitrary number of verticies, but are assumed to
// be convex.  If a non-convex polygon is passed to the Write API, incorrect
// visual results are likely.

typedef MdxList<MdxVertex> MdxPolygon;

// Materials 

struct MdxMaterial
{
    float ambR;
    float ambG;
    float ambB; 
    float difR;
    float difG;
    float difB; 
    float speR;
    float speG;
    float speB;
    float emiR;
    float emiG;
    float emiB;
    float shine;
    float alpha;
};

// Forward declarations

struct MdxHeader;
class  MdxPatch;

class Mdx
{
public:

    // Ctors/Dtors

    Mdx();

    ~Mdx();

    //-------------------------------------------------------------------
    // Initialization methods

    // These must be invoked before any geometry is sent.  This method
    // informs the MDX that the vertex information is given in a UTM-Flat
    // Projection.  

    void setTransformInfo( int datum, int zone, double northing,
        double easting );

    // This method informs the MDX that the vertex information is given
    // in a GCS cartesion coord. system

    void setTransformInfo(
        double gccX,                  // Geocentric origin of cell
        double gccY,
        double gccZ,
        double offsetX,               // Northing offset from cell center
        double offsetY,               // Easting offset from cell center
        const double xform[3][3] );   // Geocentric -> NED transformation

    // Set the patch size of the database.  A reasonable heuristic is to 
    // have about 50 terrain triangles in a patch.  So an optimal value is 
    // a function of terrain posting resolution.  For DTED Level 1
    // 500 is a good number.

    void setPatchSize( double patchSize );

    // Set extent information

    void setNorthExtent( double northExtent );

    void setEastExtent( double eastExtent );

    // After all other initialization methods have been called, invoke
    // this method before sending any polygons to the Mdx object.  It will
    // return 1 if it is OK to begin polygon storage.  Otherwise, 0
    // will be returned indicating an error in the intialization steps.

    int setupForStorage();

    // End of initialization methods
    //----------------------------------------------------------------------

    // Store a polygon into the MDX.  The MDX will handle vertex
    // redundancy checking so the caller only needs to supply explicit 
    // geometry.  The polygon is assumed to be convex.  Non-convex
    // polygons will produce unknown and likely incorrect results.  The
    // polygon will be clipped against database and patch boundaries.

    // The textureId is an integer in the range 0..N where N is the maximum
    // number of unique texture objects in the database.  0 is reserved for
    // a non-textured polygon.  The textureId number cooresponds texture
    // file entry in the database's texture library (.tlb) file.

    int storePolygon( MdxList<MdxVertex> &thePolygon, short textureId,
                      int priority, int groupPriority );

    int storeBillboard( MdxList<MdxVertex> &thePolygon, short textureId,
                        double x, double y, double z );

    // Set the LOD range for polygons sent by storePolygon

    void pushLOD( double lodMinDist, double lodMaxDist,
                  double cx, double cy, double cz );

    void popLOD();

    // After all geometry has been sent, write out the MDX
    
    int writeToFile( const char *file );

    // Enable/disable unshimmering of faces.  Shimmering of textures is a result of 
    // texture coordinates being too large in magnitude.  If unshimmering is enabled,
    // texture coordinates will be translated on a face-by-face basis so that floating
    // point precision is maintained.  Note: unshimmering faces should only be used if
    // needed as it results in more geometry and hence less performance.

    void unshimmerFaces( int bYesNo ) { m_bUnshimmerFaces = bYesNo; }

    int getMaterialId( const MdxMaterial &mat );

private:

    void m_storePolygon( MdxList<MdxVertex> &poly, short textureId, 
                         int priority, int groupPriority );

    MdxHeader  *header;
    MdxPatch   **patches;
    double     patchSize;
    int        patchesWide;
    int        patchesHigh;
    int        numPatches;

    int        m_bUnshimmerFaces;
    double     m_lodMinDist;
    double     m_lodMaxDist;
};

#endif

//----------------------------------------------------------------------
// MetaVR, Inc. MetaDatabase - Extended (MDX) Write API 
// Copyright (C) 1997, 1998, 1999, 2000 MetaVR. All rights reserved. 
//----------------------------------------------------------------------