commit 04c0417dd95581bf2ca158820db4aa277ed717f6
parent 3d6f5bd34402a9cbf1ecefd479c47e6df772593f
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Tue, 27 Feb 2018 21:59:25 +0100
Update the brief explanation of the octree buffer memory layout
Diffstat:
1 file changed, 20 insertions(+), 16 deletions(-)
diff --git a/src/htvox_octree_buffer.h b/src/htvox_octree_buffer.h
@@ -20,18 +20,23 @@
#include <rsys/dynamic_array.h>
/*
- * Buffer of octree data partitioned in fixed sized memory pages.
+ * Buffer containing the data of an octree. These data are partitioned in fixed
+ * size memory pages whose capacity is defined on buffer initialisation with
+ * respect to the page size of the system.
*
- * The nodes are stored in pages whose memory size is defined at the init of
- * the buffer. The node children are indexed relatively to their parent node
- * excepted if the relative offset is too high regarding the encoding precision
- * of the offset, or if the children are stored in another page. In such cases,
- * the node relatively references an 'octree_index', allocated in the same
- * page, that defines the absolute position of the children in the buffer.
+ * The children of a node are stored consecutively into a page. The parent node
+ * directly references its first valid children excepted if they lie in a
+ * different page. In this case, the node references a `struct octree_index',
+ * stored into the same page, that defines the absolute position of its first
+ * valid child into the whole list of node pages
*
- * Leaf attributes are stored in a separate buffer and are indexed either
- * relatively, or absolutely by the leaf node storing, following the same
- * aforementioned indexing procedure of the node children.
+ * The data of the leaves are stored in their own of memory pages. The leaves
+ * of a node are stored consecutively into a page. If the page identifier of
+ * the leaves is the same of the page into which their parent node lies, then
+ * the node saves the index toward the first valid leaf into the page of
+ * leaves. In the other case, the node references a `struct octree_index',
+ * stored into the same page of the node, that defines the absolute position of
+ * its first valid leaf into the buffer of leaves.
*/
#define OCTREE_XNODE_FLAG_FAR_INDEX (1u<<15)
@@ -39,11 +44,10 @@
#define OCTREE_XNODE_MASK OCTREE_XNODE_MAX_CHILDREN_OFFSET
struct octree_xnode {
- /* Relative offset to retrieve the children. If the
- * OCTREE_XNODE_FLAG_FAR_INDEX bit is not set, the children are stored in the
- * same page at the position `offset & OCTREE_XNODE_MASK'. If
- * OCTREE_XNODE_FLAG_FAR_INDEX is set, `offset & OCTREE_XNODE_MASK' reference
- * an octree_index toward the node children */
+ /* Offset to retrieve the children. If the OCTREE_XNODE_FLAG_FAR_INDEX bit is
+ * not set, the children are stored in the same page at the position `offset
+ * & OCTREE_XNODE_MASK'. If OCTREE_XNODE_FLAG_FAR_INDEX is set, `offset &
+ * OCTREE_XNODE_MASK' reference an octree_index toward the node children */
uint16_t node_offset;
uint16_t leaf_offset;
uint8_t is_valid; /* Mask defining if the children are valid */
@@ -104,7 +108,7 @@ octree_buffer_alloc_leaves
const size_t nleaves,
struct octree_index* first_leaf); /* Index toward the 1st allocated leaf */
-/* Allocate a octree_index in the current buffer page. Return RES_MEM_ERR if
+/* Allocate an octree_index in the current buffer page. Return RES_MEM_ERR if
* the node index cannot be allocated in the current page. In this case one
* have to alloc new nodes */
extern LOCAL_SYM res_T
