// MetaVR, Inc. MDX Write API
//
// Copyright (C) 1997- 2008 MetaVR, Inc. 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 nondisclosure 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 want
// 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 tangent
// 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
// corresponds to 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, 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 |
