Documentation|BspLeaf|BspNode|Segment: Improved apidocs for BspLeaf, …

…BspNode and Segment

doomsday/client/include/map/bspleaf.h

@@ -1,4 +1,4 @@
-/** @file map/bspleaf.h World Map BSP Leaf.
+/** @file world/bspleaf.h World BSP Leaf.
  *
  * @authors Copyright © 2003-2013 Jaakko Keränen <jaakko.keranen@iki.fi>
  * @authors Copyright © 2006-2013 Daniel Swanson <danij@dengine.net>
@@ -18,17 +18,15 @@
  * 02110-1301 USA</small>
  */
 
-#ifndef DENG_WORLD_MAP_BSPLEAF
-#define DENG_WORLD_MAP_BSPLEAF
+#ifndef DENG_WORLD_BSPLEAF_H
+#define DENG_WORLD_BSPLEAF_H
 
 #include <QList>
 
 #include <de/Error>
 #include <de/Vector>
 
 #include "MapElement"
-#include "Face"
-#include "HEdge"
 #include "Line"
 #include "Mesh"
 
@@ -39,15 +37,22 @@ struct polyobj_s;
 #ifdef __CLIENT__
 struct BiasSurface;
 struct ShadowLink;
-#endif // __CLIENT__
+#endif
 
 /**
- * Map data element describing a @em leaf in a binary space partition tree (BSP)
- * (a two dimensioned convex polygon).
+ * Represents a leaf in the map's binary space partition (BSP) tree. Each leaf
+ * defines a two dimensioned convex subspace region (which, may be represented
+ * by a face (polygon) in the map's half-edge @ref Mesh geometry).
+ *
+ * On client side a leaf also provides / links to various geometry data assets
+ * and properties used to visualize the subspace.
+ *
+ * Each leaf is attributed to a @ref Sector in the map (with the exception of
+ * wholly degenerate subspaces which may occur during the partitioning process).
  *
  * @see http://en.wikipedia.org/wiki/Binary_space_partitioning
  *
- * @ingroup map
+ * @ingroup world
  */
 class BspLeaf : public de::MapElement
 {
@@ -93,28 +98,23 @@ class BspLeaf : public de::MapElement
     inline bool isDegenerate() const { return !hasFace(); }
 
     /**
-     * Determines whether a convex face geometry (a polygon) is assigned to the
-     * BSP leaf.
+     * Determines whether a convex face geometry (a polygon) is assigned.
      *
      * @see face(), setFace()
      */
     bool hasFace() const;
 
     /**
-     * Provides access to the convex face geometry (a polygon) assigned to the
-     * BSP leaf.
+     * Provides access to the assigned convex face geometry (a polygon).
      *
      * @see hasFace(), assignPoly()
      */
-    de::Face &face();
-
-    /// @copydoc face()
     de::Face const &face() const;
 
     /**
-     * Change the polygon geometry assigned to the BSP leaf. Before the geometry
-     * is accepted it is first conformance tested to ensure that it represents
-     * a valid, simple convex polygon.
+     * Change the convex face geometry assigned to the BSP leaf. Before the
+     * geometry is accepted it is first conformance tested to ensure that it
+     * represents a valid, simple convex polygon.
      *
      * @param polygon  New polygon to be assigned to the BSP leaf. Ownership
      *                 of the polygon is given to the BspLeaf if it passes all
@@ -125,9 +125,9 @@ class BspLeaf : public de::MapElement
     void assignPoly(de::Mesh *polygon);
 
     /**
-     * Assign an additional mesh geometry to the BSP leaf. Such @em extra meshes
-     * are used to represent geometry which would result in a non-manifold mesh
-     * if incorporated in the primary mesh for the map.
+     * Assign an additional mesh geometry to the BSP leaf. Such @em extra
+     * meshes are used to represent geometry which would otherwise result in a
+     * non-manifold mesh if incorporated in the primary mesh for the map.
      *
      * @param mesh  New mesh to be assigned to the BSP leaf. Ownership of the
      *              mesh is given to the BspLeaf.
@@ -143,17 +143,17 @@ class BspLeaf : public de::MapElement
     Segments const &clockwiseSegments() const;
 
     /**
-     * Provides a list of all the line segments from the convex face geometry and
-     * any @em extra meshes assigned to the BSP leaf.
+     * Provides a list of all the line segments from the convex face geometry
+     * and any @em extra meshes assigned to the BSP leaf.
      *
      * @see clockwiseSegments(), assignExtraMesh()
      */
     Segments const &allSegments() const;
 
     /**
-     * Returns @c true iff a sector is attributed to the BSP leaf. The only time
-     * a leaf might not be attributed to a sector is if the map geometry was
-     * @em orphaned by the partitioning algorithm (a bug).
+     * Returns @c true iff a sector is attributed to the BSP leaf. The only
+     * time a leaf might not be attributed to a sector is if the map geometry
+     * was @em orphaned by the partitioning algorithm (a bug).
      */
     bool hasSector() const;
 
@@ -182,8 +182,8 @@ class BspLeaf : public de::MapElement
     void setSector(Sector *newSector);
 
     /**
-     * Determines whether the BSP leaf has a positive world volume. For this to
-     * be true the following criteria must be met:
+     * Determines whether the BSP leaf has a positive world volume. For this
+     * to be true the following criteria must be met:
      *
      * - The polygon geometry is @em not degenerate (see @ref isDegenerate()).
      * - A sector is attributed (see @ref hasSector())
@@ -196,7 +196,7 @@ class BspLeaf : public de::MapElement
     bool hasWorldVolume(bool useVisualHeights = true) const;
 
     /**
-     * Returns @c true iff there is at least one polyobj linked with the BSP leaf.
+     * Returns @c true iff at least one polyobj is linked to the BSP leaf.
      */
     inline bool hasPolyobj() { return firstPolyobj() != 0; }
 
@@ -235,43 +235,53 @@ class BspLeaf : public de::MapElement
 #ifdef __CLIENT__
 
     /**
-     * Returns a pointer to the half-edge of the BSP leaf which has been chosen for
-     * use as the base for a triangle fan geometry. May return @c 0 if no suitable
-     * base was determined.
+     * Returns a pointer to the face geometry half-edge which has been chosen
+     * for use as the base for a triangle fan GL primitive. May return @c 0 if
+     * no suitable base was determined.
      */
     de::HEdge *fanBase() const;
 
     /**
-     * Returns the number of vertices needed for the BSP leaf's triangle fan.
-     * @note May incurr updating the fan base half-edge if not already determined.
+     * Returns the number of vertices needed for a triangle fan GL primitive.
+     *
+     * @note When first called after a face geometry is assigned a new 'base'
+     * half-edge for the triangle fan primitive will be determined.
      *
      * @see fanBase()
      */
     int numFanVertices() const;
 
     /**
-     * Retrieve the bias surface for specified geometry @a groupId
+     * Retrieve the bias surface for specified geometry @a group.
      *
-     * @param groupId  Geometry group identifier for the bias surface.
+     * @param group  Geometry group identifier for the bias surface.
      */
-    BiasSurface &biasSurface(int groupId);
+    BiasSurface &biasSurface(int group);
 
-    void setBiasSurface(int groupId, BiasSurface *biasSurface);
+    /**
+     * Assign a new bias surface to the specified geometry @a group.
+     *
+     * @param group        Geometry group identifier for the surface.
+     * @param biasSurface  New BiasSurface for the identified @a group. Any
+     *                     existing bias surface will be replaced (destroyed).
+     *                     Ownership is given to the BSP leaf.
+     */
+    void setBiasSurface(int group, BiasSurface *biasSurface);
 
     /**
-     * Returns the first ShadowLink associated with the BSP leaf; otherwise @c 0.
+     * Returns a pointer to the first ShadowLink; otherwise @c 0.
      */
     ShadowLink *firstShadowLink() const;
 
     /**
-     * Returns the frame number of the last time sprites were projected for the
-     * BSP leaf.
+     * Returns the frame number of the last time mobj sprite projection was
+     * performed for the BSP leaf.
      */
     int addSpriteCount() const;
 
     /**
-     * Change the frame number of the last time sprites were projected for the
-     * BSP leaf.
+     * Change the frame number of the last time mobj sprite projection was
+     * performed for the BSP leaf.
      *
      * @param newFrameCount  New frame number.
      */
@@ -286,4 +296,4 @@ class BspLeaf : public de::MapElement
     DENG2_PRIVATE(d)
 };
 
-#endif // DENG_WORLD_MAP_BSPLEAF
+#endif // DENG_WORLD_BSPLEAF_H

doomsday/client/include/map/bspnode.h

@@ -1,4 +1,4 @@
-/** @file map/bspnode.h World Map BSP Node.
+/** @file world/bspnode.h World BSP Node.
  *
  * @authors Copyright © 2003-2013 Jaakko Keränen <jaakko.keranen@iki.fi>
  * @authors Copyright © 2006-2013 Daniel Swanson <danij@dengine.net>
@@ -18,8 +18,8 @@
  * 02110-1301 USA</small>
  */
 
-#ifndef DENG_WORLD_MAP_BSPNODE
-#define DENG_WORLD_MAP_BSPNODE
+#ifndef DENG_WORLD_BSPNODE_H
+#define DENG_WORLD_BSPNODE_H
 
 #include <de/aabox.h>
 
@@ -29,47 +29,51 @@
 #include "partition.h"
 
 /**
- * Node in the BSP tree. Children of a node can be either instances of BspNode
- * or BspLeaf.
+ * Represents a node in the map's binary space partition (BSP) tree. Each node
+ * defines a partition line which divides the subspace in two, a left child and
+ * a right child subspace. Each child may be associated with either another node,
+ * or a @ref BspLeaf.
  *
- * @todo There is a missing abstraction here. BSP tree elements should be derived
- *       from a common base class, thereby enforcing which objects can be linked
- *       into the tree. -ds
+ * @todo There is a missing abstraction here. All BSP tree elements should be
+ * derived from a common base class, thereby enforcing which objects can be
+ * linked into the tree. -ds
  *
- * @ingroup map
+ * @see http://en.wikipedia.org/wiki/Binary_space_partitioning
+ *
+ * @ingroup world
  */
 class BspNode : public de::MapElement
 {
 public:
-    /// Required child element is missing. @ingroup errors
-    DENG2_ERROR(MissingChildError);
-
     /// An invalid child element was specified. @ingroup errors
     DENG2_ERROR(InvalidChildError);
 
+    /// Required child element is missing. @ingroup errors
+    DENG2_ERROR(MissingChildError);
+
     /// Child element identifiers:
     enum { Right, Left };
 
 public:
-    BspNode(de::Partition const &partition);
+    BspNode(de::Partition const &partition = de::Partition());
 
     /**
-     * Returns the Partition for the BSP node.
+     * Returns the binary space partition at this BSP node.
      */
     de::Partition const &partition() const;
 
     /**
-     * Returns @c true iff the specified child is configured for the BSP node.
+     * Returns @c true iff the specified child is configured.
      */
     bool hasChild(int left) const;
 
     /**
-     * Returns @c true iff a Right child element is configured for the BSP node.
+     * Returns @c true iff a Right child element is configured.
      */
     inline bool hasRight() const { return hasChild(Right); }
 
     /**
-     * Returns @c true iff a Left child element is configured for the BSP node.
+     * Returns @c true iff a Left child element is configured.
      */
     inline bool hasLeft() const { return hasChild(Left); }
 
@@ -83,8 +87,8 @@ class BspNode : public de::MapElement
     de::MapElement &child(int left) const;
 
     /**
-     * Returns a pointer to the specified child of the BSP node, which may be @c 0
-     * if no child is configured.
+     * Returns a pointer to the specified child of the BSP node, which may be
+     * @c 0 if no child is configured.
      *
      * @param left  If not @c 0 return the Left child; otherwise the Right child.
      *
@@ -101,23 +105,23 @@ class BspNode : public de::MapElement
     inline void setLeft(de::MapElement *newChild) { setChild(Left, newChild); }
 
     /**
-     * Returns the axis-aligned bounding box for the specified child, which, encompases
-     * all the vertexes which define the geometry of that subspace of the BSP, in map
-     * coordinate space units.
+     * Returns the axis-aligned bounding box for the specified child, which,
+     * encompases all the vertexes which define the geometry of that subspace
+     * of the BSP, in map coordinate space units.
      */
     AABoxd const &childAABox(int left) const;
 
     /**
-     * Returns the axis-aligned bounding box for the Right child, which, encompases all
-     * the vertexes which define the geometry of that subspace of the BSP, in map
-     * coordinate space units.
+     * Returns the axis-aligned bounding box for the Right child, which,
+     * encompases all the vertexes which define the geometry of that subspace
+     * of the BSP, in map coordinate space units.
      */
     inline AABoxd const &rightAABox() const { return childAABox(Right); }
 
     /**
-     * Returns the axis-aligned bounding box for the Left child, which, encompases all
-     * the vertexes which define the geometry of that subspace of the BSP, in map
-     * coordinate space units.
+     * Returns the axis-aligned bounding box for the Left child, which,
+     * encompases all the vertexes which define the geometry of that subspace
+     * of the BSP, in map coordinate space units.
      */
     inline AABoxd const &leftAABox() const { return childAABox(Left); }
 
@@ -131,4 +135,4 @@ class BspNode : public de::MapElement
     DENG2_PRIVATE(d)
 };
 
-#endif // DENG_WORLD_MAP_BSPNODE
+#endif // DENG_WORLD_BSPNODE_H

doomsday/client/include/map/segment.h

@@ -236,13 +236,21 @@ class Segment : public de::MapElement
 #ifdef __CLIENT__
 
     /**
-     * Retrieve the bias surface for specified geometry @a groupId
+     * Retrieve the bias surface for specified geometry @a group.
      *
-     * @param groupId  Geometry group identifier for the bias surface.
+     * @param group  Geometry group identifier for the bias surface.
      */
-    BiasSurface &biasSurface(int groupId);
+    BiasSurface &biasSurface(int group);
 
-    void setBiasSurface(int groupId, BiasSurface *biasSurface);
+    /**
+     * Assign a new bias surface to the specified geometry @a group.
+     *
+     * @param group        Geometry group identifier for the surface.
+     * @param biasSurface  New BiasSurface for the identified @a group. Any
+     *                     existing bias surface will be replaced (destroyed).
+     *                     Ownership is given to the segment.
+     */
+    void setBiasSurface(int group, BiasSurface *biasSurface);
 
 #endif // __CLIENT__