diff --git a/doomsday/engine/portable/include/m_gridmap.h b/doomsday/engine/portable/include/m_gridmap.h index 7fbbabb66e..d2f528f6ef 100644 --- a/doomsday/engine/portable/include/m_gridmap.h +++ b/doomsday/engine/portable/include/m_gridmap.h @@ -1,27 +1,5 @@ -/**\file m_gridmap.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2009-2012 Daniel Swanson - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin St, Fifth Floor, - * Boston, MA 02110-1301 USA - */ - /** + * @file gridmap.h * Gridmap. An abstract class designed for mapping objects into a two * dimensional spatial index. * @@ -29,6 +7,24 @@ * however cells within it need not be populated. Therefore Gridmap may * be considered a "sparse" structure as it allows the user to construct * the space piece-wise or, leave it deliberately incomplete. + * + * @ingroup data + * + * @authors Copyright © 2009-2012 Daniel Swanson + * + * @par License + * GPL: http://www.gnu.org/licenses/gpl.html + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. This program is distributed in the hope that it + * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty + * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General + * Public License for more details. You should have received a copy of the GNU + * General Public License along with this program; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA */ #ifndef LIBDENG_DATA_GRIDMAP_H @@ -64,10 +60,9 @@ typedef struct gridmap_s Gridmap; /** * Create a new initial Gridmap (empty). * - * @param width X dimension in cells. - * @param height Y dimension in cells. - * @param sizeOfCell Amount of memory to be allocated for the - * user data associated with each cell. + * @param width X dimension in cells. + * @param height Y dimension in cells. + * @param sizeOfCell Amount of memory to be allocated for the user data associated with each cell. */ Gridmap* Gridmap_New(uint width, uint height, size_t sizeOfCell, int zoneTag); @@ -81,25 +76,24 @@ uint Gridmap_Height(const Gridmap* gridmap); /** * Retrieve the dimensions of the Gridmap in cells. - * @param widthHeight Dimensions written here. + * @param widthHeight Dimensions written here. */ void Gridmap_Size(const Gridmap* gridmap, uint widthHeight[2]); /** * Retrieve the user data associated with the identified cell. * - * @param coords XY coordinates of the cell whose data to retrieve. - * @param alloc @c true= we should allocate new user data if not - * already present for the selected cell. + * @param coords XY coordinates of the cell whose data to retrieve. + * @param alloc @c true= we should allocate new user data if not already present + * for the selected cell. * - * @return User data for the identified cell else @c NULL if an - * invalid reference or no data present (and not allocating). + * @return User data for the identified cell else @c NULL if an invalid reference or no + * there is no data present (and not allocating). */ void* Gridmap_Cell(Gridmap* gridmap, uint const coords[2], boolean alloc); /** - * Same as Gridmap::Cell except cell coordinates are expressed with - * @a x and @a y arguments. + * Same as Gridmap::Cell except cell coordinates are expressed with @a x and @a y arguments. */ void* Gridmap_CellXY(Gridmap* gridmap, uint x, uint y, boolean alloc); @@ -110,12 +104,11 @@ void* Gridmap_CellXY(Gridmap* gridmap, uint x, uint y, boolean alloc); typedef int (C_DECL *Gridmap_IterateCallback) (void* cellData, void* paramaters); /** - * Iterate over populated cells in the Gridmap making a callback for - * each. Iteration ends when all cells have been visited or @a callback - * returns non-zero. + * Iterate over populated cells in the Gridmap making a callback for each. Iteration ends + * when all cells have been visited or @a callback returns non-zero. * - * @param callback Callback function ptr. - * @param paramaters Passed to the callback. + * @param callback Callback function ptr. + * @param paramaters Passed to the callback. * * @return @c 0 iff iteration completed wholly. */ @@ -123,14 +116,13 @@ int Gridmap_Iterate2(Gridmap* gridmap, Gridmap_IterateCallback callback, void* p int Gridmap_Iterate(Gridmap* gridmap, Gridmap_IterateCallback callback); /*paramaters=NULL*/ /** - * Iterate over a block of populated cells in the Gridmap making a - * callback for each. Iteration ends when all selected cells have been - * visited or @a callback returns non-zero. + * Iterate over a block of populated cells in the Gridmap making a callback for each. + * Iteration ends when all selected cells have been visited or @a callback returns non-zero. * - * @param min Minimal coordinates for the top left cell. - * @param max Maximal coordinates for the bottom right cell. - * @param callback Callback function ptr. - * @param paramaters Passed to the callback. + * @param min Minimal coordinates for the top left cell. + * @param max Maximal coordinates for the bottom right cell. + * @param callback Callback function ptr. + * @param paramaters Passed to the callback. * * @return @c 0 iff iteration completed wholly. */ @@ -140,8 +132,8 @@ int Gridmap_BlockIterate(Gridmap* gridmap, const GridmapBlock* block, Gridmap_IterateCallback callback); /*paramaters=NULL*/ /** - * Same as Gridmap::BlockIterate except cell block coordinates are - * expressed with independent X and Y arguments. For convenience. + * Same as Gridmap::BlockIterate except cell block coordinates are expressed with + * independent X and Y coordinate arguments. For convenience. */ int Gridmap_BlockXYIterate2(Gridmap* gridmap, uint minX, uint minY, uint maxX, uint maxY, Gridmap_IterateCallback callback, void* paramaters); @@ -149,10 +141,11 @@ int Gridmap_BlockXYIterate(Gridmap* gridmap, uint minX, uint minY, uint maxX, ui Gridmap_IterateCallback callback); /*paramaters=NULL*/ /** - * Clip the cell coordinates in @a block vs the dimensions of this - * Gridmap so that they are inside the boundary this defines. + * Clip the cell coordinates in @a block vs the dimensions of this Gridmap so that they + * are inside the boundary this defines. + * + * @param block Block coordinates to be clipped. * - * @param block Block coordinates to be clipped. * @return @c true iff the block coordinates were changed. */ boolean Gridmap_ClipBlock(Gridmap* gm, GridmapBlock* block); @@ -169,15 +162,13 @@ void Gridmap_InitBlock(GridmapBlock* block, uint minX, uint minY, uint maxX, uin /** * Render a visual for this Gridmap to assist in debugging (etc...). * - * This visualizer assumes that the caller has already configured the - * GL render state (projection matrices, scale, etc...) as desired - * prior to calling. This function guarantees to restore the previous - * GL state if any changes are made to it. + * This visualizer assumes that the caller has already configured the GL render state + * (projection matrices, scale, etc...) as desired prior to calling. This function + * guarantees to restore the previous GL state if any changes are made to it. * - * \note Internally this visual uses fixed unit dimensions [1x1] for - * cells, therefore the caller should scale the appropriate matrix to - * scale this visual as desired. + * @note Internally this visual uses fixed unit dimensions [1x1] for cells, therefore + * the caller should scale the appropriate matrix to scale this visual as desired. */ void Gridmap_Debug(Gridmap* gridmap); -#endif /* LIBDENG_DATA_GRIDMAP_H */ +#endif /// LIBDENG_DATA_GRIDMAP_H