595 lines
13 KiB
HTML
595 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
|
|
<head>
|
|
<title>MTUL b3d reader/writer documentation</title>
|
|
<link rel="stylesheet" href="../ldoc.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
|
|
<div id="container">
|
|
|
|
<div id="product">
|
|
<div id="product_logo"></div>
|
|
<div id="product_name"><big><b></b></big></div>
|
|
<div id="product_description"></div>
|
|
</div> <!-- id="product" -->
|
|
|
|
|
|
<div id="main">
|
|
|
|
|
|
<!-- Menu -->
|
|
|
|
<div id="navigation">
|
|
<br/>
|
|
<h1>MTUL b3d</h1>
|
|
|
|
|
|
<ul>
|
|
<li><a href="../index.html">Index</a></li>
|
|
</ul>
|
|
|
|
<h2>Contents</h2>
|
|
<ul>
|
|
<li><a href="#Functions">Functions</a></li>
|
|
<li><a href="#Tables">Tables</a></li>
|
|
</ul>
|
|
|
|
|
|
<h2>Modules</h2>
|
|
<ul class="nowrap">
|
|
<li><strong>b3d_reader</strong></li>
|
|
<li><a href="../modules/b3d_writer.html">b3d_writer</a></li>
|
|
<li><a href="../modules/b3d_nodes.html">b3d_nodes</a></li>
|
|
</ul>
|
|
|
|
</div>
|
|
|
|
<div id="content">
|
|
|
|
<h1>Module <code>b3d_reader</code></h1>
|
|
<p>parse .b3d files into a lua table.</p>
|
|
<p> note: capitlization of name indicates a "chunk" defined by the blitz3d format (see b3d_specification.txt)</p>
|
|
|
|
|
|
<h2><a href="#Functions">Functions</a></h2>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#mtul.b3d_reader.read_model">mtul.b3d_reader.read_model (modelname, node_only)</a></td>
|
|
<td class="summary">read b3d models by their name.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#mtul.b3d_reader.read_from_stream">mtul.b3d_reader.read_from_stream (stream, ignore_chunks)</a></td>
|
|
<td class="summary">read directly from file</td>
|
|
</tr>
|
|
</table>
|
|
<h2><a href="#Tables">Tables</a></h2>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#ignore_chunks">ignore_chunks</a></td>
|
|
<td class="summary">an unordered list of the following string chunks.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#TEXS">TEXS</a></td>
|
|
<td class="summary">textures</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#BRUS">BRUS</a></td>
|
|
<td class="summary">brushes (materials)</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#VRTS">VRTS</a></td>
|
|
<td class="summary">vertices</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#TRIS">TRIS</a></td>
|
|
<td class="summary">triangle/poly sets</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#MESH">MESH</a></td>
|
|
<td class="summary">the mesh chunk table</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#BONE">BONE</a></td>
|
|
<td class="summary">bone table
|
|
a list of vertex weights indexed by their vertex_id</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#KEYS">KEYS</a></td>
|
|
<td class="summary">keyframes</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#keyframe">keyframe</a></td>
|
|
<td class="summary">table which specifies a keyframe</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#ANIM">ANIM</a></td>
|
|
<td class="summary">defines the animation of a model</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#NODE">NODE</a></td>
|
|
<td class="summary">a node chunk possibly containing the following chunks.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#BB3D">BB3D</a></td>
|
|
<td class="summary">note: in <code>b3d_writer</code> the node_paths field is ignored</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#node_paths">node_paths</a></td>
|
|
<td class="summary">node paths
|
|
a list of nodes indexed by a list which containing every related parent node aswell as itself.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br/>
|
|
<br/>
|
|
|
|
|
|
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
|
|
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "mtul.b3d_reader.read_model"></a>
|
|
<strong>mtul.b3d_reader.read_model (modelname, node_only)</strong>
|
|
</dt>
|
|
<dd>
|
|
read b3d models by their name. This simplifies read<em>from</em>stream.
|
|
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">modelname</span>
|
|
string, the name of model you are trying to read.
|
|
</li>
|
|
<li><span class="parameter">node_only</span>
|
|
bool, specifies wether to ignore textures, meshes, or anything else. Use this if you're only trying to solve bone transforms.
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
b3d table (documentation needed!)
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "mtul.b3d_reader.read_from_stream"></a>
|
|
<strong>mtul.b3d_reader.read_from_stream (stream, ignore_chunks)</strong>
|
|
</dt>
|
|
<dd>
|
|
read directly from file
|
|
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">stream</span>
|
|
the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.)
|
|
</li>
|
|
<li><span class="parameter">ignore_chunks</span>
|
|
a list of <a href="../modules/b3d_reader.html#ignore_chunks">ignore_chunks</a> to be ignored
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<a href="../modules/b3d_reader.html#BB3D">BB3D</a>
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
<h2 class="section-header "><a name="Tables"></a>Tables</h2>
|
|
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "ignore_chunks"></a>
|
|
<strong>ignore_chunks</strong>
|
|
</dt>
|
|
<dd>
|
|
an unordered list of the following string chunks.
|
|
"NODE" and "BB3D" are ommitted as they are not allowed.
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">1</span>
|
|
"TEXS" texture information
|
|
</li>
|
|
<li><span class="parameter">2</span>
|
|
"BRUS" brushes (materials)
|
|
</li>
|
|
<li><span class="parameter">3</span>
|
|
"MESH" (sub-chunks of "MESH" include "VERTS" & "TRIS")
|
|
</li>
|
|
<li><span class="parameter">4</span>
|
|
"TRIS" sets of triangles
|
|
</li>
|
|
<li><span class="parameter">5</span>
|
|
"VRTS" vertices
|
|
</li>
|
|
<li><span class="parameter">6</span>
|
|
"BONE" node vertex weights
|
|
</li>
|
|
<li><span class="parameter">7</span>
|
|
"ANIM" animation information
|
|
</li>
|
|
<li><span class="parameter">8</span>
|
|
"KEYS" keyframes
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "TEXS"></a>
|
|
<strong>TEXS</strong>
|
|
</dt>
|
|
<dd>
|
|
textures
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">file</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">flags</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">pos</span>
|
|
table {float, float}
|
|
</li>
|
|
<li><span class="parameter">pos</span>
|
|
table {float, float}
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "BRUS"></a>
|
|
<strong>BRUS</strong>
|
|
</dt>
|
|
<dd>
|
|
brushes (materials)
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">name</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">color</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">shininess</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">blend</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">fx</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">texture_id</span>
|
|
|
|
|
|
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "VRTS"></a>
|
|
<strong>VRTS</strong>
|
|
</dt>
|
|
<dd>
|
|
vertices
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">flags</span>
|
|
uknown
|
|
</li>
|
|
<li><span class="parameter">tex_coord_sets</span>
|
|
the number of texture coordinate sets
|
|
</li>
|
|
<li><span class="parameter">tex_coord_set_size</span>
|
|
unknown
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
a list of vertices, the integer index defines their vertex<em>ids { pos={x,y,z}, color={r, g, b, a}, tex</em>coords=... }
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "TRIS"></a>
|
|
<strong>TRIS</strong>
|
|
</dt>
|
|
<dd>
|
|
triangle/poly sets
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">brush_id</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">vertex_ids</span>
|
|
a list of three vertex IDs {i, j, k} which make it up
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "MESH"></a>
|
|
<strong>MESH</strong>
|
|
</dt>
|
|
<dd>
|
|
the mesh chunk table
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">brush_id</span>
|
|
(may not exist) brush from brush chunk to use
|
|
</li>
|
|
<li><span class="parameter">vertices</span>
|
|
<a href="../modules/b3d_reader.html#VRTS">VRTS</a> vertices and indexed by their ID and additional info
|
|
</li>
|
|
<li><span class="parameter">triangle_sets</span>
|
|
<a href="../modules/b3d_reader.html#TRIS">TRIS</a> a list of three vertices to be used in
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "BONE"></a>
|
|
<strong>BONE</strong>
|
|
</dt>
|
|
<dd>
|
|
bone table
|
|
a list of vertex weights indexed by their vertex_id
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "KEYS"></a>
|
|
<strong>KEYS</strong>
|
|
</dt>
|
|
<dd>
|
|
keyframes
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">flags</span>
|
|
defines if position rotation and scale exists (further explanation needed)
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
a list of <a href="../modules/b3d_reader.html#keyframe">keyframe</a>s
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "keyframe"></a>
|
|
<strong>keyframe</strong>
|
|
</dt>
|
|
<dd>
|
|
table which specifies a keyframe
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "ANIM"></a>
|
|
<strong>ANIM</strong>
|
|
</dt>
|
|
<dd>
|
|
defines the animation of a model
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">flags</span>
|
|
unused?
|
|
</li>
|
|
<li><span class="parameter">frames</span>
|
|
number of frames
|
|
</li>
|
|
<li><span class="parameter">fps</span>
|
|
framerate of the model
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "NODE"></a>
|
|
<strong>NODE</strong>
|
|
</dt>
|
|
<dd>
|
|
a node chunk possibly containing the following chunks.
|
|
there are three possible "types" of nodes. All bones will contain the following chunks:
|
|
<code>position</code>, <code>rotation</code>, <code>scale</code>.
|
|
Bones will have a bone field which will contain IDs from it's parent node's mesh chunk.
|
|
Meshes will have a mesh field containing information about their mesh.
|
|
Pivots will have neither of those and simply serve as parents to child nodes. <3
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">name</span>
|
|
|
|
|
|
|
|
</li>
|
|
<li><span class="parameter">type</span>
|
|
string which is either "pivot", "bone" or "mesh"
|
|
</li>
|
|
<li><span class="parameter">children</span>
|
|
a list of child nodes, Transoformations (position, rotation, scale) will be applied to the children.
|
|
</li>
|
|
<li><span class="parameter">position</span>
|
|
position {x, y, z} of the bone
|
|
</li>
|
|
<li><span class="parameter">rotation</span>
|
|
quaternion {x, y, z, w} rotation of the bone at rest
|
|
</li>
|
|
<li><span class="parameter">scale</span>
|
|
{x, y, z} scale of the bone at rest
|
|
</li>
|
|
<li><span class="parameter">mesh</span>
|
|
<a href="../modules/b3d_reader.html#MESH">MESH</a> chunk. Found in <strong>mesh</strong> node
|
|
</li>
|
|
<li><span class="parameter">bone</span>
|
|
<a href="../modules/b3d_reader.html#BONE">BONE</a> chunk. Found in <strong>bone</strong> node
|
|
</li>
|
|
<li><span class="parameter">keys</span>
|
|
<a href="../modules/b3d_reader.html#KEYS">KEYS</a> chunk. Found in <strong>bone</strong> node
|
|
</li>
|
|
<li><span class="parameter">animation</span>
|
|
<a href="../modules/b3d_reader.html#ANIM">ANIM</a> chunk. Typically found in root node (uknown wether it can be elsewhere.)
|
|
</li>
|
|
<li><span class="parameter">parent</span>
|
|
the parent node. (The node in which this node is in the children table)
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "BB3D"></a>
|
|
<strong>BB3D</strong>
|
|
</dt>
|
|
<dd>
|
|
note: in <code>b3d_writer</code> the node_paths field is ignored
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">node_paths</span>
|
|
all nodes in the model indexed by a table <a href="../modules/b3d_reader.html#node_paths">node_paths</a>
|
|
</li>
|
|
<li><span class="parameter">node</span>
|
|
a table containing the root <a href="../modules/b3d_reader.html#NODE">NODE</a> of the model.
|
|
</li>
|
|
<li><span class="parameter">textures</span>
|
|
a list of <a href="../modules/b3d_reader.html#TEXS">TEXS</a> chunks
|
|
</li>
|
|
<li><span class="parameter">brushes</span>
|
|
a list of <a href="../modules/b3d_reader.html#BRUS">BRUS</a> chunks
|
|
</li>
|
|
<li><span class="parameter">version</span>
|
|
<code>{major=float, minor=float}</code> this functionally means nothing, but it's version information.
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "node_paths"></a>
|
|
<strong>node_paths</strong>
|
|
</dt>
|
|
<dd>
|
|
node paths
|
|
a list of nodes indexed by a list which containing every related parent node aswell as itself.
|
|
|
|
|
|
<h3>Fields:</h3>
|
|
<ul>
|
|
<li><span class="parameter">...</span>
|
|
) node
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
|
|
|
|
</div> <!-- id="content" -->
|
|
</div> <!-- id="main" -->
|
|
<div id="about">
|
|
<i>generated by <a href="http://github.com/lunarmodules/ldoc">LDoc 1.5.0</a></i>
|
|
<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
|
|
</div> <!-- id="about" -->
|
|
</div> <!-- id="container" -->
|
|
</body>
|
|
</html>
|