World|BspLeaf: Cleanup, updated API docs

doomsday/client/include/world/bspleaf.h

@@ -1,7 +1,6 @@
-/** @file bspleaf.h  World map BSP leaf.
+/** @file bspleaf.h  World map BSP leaf half-space.
  *
- * @authors Copyright © 2003-2013 Jaakko Keränen <jaakko.keranen@iki.fi>
- * @authors Copyright © 2006-2014 Daniel Swanson <danij@dengine.net>
+ * @authors Copyright © 2014 Daniel Swanson <danij@dengine.net>
  *
  * @par License
  * GPL: http://www.gnu.org/licenses/gpl.html
@@ -23,33 +22,25 @@
 
 #include <de/Error>
 #include "MapElement"
-#include "ConvexSubspace"
-#include "Sector"
 
-class SectorCluster;
+class ConvexSubspace;
+class Sector;
 
 /**
  * Represents a leaf in the map's binary space partition (BSP) tree. Each leaf
  * defines a half-space of the parent space (a node, or the whole map space).
  *
- * A leaf may be assigned a two dimensioned convex subspace geometry, which, is
- * represented by a face (polygon) in the map's half-edge @ref de::Mesh.
+ * A leaf may be assigned a two dimensioned ConvexSubspace geometry.
  *
  * Each leaf is attributed to a @ref Sector in the map regardless of whether a
- * closed convex geometry exists at the leaf.
- *
- * On client side a leaf also provides / links to various geometry data assets
- * and properties used to visualize the subspace.
+ * convex geometry exists at the leaf.
  *
  * @see http://en.wikipedia.org/wiki/Binary_space_partitioning
  *
  * @ingroup world
  */
 class BspLeaf : public de::MapElement
 {
-    DENG2_NO_COPY  (BspLeaf)
-    DENG2_NO_ASSIGN(BspLeaf)
-
 public:
     /// Required subspace is missing. @ingroup errors
     DENG2_ERROR(MissingSubspaceError);
@@ -59,45 +50,32 @@ class BspLeaf : public de::MapElement
      * Construct a new BSP leaf and optionally attribute it to @a sector.
      * Ownership is unaffected.
      */
-    explicit BspLeaf(Sector *sector = 0);
-
-    /**
-     * Convenient method of returning the parent sector of the BSP leaf.
-     */
-    inline Sector &sector() { return parent().as<Sector>(); }
-
-    /// @copydoc sector()
-    inline Sector const &sector() const { return parent().as<Sector>(); }
+    BspLeaf(Sector *sector = 0);
 
     /**
-     * Convenient method returning a pointer to the sector attributed to the
-     * BSP leaf. If not attributed then @c 0 is returned.
-     *
-     * @see sector()
-     */
-    inline Sector *sectorPtr() { return hasParent()? &sector() : 0; }
-
-    /// @copydoc sectorPtr()
-    inline Sector const *sectorPtr() const { return hasParent()? &sector() : 0; }
-
-    /**
-     * Determines whether a subspace geometry is attributed to the BSP leaf.
+     * Determines whether a subspace geometry is assigned to the BSP leaf half-space.
      *
      * @see subspace(), setSubspace()
      */
     bool hasSubspace() const;
 
     /**
-     * Returns the ConvexSubspace attributed to the BSP leaf.
+     * Returns the subspace assigned to the BSP leaf half-space.
      *
      * @see hasSubspace()
      */
     ConvexSubspace &subspace() const;
 
+    /**
+     * Convenient method returning a pointer to the ConvexSubspace assigned to
+     * the BSP leaf half-space; otherwise @c 0 if no subspace is assigned.
+     *
+     * @see subspace(), hasSubspace()
+     */
     inline ConvexSubspace *subspacePtr() const { return hasSubspace()? &subspace() : 0; }
 
     /**
-     * Change the subspace geometry attributed to the BSP leaf.
+     * Change the subspace geometry assigned to the BSP leaf.
      *
      * @param newSubspace New subspace to attribute to the BSP leaf. Ownership
      *                    of the subspace is given to BspLeaf. Use @c 0 to clear
@@ -107,19 +85,19 @@ class BspLeaf : public de::MapElement
      */
     void setSubspace(ConvexSubspace *newSubspace);
 
-public: /// Convenience accessors @todo remove ---------------------------------
-
-    inline bool hasPoly() const              { return hasSubspace(); }
-    inline de::Face const &poly() const      { return subspace().poly(); }
-    inline SectorCluster &cluster() const    { return subspace().cluster(); }
-
-    inline bool hasCluster() const           {
-        return hasSubspace() && subspace().hasCluster();
-    }
+    /**
+     * Convenient method returning a pointer to the Sector attributed to the BSP
+     * leaf half-space.
+     *
+     * Note that this does @em not necessarily mean there is a subspace at this
+     * leaf. Usually one should resolve the sector from the subspace. This method
+     * is primarily intended for legacy compatibility logics which don't care if
+     * subspace exists at the leaf or not.
+     */
+    Sector *sectorPtr();
 
-    inline SectorCluster *clusterPtr() const {
-        return hasSubspace()? subspace().clusterPtr() : 0;
-    }
+    /// @copydoc sectorPtr()
+    Sector const *sectorPtr() const;
 
 private:
     DENG2_PRIVATE(d)

doomsday/client/include/world/convexsubspace.h

@@ -38,6 +38,9 @@ class Lumobj;
 #endif
 
 /**
+ * On client side a convex subspace also provides / links to various geometry
+ * data assets and properties used to visualize the subspace.
+ *
  * @ingroup world
  */
 class ConvexSubspace : public de::MapElement

doomsday/client/include/world/p_object.h

@@ -122,20 +122,20 @@ dd_bool Mobj_SetOrigin(mobj_t *mobj, coord_t x, coord_t y, coord_t z);
 BspLeaf &Mobj_BspLeafAtOrigin(mobj_t const &mobj);
 
 /**
- * Returns @c true iff the sector cluster at the mobj's origin is known (i.e.,
- * it has been linked into the map by calling @ref Mobj_SetOrigin() and the BSP
- * leaf at the origin has a convex geometry (not degenerate)).
+ * Returns @c true iff the BSP leaf at the mobj's origin is known (i.e.,
+ * it has been linked into the map by calling @ref Mobj_SetOrigin() and has a
+ * convex geometry).
  *
  * @param mobj  Mobj instance.
  */
-bool Mobj_HasCluster(mobj_t const &mobj);
+bool Mobj_HasSubspace(mobj_t const &mobj);
 
 /**
  * Returns the sector cluster in which the mobj currently resides.
  *
  * @param mobj  Mobj instance.
  *
- * @see Mobj_HasCluster()
+ * @see Mobj_HasSubspace()
  */
 SectorCluster &Mobj_Cluster(mobj_t const &mobj);
 

doomsday/client/src/edit_bias.cpp

@@ -26,6 +26,7 @@
 
 #include "world/map.h"
 #include "world/p_players.h" // viewPlayer
+#include "ConvexSubspace"
 #include "Hand"
 #include "HueCircle"
 #include "render/viewports.h"
@@ -585,12 +586,12 @@ static void drawLightGauge(Vector2i const &origin, int height = 255)
     else
         source = map.biasSourceNear(hand.origin());
 
-    if(SectorCluster *cluster = source->bspLeafAtOrigin().clusterPtr())
+    if(ConvexSubspace *subspace = source->bspLeafAtOrigin().subspacePtr())
     {
-        if(lastCluster != cluster)
+        if(subspace->hasCluster() && lastCluster != subspace->clusterPtr())
         {
-            minLevel = maxLevel = cluster->lightSourceIntensity();
-            lastCluster = cluster;
+            lastCluster = &subspace->cluster();
+            minLevel = maxLevel = lastCluster->lightSourceIntensity();
         }
     }
 

doomsday/client/src/render/biasillum.cpp

@@ -22,6 +22,7 @@
 #include "world/map.h"
 #include "world/linesighttest.h"
 #include "BspLeaf"
+#include "ConvexSubspace"
 #include "SectorCluster"
 #include "Surface"
 #include "BiasTracker"
@@ -144,18 +145,19 @@ DENG2_PIMPL_NOREF(BiasIllum)
         Vector3f &casted = contribution(index);
 
         /// @todo LineSightTest should (optionally) perform this test.
-        SectorCluster *cluster = source.bspLeafAtOrigin().clusterPtr();
-        if(!cluster)
+        ConvexSubspace *subspace = source.bspLeafAtOrigin().subspacePtr();
+        if(!subspace)
         {
             // This affecting source does not contribute any light.
             casted = Vector3f();
             return;
         }
 
-        if((!cluster->visFloor().surface().hasSkyMaskedMaterial() &&
-                source.origin().z < cluster->visFloor().heightSmoothed()) ||
-           (!cluster->visCeiling().surface().hasSkyMaskedMaterial() &&
-                source.origin().z > cluster->visCeiling().heightSmoothed()))
+        SectorCluster &cluster = subspace->cluster();
+        if((!cluster.visFloor().surface().hasSkyMaskedMaterial() &&
+                source.origin().z < cluster.visFloor().heightSmoothed()) ||
+           (!cluster.visCeiling().surface().hasSkyMaskedMaterial() &&
+                source.origin().z > cluster.visCeiling().heightSmoothed()))
         {
             casted = Vector3f();
             return;

doomsday/client/src/render/biassource.cpp

@@ -22,6 +22,7 @@
 #include "world/worldsystem.h"
 #include "world/map.h"
 #include "BspLeaf"
+#include "ConvexSubspace"
 #include "SectorCluster"
 
 #include "BiasDigest"
@@ -278,18 +279,20 @@ bool BiasSource::trackChanges(BiasDigest &changes, uint digestIndex, uint curren
         float const oldIntensity = intensity();
         float newIntensity = 0;
 
-        if(SectorCluster *cluster = d->bspLeaf->clusterPtr())
+        if(ConvexSubspace *subspace = d->bspLeaf->subspacePtr())
         {
+            SectorCluster &cluster = subspace->cluster();
+
             // Lower intensities are useless for light emission.
-            if(cluster->lightSourceIntensity() >= d->maxLight)
+            if(cluster.lightSourceIntensity() >= d->maxLight)
             {
                 newIntensity = d->primaryIntensity;
             }
 
-            if(cluster->lightSourceIntensity() >= d->minLight && d->minLight != d->maxLight)
+            if(cluster.lightSourceIntensity() >= d->minLight && d->minLight != d->maxLight)
             {
                 newIntensity = d->primaryIntensity *
-                    (cluster->lightSourceIntensity() - d->minLight) / (d->maxLight - d->minLight);
+                    (cluster.lightSourceIntensity() - d->minLight) / (d->maxLight - d->minLight);
             }
         }
 

doomsday/client/src/render/lightdecoration.cpp

@@ -27,6 +27,7 @@
 
 #include "world/map.h"
 #include "BspLeaf"
+#include "ConvexSubspace"
 #include "SectorCluster"
 #include "Surface"
 
@@ -77,11 +78,11 @@ Lumobj *LightDecoration::generateLumobj() const
     if(source().color == Vector3f(0, 0, 0))
         return 0;
 
-    SectorCluster *cluster = bspLeafAtOrigin().clusterPtr();
-    if(!cluster) return 0;
+    ConvexSubspace *subspace = bspLeafAtOrigin().subspacePtr();
+    if(!subspace) return 0;
 
     // Does it pass the ambient light limitation?
-    float lightLevel = cluster->lightSourceIntensity();
+    float lightLevel = subspace->cluster().lightSourceIntensity();
     Rend_ApplyLightAdaptation(lightLevel);
 
     float intensity = checkLightLevel(lightLevel,

doomsday/client/src/render/r_main.cpp

@@ -34,6 +34,7 @@
 #include "world/map.h"
 #include "world/p_players.h"
 #include "BspLeaf"
+#include "ConvexSubspace"
 #include "SectorCluster"
 
 #include <de/GLState>
@@ -119,7 +120,7 @@ static void setupPSpriteParams(rendpspriteparams_t *params, vispsprite_t *spr)
         }
         else
         {
-            Vector4f const color = spr->data.sprite.bspLeaf->cluster().lightSourceColorfIntensity();
+            Vector4f const color = spr->data.sprite.bspLeaf->subspace().cluster().lightSourceColorfIntensity();
 
             // No need for distance attentuation.
             float lightLevel = color.w;
@@ -249,7 +250,7 @@ static void setupModelParamsForVisPSprite(vissprite_t &vis, vispsprite_t const *
         }
         else
         {
-            Vector4f const color = spr->data.model.bspLeaf->cluster().lightSourceColorfIntensity();
+            Vector4f const color = spr->data.model.bspLeaf->subspace().cluster().lightSourceColorfIntensity();
 
             // No need for distance attentuation.
             float lightLevel = color.w;

doomsday/client/src/render/r_things.cpp

@@ -189,7 +189,7 @@ void R_ProjectSprite(mobj_t *mo)
     // ...hidden?
     if((mo->ddFlags & DDMF_DONTDRAW)) return;
     // ...not linked into the map?
-    if(!Mobj_HasCluster(*mo)) return;
+    if(!Mobj_HasSubspace(*mo)) return;
     // ...in an invalid state?
     if(!mo->state || !runtimeDefs.states.indexOf(mo->state)) return;
     // ...no sprite frame is defined?

doomsday/client/src/render/rend_main.cpp

@@ -47,6 +47,7 @@
 #include "BspLeaf"
 #include "BspNode"
 #include "Contact"
+#include "ConvexSubspace"
 #include "Hand"
 #include "SectorCluster"
 #include "Surface"

doomsday/client/src/render/rend_particle.cpp

@@ -32,6 +32,7 @@
 #include "world/map.h"
 #include "world/p_players.h"
 #include "BspLeaf"
+#include "ConvexSubspace"
 #include "Line"
 #include "Plane"
 #include "SectorCluster"
@@ -451,7 +452,7 @@ static void setupModelParamsForParticle(vissprite_t &spr,
         }
         else
         {
-            Vector4f const color = pinfo->bspLeaf->cluster().lightSourceColorfIntensity();
+            Vector4f const color = pinfo->bspLeaf->subspace().cluster().lightSourceColorfIntensity();
 
             float lightLevel = color.w;
 
@@ -627,9 +628,9 @@ static void renderParticles(int rtype, bool withBlend)
         {
             // This is a simplified version of sectorlight (no distance
             // attenuation or range compression).
-            if(SectorCluster *cluster = pinfo->bspLeaf->clusterPtr())
+            if(ConvexSubspace *subspace = pinfo->bspLeaf->subspacePtr())
             {
-                float const lightLevel = cluster->lightSourceIntensity();
+                float const lightLevel = subspace->cluster().lightSourceIntensity();
                 color *= Vector4f(lightLevel, lightLevel, lightLevel, 1);
             }
         }
@@ -663,10 +664,11 @@ static void renderParticles(int rtype, bool withBlend)
         bool nearWall = (pinfo->contact && !pinfo->mov[VX] && !pinfo->mov[VY]);
 
         bool nearPlane = false;
-        if(SectorCluster *cluster = pinfo->bspLeaf->clusterPtr())
+        if(ConvexSubspace *subspace = pinfo->bspLeaf->subspacePtr())
         {
-            if(FLT2FIX(cluster->  visFloor().heightSmoothed()) + 2 * FRACUNIT >= pinfo->origin[VZ] ||
-               FLT2FIX(cluster->visCeiling().heightSmoothed()) - 2 * FRACUNIT <= pinfo->origin[VZ])
+            SectorCluster &cluster = subspace->cluster();
+            if(FLT2FIX(cluster.  visFloor().heightSmoothed()) + 2 * FRACUNIT >= pinfo->origin[VZ] ||
+               FLT2FIX(cluster.visCeiling().heightSmoothed()) - 2 * FRACUNIT <= pinfo->origin[VZ])
             {
                 nearPlane = true;
             }

doomsday/client/src/render/viewports.cpp

@@ -37,6 +37,7 @@
 #include "world/p_object.h"
 #include "world/p_players.h"
 #include "BspLeaf"
+#include "ConvexSubspace"
 #include "SectorCluster"
 #include "Surface"
 #include "Contact"
@@ -743,7 +744,7 @@ static void setupPlayerSprites()
         return;
     mobj_t *mo = ddpl->mo;
 
-    if(!Mobj_HasCluster(*mo))
+    if(!Mobj_HasSubspace(*mo))
         return;
     SectorCluster &cluster = Mobj_Cluster(*mo);
 

doomsday/client/src/world/api_map.cpp

@@ -43,6 +43,7 @@
 #include "world/maputil.h"
 #include "world/worldsystem.h"
 #include "BspLeaf"
+#include "ConvexSubspace"
 #include "Interceptor"
 
 #ifdef __CLIENT__