From 9e564ec5e3d1901394b08a478ca48c4138dbcf3a Mon Sep 17 00:00:00 2001 From: danij Date: Fri, 7 Jun 2013 04:57:54 +0100 Subject: [PATCH] Documentation|BspLeaf|BspNode|Segment: Improved apidocs for BspLeaf, BspNode and Segment --- doomsday/client/include/map/bspleaf.h | 100 ++++++++++++++------------ doomsday/client/include/map/bspnode.h | 62 ++++++++-------- doomsday/client/include/map/segment.h | 16 +++-- 3 files changed, 100 insertions(+), 78 deletions(-) diff --git a/doomsday/client/include/map/bspleaf.h b/doomsday/client/include/map/bspleaf.h index 9c7117fa5e..10f591c9bf 100644 --- a/doomsday/client/include/map/bspleaf.h +++ b/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 * @authors Copyright © 2006-2013 Daniel Swanson @@ -18,8 +18,8 @@ * 02110-1301 USA */ -#ifndef DENG_WORLD_MAP_BSPLEAF -#define DENG_WORLD_MAP_BSPLEAF +#ifndef DENG_WORLD_BSPLEAF_H +#define DENG_WORLD_BSPLEAF_H #include @@ -27,8 +27,6 @@ #include #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 diff --git a/doomsday/client/include/map/bspnode.h b/doomsday/client/include/map/bspnode.h index bfef02cd7d..9c591f4e6a 100644 --- a/doomsday/client/include/map/bspnode.h +++ b/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 * @authors Copyright © 2006-2013 Daniel Swanson @@ -18,8 +18,8 @@ * 02110-1301 USA */ -#ifndef DENG_WORLD_MAP_BSPNODE -#define DENG_WORLD_MAP_BSPNODE +#ifndef DENG_WORLD_BSPNODE_H +#define DENG_WORLD_BSPNODE_H #include @@ -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 diff --git a/doomsday/client/include/map/segment.h b/doomsday/client/include/map/segment.h index eb50b91479..eab5a34607 100644 --- a/doomsday/client/include/map/segment.h +++ b/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__