Document usage of node masks

apps/opencs/view/render/mask.hpp

@@ -4,7 +4,10 @@
 namespace CSVRender
 {
 
-    /// @note Enumeration values can be changed freely, as long as they do not collide.
+    /// Node masks used on the OSG scene graph in OpenMW-CS.
+    /// @note See the respective file in OpenMW (apps/openmw/mwrender/vismask.hpp)
+    /// for general usage hints about node masks.
+    /// @copydoc MWRender::VisMask
     enum Mask
     {
         // internal use within NifLoader, do not change

apps/openmw/mwrender/vismask.hpp

@@ -5,6 +5,20 @@ namespace MWRender
 {
 
     /// Node masks used for controlling visibility of game objects.
+    /// @par Any node in the OSG scene graph can have a node mask. When traversing the scene graph,
+    /// the node visitor's traversal mask is OR'ed with the node mask. If the result of this test is
+    /// 0, then the node <i>and all its child nodes</i> are not processed.
+    /// @par Important traversal masks are the camera's cull mask (determines what is visible),
+    /// the update visitor mask (what is updated) and the intersection visitor mask (what is
+    /// selectable through mouse clicks or other intersection tests).
+    /// @par In practice, it can be useful to make a "hierarchy" out of the node masks - e.g. in OpenMW,
+    /// all 3D rendering nodes are child of a Scene Root node with Mask_Scene. When we do not want 3D rendering,
+    /// we can just omit Mask_Scene from the traversal mask, and do not need to omit all the individual
+    /// element masks (water, sky, terrain, etc.) since the traversal will already have stopped at the Scene root node.
+    /// @par The comments within the VisMask enum should give some hints as to what masks are commonly "child" of
+    /// another mask, or what type of node this mask is usually set on.
+    /// @note The mask values are not serialized within models, nor used in any other way that would break backwards
+    /// compatibility if the enumeration values were to be changed. Feel free to change them when it makes sense.
     enum VisMask
     {
         Mask_UpdateVisitor = 0x1, // reserved for separating UpdateVisitors from CullVisitors
@@ -24,8 +38,6 @@ namespace MWRender
         Mask_Sun = (1<<10),
         Mask_WeatherParticles = (1<<11),
 
-        // child of Water
-
         // top level masks
         Mask_Scene = (1<<12),
         Mask_GUI = (1<<13),