Lib3df 20030825 review
DownloadLib3df is a C++ library to load 3D world
|
|
Lib3df is a C++ library to load 3D world. It works under Windows,MacOS,Linux and most Unixes.
HLIB is a C++ library intended to facilitate the use of ".MAP" files in applications. ".MAP" files are produced by the "Valve Hammer Editor" availlable at: http://collective.valve-erc.com/ . This is the editor used to create Half-Life, Team Fortress Classic, Counter-Strike and Day of Defeat maps. A lot of models are availlable in this format on the internet and the abillity to read such format may greatly help game programmer. HLIB is intended to be portable accross many platforms including: GNU/Linux, All UNIX*S, MS-Windows > 95.
HOW IT WORKS:
HLIB doesn't impose you anything about how the map data will be presented in memory. Instead the library calls the methods of a "builder" object you supplied, to inform your program that some kind of 3D objects has been found in the map file. For instance when the library finds a polygon it calls:
BeginPolygon(); then all subsequent method call will refer to this polygon.
When there is no more data about the polygon, the library calls: EndPolygon();
A map is made of many entities. Each entity can have many key-value pairs (such as: "classname" "player", which says: this entity is of class player). In addition, an entity can have some brushes. A brush is a convex set of polygons. Each polygon has:
- one texture name
- at least 3 vertex
- one normal per vertex
- one UV coordinate per vertex
First you have to create a "builder". You do this by subclassing the
HLMapBuilder class:
class MyBuilder
: public HLMapBuilder
{
public:
MyBuilder(void) {}
virtual ~MyBuilder(void) {}
}
Then you have to create an HLMap object and a builder and link them together:
HLMap theMap;
MyBuilder theBuilder
theMap.SetBuilder(theBuilder);
std::ifstream theMapFile("mymap.map");
theMap.BuildFromStream(theMapFile);
The HLMap object will parse the file and call the following methods of the builder
object:
// Cancel everything (error)
virtual void BuildError(void);
// Begins a map building
virtual void BuildBeginMap(void);
// Begins an entity building
virtual void BuildBeginEntity(void);
// Builds an option
virtual void BuildOption(const char* option, const char* value);
// Begins a brush building (an entity may have many brushes)
virtual void BuildBeginBrush(void);
// Builds a facet (deprecated)
virtual void BuildFacet(sgVec3 A, sgVec3 B, sgVec3 C, const char* texture, sgVec3 U, int ushift, sgVec3 V, int vshift, float rotation, float xscale, float yscale);
// Begins a polygon building
virtual void BuildBeginPolygon(void);
// Builds the polygon's texture
virtual void BuildTexture(const char* texture);
// Get the last built texture height and width
virtual void GetTextureDimension(int* w, int* h);
// Builds one polygon's vertex
virtual void BuildNormal(sgVec3 v);
// Builds one polygon's vertex
virtual void BuildVertex(sgVec3 v);
// Builds the vertex UV mapping
virtual void BuildUVMapping(sgVec3 uv);
// Ends a polygon building
virtual void BuildEndPolygon(void);
// Ends a brush building (an entity may have many brushes)
virtual void BuildEndBrush(void);
// Ends an entity building
virtual void BuildEndEntity(void);
// Ends a map building
virtual void BuildEndMap(void);
Here is the list of method call produced for a map containing only a single
pyramidal object:
BuildBeginMap(); // this is a new map
BuildBeginEntity(); // this is a new entity
BuildOption("classname", "pyramid"); // this entity's classname is: "pyramid"
BuildOption("name", "The Big Pyramid"); // this entity's name is: "The Big Pyramid"
BuildBeginBrush(); // this entity contains a brush
BuildBeginPolygon(); // let's go for the brush's first polygon
BuildTexture("GoodOldPyramid"); // it uses the good old pyramid texture
GetTextureDimension(&w, &h); // the builder has to give the with and height
// of the texture
/// it is needed because the HLMap object doesn't
// know anything about image file format
BuildVertex(v); // the first vertex
BuildNormal(n); // its normal
BuildUVMapping(uv); // its UV corrdinate
BuildVertex(v); // the second vertex
BuildNormal(n); // its normal
BuildUVMapping(uv); // its UV corrdinate
...
BuildEndPolygon(); // this polygon is finished
BuildPolygon(); // The second polygon
...
BuildEndPolygon(); // the second polygon is finished
...
BuildEndBrush(); // this brush is finished
BuildBeginBrush(); // a second brush
...
BuildEndBrush(); // the second brush is finished
...
BuildEndEntity(); // The first entity is finished
BuildBeginEntity(); // a second entity
...
BuildEndEntity(); // the second entity is finished
...
BuildEndMap(); // the map is finished
HLIB contains a HLMapBuilder class which is a basic builder. It doesn't do anything but donc break anything. It is the base class for all your builder. A real life builder is given in example with the PlibMapBuilder class. It is up to you to customize these methods to produce something
usefull. HLIB is just a parser with some 3D geometry CSG calculations.
Due to the file format, HLIB has to do a lot of 3D calculation when reading the map file. To help with these calculations HLIB uses PLIB. PLIB is a 3D library availlable at: http://sourceforge.net/projects/plib
PLIB is made of many components:
- SG: which deals with geometry and is used extensively throughout HLIB
- SSG: which deals with rendering
- UL: which is a utility library, (only used in HLIB for some defines)
- ....
HLIB uses SG internally and externally: the sgVec3 type is defined by SG and is used to pass vertex data from the director (HLMap) to the builder (HLMapBuilder derived classes).
HLIB uses SSG in one class only: PlibMapBuilder. You can safely remove this class if you don't want SSG at all.
Requirements:
PLIB
Lib3df 20030825 keywords