commit 16122bf99ac305d84f4ec94dfe37c100f06c06f7
parent 99a2195969148c372d4095f3e3dc5f8b4b7721cb
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 14 Mar 2022 16:21:06 +0100
Write the Star-Mesh man page
Diffstat:
2 files changed, 64 insertions(+), 20 deletions(-)
diff --git a/doc/smsh.5.scd b/doc/smsh.5.scd
@@ -0,0 +1,64 @@
+smsh(5)
+
+# NAME
+
+smsh - Star-Mesh file format
+
+# DESCRIPTION
+
+*smsh* is a binary file format that describes an indexed mesh (surface or
+volume). Only the geometric data of the mesh is stored; no additional properties
+are attached to its nodes or cells.
+
+An *smsh* file begins with a header that describes the layout of the data,
+followed by the geometric data itself, i.e. the list of nodes and the list of
+cells.
+
+The header consists of 5 integers. The first integer is a power of two (usually
+4096) that defines the size of the memory page in bytes (_pagesize_) on which
+the list of nodes and the list of cells are aligned. By aligning data to
+_pagesize_, and depending on system requirements, memory mapping can be used to
+automatically load/unload pages on demand (see *mmap*(2)). The remaining
+integers store the number of nodes (_#nodes_) and the number of cells
+(_#cells_), followed by the size of a node (_dimnode_) and the size of a cell
+(_dimcell_), respectively.
+
+Fill bytes follow the file header to align nodes to _pagesize_. The nodes are
+then listed with a list of _#nodes_ _dimnode_ double-precision floating-point
+numbers per node, where _#nodes_ is the number of mesh nodes and _dimnode_ is
+the number of floating-point numbers per node. Additional fill bytes are added
+after the node list to align the list of upcoming cells to _pagesize_. The cells
+are then listed using _dimcell_ 64-bit signed integers per node where each integer
+indexes a node in the previously defined list of nodes (indexing starts at 0).
+Finally, fill bytes are added to align the overall file size to _pagesize_.
+
+# BINARY FILE FORMAT
+
+```
+<smsh> ::= <pagesize> <#nodes> <#cells> <dimnode> <dimcell>
+ <padding>
+ <nodes>
+ <padding>
+ <cells>
+ <padding>
+<pagesize> ::= UINT64
+<#nodes> ::= UINT64
+<#cells> ::= UINT64
+<dimnode> ::= UINT32
+<dimcell> ::= UINT32
+
+<padding> ::= [ BYTE ... ]
+
+<nodes> ::= <node-pos>
+ [ <node-pos> ... ]
+
+<cells> ::= <cell-ids>
+ [ <cell-ids> ... ]
+
+<node-pos> ::= DOUBLE ...
+<cell-ids> ::= UINT64 ...
+```
+
+# SEE ALSO
+
+*mmap*(2)
diff --git a/doc/stri.txt b/doc/stri.txt
@@ -1,20 +0,0 @@
-<stri> ::= <pagesize> <#vertices> <#triangles>
- <padding>
- <positions>
- <padding>
- <indices>
- <padding>
-<pagesize> ::= INT64
-<#vertices> ::= INT64
-<#triangles> ::= INT64
-<padding> ::= [ BYTE ... ]
-
-<positions> ::= <vertex-pos>
- [ <vertex-pos> ... ]
-
-<indices> ::= <triangle-ids>
- [ <triangle-ids> ... ]
-
-<vertex-pos> ::= DOUBLE DOUBLE DOUBLE
-<triangle-ids> ::= INT64 INT64 INT64
-
