luanti-extended-engine-features/leef-b3d-cd2025
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
FatalErr42O 2024-08-03 16:25:17 -07:00
parent 215dfdab41
commit 8453de9caf
7 changed files with 145 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/index.html
View File

@ -65,7 +65,7 @@
</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-07-14 13:05:02 </i>
<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

2
docs/modules/b3d_nodes.html
View File

@ -262,7 +262,7 @@ outputs need cleaning up.</li>
</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-07-14 13:05:02 </i>
<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

128
docs/modules/b3d_reader.html
View File

@ -68,10 +68,18 @@
<h2><a href="#Tables">Tables</a></h2>
<table class="function_list">
<tr>
<td class="name" nowrap><a href="#chunks">chunks</a></td>
<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>
@ -102,18 +110,16 @@
</tr>
<tr>
<td class="name" nowrap><a href="#NODE">NODE</a></td>
<td class="summary">node
a node chunk possibly containing the following chunks.</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">b3d table
note: in the b3d writer the node_paths field is ignored</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 hieracrchy of nodes i.e.</td>
a list of nodes indexed by a list which containing every related parent node aswell as itself.</td>
</tr>
</table>
@ -166,14 +172,14 @@
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#chunks">chunks</a> to be ignored (documentation needed)
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> (documentation needed!)
<a href="../modules/b3d_reader.html#BB3D">BB3D</a>
</ol>
@ -185,8 +191,8 @@
<dl class="function">
<dt>
<a name = "chunks"></a>
<strong>chunks</strong>
<a name = "ignore_chunks"></a>
<strong>ignore_chunks</strong>
</dt>
<dd>
an unordered list of the following string chunks.
@ -225,6 +231,86 @@
</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>
@ -389,11 +475,12 @@
<strong>NODE</strong>
</dt>
<dd>
node
a node chunk possibly containing the following chunks.
a node chunk possibly containing the following chunks.
there are three possible "types" of nodes. All bones will contain the following chunks:
position, rotation, scale. Bones will have a
bone field which will contain IDs from it's parent node's mesh chunk.
<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. &lt;3
<h3>Fields:</h3>
@ -445,23 +532,22 @@
<strong>BB3D</strong>
</dt>
<dd>
b3d table
note: in the b3d writer the node_paths field is ignored
note: in <code>b3d_writer</code> the node_paths field is ignored
<h3>Fields:</h3>
<ul>
<li><span class="parameter">node_paths</span>
all of the nodes in the model <a href="../modules/b3d_nodes.html#">b3d_nodes</a>
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>
??? texture information
a list of <a href="../modules/b3d_reader.html#TEXS">TEXS</a> chunks
</li>
<li><span class="parameter">brushes</span>
??? material information
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.
@ -479,7 +565,7 @@
</dt>
<dd>
node paths
a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node"
a list of nodes indexed by a list which containing every related parent node aswell as itself.
<h3>Fields:</h3>
@ -501,7 +587,7 @@
</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-07-14 13:05:02 </i>
<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

6
docs/modules/b3d_writer.html
View File

@ -85,7 +85,7 @@
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">self</span>
???
<a href="../modules/b3d_reader.html#BB3D">BB3D chunk</a>
</li>
</ul>
@ -110,7 +110,7 @@
<h3>Parameters:</h3>
<ul>
<li><span class="parameter">self</span>
???
<a href="../modules/b3d_reader.html#BB3D">BB3D chunk</a>
</li>
<li><span class="parameter">stream</span>
io file object to write to
@ -129,7 +129,7 @@
</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-07-14 13:05:02 </i>
<i style="float:right;">Last updated 2024-08-03 16:24:48 </i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>

BIN
ldoc/index.html - Shortcut.lnk Normal file
View File

Binary file not shown.

43
modlib/read_b3d.lua
View File

@ -66,13 +66,13 @@ end
-- @field 6 "BONE" node vertex weights
-- @field 7 "ANIM" animation information
-- @field 8 "KEYS" keyframes
-- @table chunks
-- @table ignore_chunks
--- read directly from file
-- @function mtul.b3d_reader.read_from_stream
-- @param stream the file object (from the io library) to read from. Make sure you open it as "rb" (read binary.)
-- @param ignore_chunks a list of @{chunks} to be ignored (documentation needed)
-- @return @{BB3D} (documentation needed!)
-- @param ignore_chunks a list of @{ignore_chunks} to be ignored
-- @return @{BB3D}
function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
local left = 8
@ -164,6 +164,12 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
local chunk
local chunks = {
TEXS = function()
--- textures
--@field file
--@field flags
--@field pos table {float, float}
--@field pos table {float, float}
--@table TEXS
local textures = {}
while content() do
local tex = {}
@ -178,6 +184,14 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return textures
end,
BRUS = function()
--- brushes (materials)
-- @field name
-- @field color
-- @field shininess
-- @field blend
-- @field fx
-- @field texture_id
-- @table BRUS
local brushes = {}
local n_texs = int()
assert(n_texs <= 8)
@ -330,11 +344,13 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
return ret
end,
NODE = function()
--- node
-- a node chunk possibly containing the following chunks.
--- a node chunk possibly containing the following chunks.
-- there are three possible "types" of nodes. All bones will contain the following chunks:
-- position, rotation, scale. Bones will have a
-- bone field which will contain IDs from it's parent node's mesh chunk.
-- `position`, `rotation`, `scale`.
-- 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
--
-- @field name
-- @field type string which is either "pivot", "bone" or "mesh"
-- @field children a list of child nodes, Transoformations (position, rotation, scale) will be applied to the children.
@ -399,12 +415,11 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
end)
return node
end,
--- b3d table
-- note: in the b3d writer the node_paths field is ignored
-- @field node_paths all of the nodes in the model @{b3d_nodes}
--- note: in `b3d_writer` the node_paths field is ignored
-- @field node_paths all nodes in the model indexed by a table @{node_paths}
-- @field node a table containing the root @{NODE} of the model.
-- @field textures @{TEXS} texture information
-- @field brushes @{BRUS} material information
-- @field textures a list of @{TEXS} chunks
-- @field brushes a list of @{BRUS} chunks
-- @field version `{major=float, minor=float}` this functionally means nothing, but it's version information.
-- @table BB3D
BB3D = function()
@ -458,7 +473,7 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
--also, Fatal here: for the sake of my reputation (which is nonexistent), typically I wouldn't nest these functions
--because I am not a physcopath and or a german named Lars, but for the sake of consistency it has to happen.
--(Not that its *always* a bad idea, but unless you're baking in parameters it's sort of useless and potentially wasteful)
local copy_path = mtul.table and mtul.table.shallow_copy or function(tbl)
local copy_path = function(tbl)
local new_table = {}
for i, v in pairs(tbl) do
new_table[i] = v
@ -486,6 +501,6 @@ function mtul.b3d_reader.read_from_stream(stream, ignore_chunks)
end
--- node paths
-- a list of nodes indexed by a hieracrchy of nodes i.e. "path.to.node"
-- a list of nodes indexed by a list which containing every related parent node aswell as itself.
-- @field (...) node
-- @table node_paths

7
modlib/write_b3d.lua
View File

@ -151,7 +151,8 @@ local function write_rope(self)
chunk("KEYS", function()
int(flags)
for _, frame in ipairs(keys) do
int(frame.frame)
--reader offsets by 1, so writer should to.
int(frame.frame+1)
if frame.position then vector3(frame.position) end
if frame.scale then vector3(frame.scale) end
if frame.rotation then quaternion(frame.rotation) end
@ -219,7 +220,7 @@ end
--- output a string of binary in the blitz 3d format
-- @function mtul.b3d_writer.write_string
-- @param self @{BB3D}
-- @param self @{b3d_reader.BB3D|BB3D chunk}
-- @return string containing the binary file
function mtul.b3d_writer.write_string(self)
return table.concat(write_rope(self))
@ -227,7 +228,7 @@ end
--- output in the blitz3d format file reference
-- @function mtul.b3d_writer.write_model_to_file
-- @param self @{BB3D}
-- @param self @{b3d_reader.BB3D|BB3D chunk}
-- @param stream io file object to write to
function mtul.b3d_writer.write_model_to_file(self, stream)
for _, str in ipairs(write_rope(self)) do