commit eefd8f18f273f0b96b3b33c9efd104aaf5e40f88
parent 280e2d4954f25388e93ba8675b34cecd99c5f15b
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Fri, 15 Jul 2022 15:56:30 +0200
Write the man page of the surface properties file format
Diffstat:
3 files changed, 105 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
@@ -16,7 +16,8 @@ on the
[Star-3D](https://gitlab.com/meso-star/star-3d),
[Star-Buffer](https://gitlab.com/meso-star/star-buffer), and
[Star-Mesh](https://gitlab.com/meso-star/star-mesh)
-libraries.
+libraries. It optionally depends on [scdoc](https://sr.ht/~sircmpwn/scdoc/)
+which, if available, is used to generate the man pages.
First ensure that CMake is installed on your system. Then install the RCMake
package as well as the aforementioned prerequisites. Finally generate the
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -105,6 +105,27 @@ if(NOT NO_TEST)
endif()
################################################################################
+# Man page
+###############################################################################
+find_program(SCDOC NAMES scdoc)
+if(NOT SCDOC)
+ message(WARNING
+ "The `scdoc' program is missing. "
+ "The Rad Net GRounD man page cannot be generated.")
+else()
+ set(_src ${PROJECT_SOURCE_DIR}/../doc/rnsp.5.scd)
+ add_custom_command(
+ OUTPUT rnsp.5
+ COMMAND ${SCDOC} < ${_src} > rnsp.5
+ DEPENDS ${_src}
+ WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+ COMMENT "Buid ROFF man page rnsp.5"
+ VERBATIM)
+ add_custom_target(man-roff ALL DEPENDS rnsp.5)
+ install(FILES ${CMAKE_CURRENT_BINARY_DIR}/rnsp.5 DESTINATION share/man/man5)
+endif()
+
+################################################################################
# Define output & install directories
################################################################################
install(TARGETS rngrd
diff --git a/doc/rnsp.5.scd b/doc/rnsp.5.scd
@@ -0,0 +1,82 @@
+rnmtl(5)
+
+; Copyright (C) 2022 Centre National de la Recherche Scientifique
+; Copyright (C) 2022 Institut de Physique du Globe de Paris
+; Copyright (C) 2022 |Méso|Star> (contact@meso-star.com)
+; Copyright (C) 2022 Université de Reims Champagne-Ardenne
+; Copyright (C) 2022 Université de Versaille Saint-Quentin
+; Copyright (C) 2022 Université Paul Sabatier (contact@laplace.univ-tlse.fr)
+;
+; This program is free software: you can redistribute it and/or modify
+; it under the terms of the GNU General Public License as published by
+; the Free Software Foundation, either version 3 of the License, or
+; (at your option) any later version.
+;
+; This program is distributed in the hope that it will be useful,
+; but WITHOUT ANY WARRANTY; without even the implied warranty of
+; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+; GNU General Public License for more details.
+;
+; You should have received a copy of the GNU General Public License
+; along with this program. If not, see <http://www.gnu.org/licenses/>.
+
+# NAME
+
+rnsp - Rad-Net Surface Properties file format
+
+# DESCRIPTION
+
+*rnsp* is a binary file format for storing surface mesh properties. The
+properties are listed by geometric primitive (for example by triangle). The mesh
+to which the properties are attached is _not_ described there but must be
+defined in a separate file, for example in an *smsh*(5) file. The number of
+available properties and their order should match the geometric primitives
+listed in the corresponding mesh.
+
+An *rnsp* file is actually a Star-Buffer file (see *sbuf*(5)). It starts with a
+header of 4 64-bit integers describing the layout of the data. The first integer
+is a power of two (usually 4096) that defines the size of the memory page in
+bytes to which the list of properties aligns (_pagesize_). The second integer
+is the _size_ of the array, i.e. the number of property sets in the list.
+Finally, the 2 remaining integers store the memory size (8 octets) and the
+memory alignment (8 octets) of the property set defined by geometric primitive.
+
+Padding bytes follow the file header to align the listed properties to
+_pagesize_.
+
+For each geometric primitive, the properties are composed of a 32-bit integer,
+which is the material identifier of the primitive (_matid_), and a 32-bit
+floating-point number that stores temperature in Kelvin.
+
+The end of the file is eventually padded with dummy bytes to ensure that the
+overall file size is a multiple of _pagesize_.
+
+# BINARY FILE FORMAT
+
+Data are encoded with respect to the little endian bytes ordering, i.e. least
+significant bytes are stored first.
+
+```
+<rnsp> ::= <pagesize> <size> 8 8
+ <padding>
+ <properties>
+ <padding>
+
+<pagesize> ::= UINT64
+<size> ::= UINT64 # Number of items stored
+
+---
+
+<properties> ::= <property> ... ...
+<property> ::= <matid> <temperature>
+<matid> ::= UINT32
+<temperature> ::= FLOAT # In K
+
+---
+
+<padding> ::= [ BYTE ... ] # Ensure alignement
+```
+
+# SEE ALSO
+
+*smsh*(5)
