aboutsummaryrefslogtreecommitdiff
path: root/docs/doxygen/nel/3d_data_howto.html
blob: c47b89aaaa2e2dd59eab7c44127c50858959aa1a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
	<TITLE>nevrax.org : docs</TITLE>
	<LINK REL=stylesheet TYPE="text/css" HREF="/inc/css/nevrax.css">
	<link href="doxygen.css" rel="stylesheet" type="text/css">
</HEAD>
<BODY MARGINHEIGHT="0" MARGINWIDTH="0">

<!-- uplinks -->
<TABLE CELLSPACING=0 CELLPADDING=0  BORDER=0>
 <TR>
        <TD WIDTH=16><IMG  SRC="/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
        <TD WIDTH=140 BGCOLOR=#dddddd><IMG  SRC="/inc/img/pixel.gif" WIDTH="140" HEIGHT="16" BORDER=0 ALT=""></TD>
        <TD WIDTH=16><IMG  SRC="/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
        <TD><IMG width=6 height=14 SRC="/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF='/'><b>Home</B></FONT></A>&nbsp;&nbsp;&nbsp;</TD>
        <TD><IMG  width=6 height=14  SRC="/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle>&nbsp;<A CLASS=uplinks HREF='/'><b>nevrax.com</B></FONT></A>&nbsp;&nbsp;&nbsp;</TD>
 </TR>
</TABLE> 

<!-- banner Nevrax -->
<TABLE CELLSPACING=0 CELLPADDING=0  BORDER=0 WIDTH=100%>
 <TR><TD  BGCOLOR="#000000" BACKGROUND="/inc/img/black_banner.jpg"><A HREF=""><IMG  SRC="/inc/img/nevrax.gif" WIDTH="170" HEIGHT="45" BORDER=0 ALT="Nevrax" ></A></TD></TR>
</TABLE>

<!-- main table -->
<TABLE CELLSPACING=0 CELLPADDING=0  BORDER=0 height=100%>
 <TR>
	<TD WIDTH=16><IMG  SRC="/inc/img/pixel.gif" WIDTH="16" HEIGHT="10" BORDER=0 ALT=""></TD>
	<TD WIDTH=140   BGCOLOR=#dddddd VALIGN=TOP ALIGN=middle><IMG  SRC="/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">

		<!------ Begin Box ------>
		<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 BGCOLOR=black><TR><TD><TABLE border=0  cellspacing=2 cellpadding=0 width=120><tr><TD ALIGN=middle bgcolor=black>
		<FONT COLOR=white FACE="sans-serif"><B>Nevrax.org</B></FONT></TD></TR><tr><td  colspan=2 bgcolor=#FFFFFF>
		<TABLE cellspacing=0 cellpadding=1 border=0>
			<tr><td ALIGN=middle><a  class='linkbox' href="/news/" TITLE="Rubrique news"><img width=13 height=15  hspace=5 border=0 src=/inc/img/picto-news.gif ALT=#></A></td><td><a  class='linkbox' href="/news/" TITLE="News">News</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/mail/" TITLE="Rubrique mail"><img width=15 height=11  hspace=5 border=0 src=/inc/img/picto-mail.gif ALT=#></A></td><td><a  class='linkbox' href="/mail/" TITLE="Mailing list archive">Mailing-list</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/docs/" TITLE="Rubrique docs"><img width=14 height=16  hspace=5 border=0 src=/inc/img/picto-docs.gif ALT=#></A></td><td><a  class='linkbox' href="/docs/" TITLE="Documentation">Documentation</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/cvs/" TITLE="Rubrique cvs"><img width=13 height=17  hspace=5 border=0 src=/inc/img/picto-cvs.gif ALT=#></A></td><td><a  class='linkbox' href="/cvs/" TITLE="CVS Web">CVS</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/bugs/" TITLE="Rubrique bugs"><img width=20 height=16  hspace=5 border=0 src=/inc/img/picto-bugs.gif ALT=#></A></td><td><a  class='linkbox' href="/bugs/" TITLE="Bugtracking">Bugs</a></td></tr>
			<tr><td ALIGN=middle><a  class='linkbox' href="/GPL.php3" TITLE="Rubrique license"><img  width=18 height=12   hspace=5 border=0 src=/inc/img/picto-gpl.gif ALT=#></A></td><td><a  class='linkbox' href="/GPL.php3" TITLE="License">License</a></td></tr>
		</TABLE>
		</TD></TR></TABLE></TD></TR></TABLE>
		<!------ End Box  ------>

	</TD>
	<TD WIDTH=15><IMG  SRC="/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
	<TD ALIGN=left valign=top><IMG  SRC="/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">

<!-- title -->
<TABLE  background="/inc/img/redline.gif" CELLSPACING=0 CELLPADDING=0  BORDER=0 width=100%><tr><td>
<A HREF="/docs/"><img src="/inc/img/t_docs.gif" ALT="Docs" HEIGHT=20 BORDER=0></A>
</td><td><IMG  SRC="/inc/img/pixel.gif" WIDTH="1" HEIGHT="1" BORDER=0 ALT="">
</td></tr></table>
&nbsp;

<!-- block -->
<TABLE  bgcolor="#dddddd" CELLSPACING=0 CELLPADDING=0  BORDER=0 width=100%><tr><td width=1% valign=middle><img width=6 height=14 hspace=2 vspace=2 src="/inc/img/reddots.gif"></TD>
	<TD><B>Documentation</B></TD>
	<TD ALIGN=RIGHT>&nbsp;</td>
</tr></table>
<!-- Generated by Doxygen 1.2.14 -->
<center>
<a class="qindex" href="index.html">Main Page</a> &nbsp; <a class="qindex" href="namespaces.html">Namespace List</a> &nbsp; <a class="qindex" href="hierarchy.html">Class Hierarchy</a> &nbsp; <a class="qindex" href="classes.html">Alphabetical List</a> &nbsp; <a class="qindex" href="annotated.html">Compound List</a> &nbsp; <a class="qindex" href="files.html">File List</a> &nbsp; <a class="qindex" href="namespacemembers.html">Namespace Members</a> &nbsp; <a class="qindex" href="functions.html">Compound Members</a> &nbsp; <a class="qindex" href="globals.html">File Members</a> &nbsp; <a class="qindex" href="pages.html">Related Pages</a> &nbsp; <a class="qindexRef" doxygen="_cgi:/cgi-bin/nel-search.cgi" href="/cgi-bin/nel-search.cgi">Search</a> &nbsp; </center>
<hr><a name="3d_data_howto"><h2>How to deal with 3d data</h2></a>
 <dl compact><dt><b>
Author: </b><dd>
Cyril Corvazier</dl><a name="d_data_overview"><h3>Overall view</h3></a>

<p>
3d data files in NeL are managed in a specific way.
<p>
NeL doesn't import proprietary 3d file format like .3ds. NeL only deal with NeL binary files. NeL doesn't describe the NeL binary file format, it gives interface to import and export it.
<p>
Those files are generated by serializing some classes. Building those data is easy. With the serial's version system, data can change and stay compatible with the futur version  of NeL.
<p>
To get some NeL binary 3d files, you can:
<p>
<ul>
<li>Get some NeL files from your friend or from Nevrax. :)<li>Export some data with a specific plugin exporting NeL files.<li>Write a file converter from your format to NeL format.<li>Write a plugin for your 3d editor.</ul>
<a name="mesh"><h3>Build a simple mesh</h3></a>

<p>
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 <a class="el" href="classNL3D_1_1CMesh.html">NL3D::CMesh</a>.
<p>
The class <a class="el" href="structNL3D_1_1CMesh_1_1CMeshBuild.html">NL3D::CMesh::CMeshBuild</a> is used to build this mesh. Just fill it with appropriate values:
<p>
<ul>
<li>VertexFlags will received flags that describe vertices format like in CVertexBuffer. 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 exemple:<ul>
<li>IDRV_VF_XYZ|IDRV_VF_NORMAL, simple lighted vertex<li>IDRV_VF_XYZ|IDRV_VF_NORMAL|IDRV_VF_UV[0]|IDRV_VF_UV[1], simple lighted vertex with two mapping channels<li>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.</ul>
<li>Materials is an array of materials. Resize it and fill it with your materials data. See material_howto for more information.<li>Vertices is the vertex array. Only local x, y and z coordinates are stored here. Resize it and fill it.<li>Faces is the triangle array. Each triangle is composed by 3 <a class="el" href="structNL3D_1_1CMesh_1_1CCorner.html">NL3D::CMesh::CCorner</a> and a material Id. The corner must be fill like this:<ul>
<li>Vertex must receive the vertex id used at this corner.<li>Normal must receive the local normalized normal at this corner.<li>Uvs must receive the UV values for each mapping channels defined in VertexFlags.<li>Color must receive the diffuse color if IDRV_VF_COLOR is defined in VertexFlags.<li>Specular must receive the specular color if IDRV_VF_COLOR is defined in VertexFlags.<li>Weights must receive the weight values for each weighting channels defined in VertexFlags.</ul>
</ul>
<div class="fragment"><pre>        <font class="comment">// Let's assume that those namespaces are used: NL3D, NLMISC</font>

        <font class="comment">// My building struct</font>
        CMesh::CMeshBuild buildStruct;

        <font class="comment">// Filling the struct..</font>
        ...

        <font class="comment">// Create a CMesh</font>
        CMesh myMesh;

        <font class="comment">// Build the mesh</font>
        myMesh.build (buildStruct);

        <font class="comment">// Create a mesh for export</font>
        CShapeStream streamableMesh (&amp;myMesh)

        <font class="comment">// Ok, ready to export</font>
</pre></div>
<p>
You have normals, colors and uvs per vertex per triangle. Once you have filled all those values, call <a class="el" href="classNL3D_1_1CMesh.html#a4">NL3D::CMesh::build</a>() on the mesh.  <a class="el" href="classNL3D_1_1CMesh.html#a4">NL3D::CMesh::build</a>() will optimize your corners by merging the same one.
<p>
To simplify the serialization of a shape, use the class <a class="el" href="classNL3D_1_1CShapeStream.html">NL3D::CShapeStream</a> 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 <a class="el" href="classNL3D_1_1CShapeStream.html#a4">NL3D::CShapeStream::serial</a>():
<p>
<div class="fragment"><pre><font class="keywordtype">void</font> CShapeStream::serial(<a class="code" href="classNLMISC_1_1IStream.html">NLMISC::IStream</a> &amp;f) <font class="keywordflow">throw</font>(NLMISC::EStream)
{
        <font class="comment">// First, serial an header or checking if it is correct</font>
        f.serialCheck ((uint32)'PAHS');

        <font class="comment">// Then, serial the shape</font>
        f.serialPolyPtr (_Shape);

        <font class="comment">// Ok, it's done</font>
}
</pre></div>
<p>
Your mesh is ready to export.
<p>
<a name="zone"><h3>Build a landscape zone</h3></a>

<p>
It's coming..
<p>
<a name="serial"><h3>Serial a NeL class</h3></a>

<p>
Now you have build 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:
<p>
<div class="fragment"><pre>        <font class="comment">// Let's assume that those namespaces are used: NL3D, NLMISC</font>

        <font class="comment">// Your object to load into</font>
        CZone                   zone;

        <font class="comment">// Create an input file stream</font>
        CIFile                  fileIn;

        <font class="comment">// Open your file for writing</font>
        <font class="keywordflow">if</font> (fileIn.open (<font class="stringliteral">"myZoneFile.zone"</font>))
        {
                <font class="comment">// Catch some error</font>
                <font class="keywordflow">try</font>
                {
                        <font class="comment">// Read your object</font>
                        zone.serial (fileIn);
                }
                <font class="keywordflow">catch</font> (CException&amp; except)
                {
                        <font class="comment">// Handle errors. File truncated, bad version, etc...</font>
                }
        }
</pre></div>
<p>
Then how to write a shape in a file ? Easy too..
<p>
<div class="fragment"><pre>        <font class="comment">// Let's assume that those namespaces are used: NL3D, NLMISC</font>

        <font class="comment">// Your shape to write</font>
        CShapeStream    shape;

        <font class="comment">// Create an output file stream</font>
        COFile                  fileOut;

        <font class="comment">// Open your file for writing</font>
        <font class="keywordflow">if</font> (fileOut.open (<font class="stringliteral">"myExportedFile.shape"</font>))
        {
                <font class="comment">// Catch some error</font>
                <font class="keywordflow">try</font>
                {
                        <font class="comment">// Write your object</font>
                        shape.serial (fileOut);
                }
                <font class="keywordflow">catch</font> (CException&amp; except)
                {
                        <font class="comment">// Handle error. Disk full, etc...</font>
                }
        }
</pre></div>
<p>


<!-- footer -->
<BR><FONT Size=+5>&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; </FONT>
</TD>
<TD WIDTH=15><IMG  SRC=/inc/img/pixel.gif WIDTH=15 HEIGHT=15 BORDER=0 ALT=""></TD>
</TR>
</TABLE>
</BODY>
</HTML>