3D data files in NeL are managed in a specific way.
NeL doesn't load proprietary 3D file formats like .max directly. NeL only deals with NeL binary files. The binary format is not described, NeL provides and interface to import and export it.
Each instanced shape in a 3D scene has:
- An instance class that derives from CTransformShape.
- A definition class which derives from IShape.
- A CMesh-derived class obtained from the exported data.
Binary NeL files are generated by serializing some classes. Building the data is straightforward. With the serial function's versioning system, data can change and stay compatible with the future versions of NeL as well.
To get some NeL binary 3D files, you can:
- Get some NeL files from your friends or from Ryzom Core.
- Export some data with a specific plugin exporting NeL files.
- Write a file converter from your format to NeL format.
- Write a plugin for your 3D editor.
¶ Build a simple mesh
Ok, First you will need to build a simple mesh. A mesh is a class that handle one 3d object. It contains the vertices, the primitives, and pointers on materials. The mesh class is NL3D::CMesh.
The class NL3D::CMesh::CMeshBuild is used to build this mesh. Just fill it with appropriate values:
VertexFlagswill received flags that describe vertices format like inCVertexBuffer. Following flags can be used:- IDRV_VF_XYZ: x, y, z local value, must be present
- IDRV_VF_NORMAL: normal, should be present for lighted material
- IDRV_VF_COLOR: vertex diffuse color
- IDRV_VF_SPECULAR: vertex specular color
- IDRV_VF_UV[IDRV_VF_MAXSTAGES]: flags for each UV channel used, max IDRV_VF_MAXSTAGES UV channels
- IDRV_VF_W[IDRV_VF_MAXW]: flags for each weighting channel used
Some examples:- IDRV_VF_XYZ | IDRV_VF_NORMAL: simple lighted vertex
- IDRV_VF_XYZ | IDRV_VF_NORMAL|IDRV_VF_UV[0] | IDRV_VF_UV[1]: simple lighted vertex with two mapping channels
- IDRV_VF_XYZ | IDRV_VF_NORMAL|IDRV_VF_W[0] | IDRV_VF_W[1] | IDRV_VF_W[2] | IDRV_VF_W[3]: simple lighted vertex with 4 weights for skinning matrix.
Materialsis an array of materials. Resize it and fill it with your materials data.Verticesis the vertex array. Only local x, y and z coordinates are stored here. Resize it and fill it.Facesis the triangle array. Each triangle is composed by 3CMesh::CCornerand a material Id. The corner must be fill like this:Vertexmust receive the vertex id used at this corner.Normalmust receive the local normalized normal at this corner.Uvsmust receive the UV values for each mapping channels defined inVertexFlags.Colormust receive the diffuse color ifIDRV_VF_COLORis defined inVertexFlags.Specularmust receive the specular color ifIDRV_VF_COLORis defined inVertexFlags.Weightsmust receive the weight values for each weighting channels defined inVertexFlags.
// Let's assume that those namespaces are used: NL3D, NLMISC
// My building struct
CMesh::CMeshBuild buildStruct;
// Filling the struct..
...
// Create a CMesh
CMesh myMesh;
// Build the mesh
myMesh.build (buildStruct);
// Create a mesh for export
CShapeStream streamableMesh (&myMesh)
// Ok, ready to export
You have normals, colors and uvs per vertex per triangle. Once you have filled all those values, call NL3D::CMesh::build() on the mesh. NL3D::CMesh::build() will optimize your corners by merging the same one.
To simplify the serialization of a shape, use the class NL3D::CShapeStream construct with your shape pointer and serialize it. This class will serial a valid .shape file with header and polymorphic serialization of the shape, materials and textures. Here is the code of NL3D::CShapeStream::serial():
void CShapeStream::serial(NLMISC::IStream &f) throw(NLMISC::EStream)
{
// First, serial an header or checking if it is correct
f.serialCheck ((uint32)'PAHS');
// Then, serial the shape
f.serialPolyPtr (_Shape);
// Ok, it's done
}
Your mesh is ready to export.
¶ Build a landscape zone
Todo.
¶ Serial a NeL class
Now you have built your data, you must know how to serial a NeL class. Let's assume that you want to read a landscape zone from a file:
// Let's assume that those namespaces are used: NL3D, NLMISC
// Your object to load into
CZone zone;
// Create an input file stream
CIFile fileIn;
// Open your file for writing
if (fileIn.open("myZoneFile.zone"))
{
// Catch some error
try
{
// Read your object
zone.serial(fileIn);
}
catch (CException& except)
{
// Handle errors. File truncated, bad version, etc...
}
}
Then how to write a shape in a file ? Easy too..
// Let's assume that those namespaces are used: NL3D, NLMISC
// Your shape to write
CShapeStream shape;
// Create an output file stream
COFile fileOut;
// Open your file for writing
if (fileOut.open ("myExportedFile.shape"))
{
// Catch some error
try
{
// Write your object
shape.serial (fileOut);
}
catch (CException& except)
{
// Handle error. Disk full, etc...
}
}