Another round of doxygen comments

qgis · Sep 24, 2017 · 4bf44d5 · 4bf44d5
1 parent 990f353
commit 4bf44d5
Show file tree

Hide file tree

Showing 12 changed files with 112 additions and 27 deletions.
diff --git a/src/3d/chunks/chunkboundsentity.cpp b/src/3d/chunks/chunkboundsentity.cpp
@@ -9,6 +9,8 @@
 #include "aabb.h"
 
 
+///@cond PRIVATE
+
 class LineMeshGeometry : public Qt3DRender::QGeometry
 {
   public:
@@ -28,6 +30,8 @@ class LineMeshGeometry : public Qt3DRender::QGeometry
 
 };
 
+/// @endcond
+
 LineMeshGeometry::LineMeshGeometry( Qt3DCore::QNode *parent )
   : Qt3DRender::QGeometry( parent )
   , _positionAttribute( new Qt3DRender::QAttribute( this ) )
@@ -67,7 +71,9 @@ void LineMeshGeometry::setVertices( QList<QVector3D> vertices )
 
 // ----------------
 
+///@cond PRIVATE
 
+//! Geometry renderer for axis aligned bounding boxes - draws a box edges as lines
 class AABBMesh : public Qt3DRender::QGeometryRenderer
 {
   public:
@@ -79,6 +85,8 @@ class AABBMesh : public Qt3DRender::QGeometryRenderer
     LineMeshGeometry *_lineMeshGeo;
 };
 
+/// @endcond
+
 AABBMesh::AABBMesh( Qt3DCore::QNode *parent )
   : Qt3DRender::QGeometryRenderer( parent )
   , _lineMeshGeo( nullptr )

diff --git a/src/3d/chunks/chunklist.h b/src/3d/chunks/chunklist.h
@@ -7,6 +7,7 @@ class ChunkNode;
 class ChunkListEntry
 {
   public:
+    //! Constructs entry for a particular node
     ChunkListEntry( ChunkNode *node )
       : prev( nullptr )
       , next( nullptr )
@@ -21,30 +22,49 @@ class ChunkListEntry
 };
 
 
-//! double linked list of chunks.
-//! does not own entries!
+/** \ingroup 3d
+ * Double linked list of chunks.
+ * The list does not own entries.
+ *
+ * Why having another linked list structure if there is already QLinkedList template?
+ * This list implementation allows tighter integration with chunk nodes: they keep
+ * pointers to list entries, so it is possible to locate their entry in the list in constant
+ * time (rather than having to search the whole list). This feature is very useful
+ * in loader and replacement queues where entries are often taken out of the list
+ * and inserted at the front again.
+ * \since QGIS 3.0
+ */
 class ChunkList
 {
   public:
     ChunkList();
 
+    //! Counts the real number of entries by walking the list (for debugging purposes only)
     int trueCount() const;
+    //! Returns number of entries in the list
     int count() const { return mCount; }
 
+    //! Returns the first entry. Null will be returned if the list is empty.
     ChunkListEntry *first() const { return mHead; }
+    //! Returns the last entry. Null will be returned if the list is empty.
     ChunkListEntry *last() const { return mTail; }
+    //! Returns whether the list is empty or it contains some entries
     bool isEmpty() const;
 
+    //! Inserts a new entry before the entry "next".
+    //! If "next" is null, entry will be inserted at the end of the list
     void insertEntry( ChunkListEntry *entry, ChunkListEntry *next );
 
+    //! Takes the entry out of the list (does not delete it)
     void takeEntry( ChunkListEntry *entry );
-
+    //! Takes the first entry from the list and returns it
     ChunkListEntry *takeFirst();
-
+    //! Takes the last entry from the list and returns it
     ChunkListEntry *takeLast();
 
+    //! Inserts an entry at the start of the list
     void insertFirst( ChunkListEntry *entry );
-
+    //! Inserts an entry at the end of the list
     void insertLast( ChunkListEntry *entry );
 
   private:

diff --git a/src/3d/chunks/chunkloader.h b/src/3d/chunks/chunkloader.h
@@ -10,14 +10,17 @@ namespace Qt3DCore
 
 #include <QObject>
 
-/** Base class for chunk queue jobs. Job implementations start their work when they are created
+/** \ingroup 3d
+ * Base class for chunk queue jobs. Job implementations start their work when they are created
  * and all work is done asynchronously, i.e. constructor should exit as soon as possible and
  * all work should be done in a worker thread. Once the job is done, finished() signal is emitted
  * and will be processed by the parent chunked entity.
  *
  * There are currently two types of queue jobs:
  *  1. chunk loaders: prepares all data needed for creation of entities (ChunkLoader sub-class)
  *  2. chunk updaters: given a chunk with already existing entity, it updates the entity (e.g. update texture or geometry)
+ *
+ * \since QGIS 3.0
  */
 class ChunkQueueJob : public QObject
 {
@@ -32,7 +35,7 @@ class ChunkQueueJob : public QObject
 
     ChunkNode *chunk() { return node; }
 
-    //! Request that the loading gets cancelled.
+    //! Request that the loading gets canceled.
     //! Returns only after the async job has been stopped.
     //! The signal finished() will not be emitted afterwards.
     virtual void cancel();
@@ -44,11 +47,17 @@ class ChunkQueueJob : public QObject
     ChunkNode *node;
 };
 
+/** \ingroup 3d
+ * Base class for factories of chunk queue jobs. Derived classes need to implement createJob()
+ * method that will create a specific job for given chunk node.
+ * \since QGIS 3.0
+ */
 class ChunkQueueJobFactory
 {
   public:
     virtual ~ChunkQueueJobFactory() = default;
 
+    //! Creates a specific chunk queue job for the chunk node. Ownership of the returned is passed to the caller.
     virtual ChunkQueueJob *createJob( ChunkNode *chunk ) = 0;
 };
 
@@ -58,6 +67,7 @@ class ChunkLoader : public ChunkQueueJob
 {
     Q_OBJECT
   public:
+    //! Construct chunk loader for a node
     ChunkLoader( ChunkNode *node )
       : ChunkQueueJob( node )
     {
@@ -78,6 +88,7 @@ class ChunkLoaderFactory
   public:
     virtual ~ChunkLoaderFactory();
 
+    //! Creates loader for the given chunk node. Ownership of the returned is passed to the caller.
     virtual ChunkLoader *createChunkLoader( ChunkNode *node ) const = 0;
 };
 

diff --git a/src/3d/qgs3dmapscene.h b/src/3d/qgs3dmapscene.h
@@ -27,18 +27,23 @@ class Qgs3DMapSettings;
 class Terrain;
 class ChunkedEntity;
 
-/**
+/** \ingroup 3d
  * Entity that encapsulates our 3D scene - contains all other entities (such as terrain) as children.
+ * \since QGIS 3.0
  */
 class _3D_EXPORT Qgs3DMapScene : public Qt3DCore::QEntity
 {
     Q_OBJECT
   public:
+    //! Constructs a 3D scene based on map settings and Qt 3D renderer configuration
     Qgs3DMapScene( const Qgs3DMapSettings &map, Qt3DExtras::QForwardRenderer *defaultFrameGraph, Qt3DRender::QRenderSettings *renderSettings, Qt3DRender::QCamera *camera, const QRect &viewportRect, Qt3DCore::QNode *parent = nullptr );
 
+    //! Returns camera controller
     QgsCameraController *cameraController() { return mCameraController; }
+    //! Returns terrain entity
     Terrain *terrain() { return mTerrain; }
 
+    //! Resets camera view to show the whole scene (top view)
     void viewZoomFull();
 
   private slots:

diff --git a/src/3d/qgs3dmapsettings.h b/src/3d/qgs3dmapsettings.h
@@ -32,6 +32,7 @@ class _3D_EXPORT Qgs3DMapSettings : public QObject
     Q_OBJECT
   public:
     Qgs3DMapSettings();
+    //! Copy constructor
     Qgs3DMapSettings( const Qgs3DMapSettings &other );
     ~Qgs3DMapSettings();
 

diff --git a/src/3d/qgs3dutils.h b/src/3d/qgs3dutils.h
@@ -24,6 +24,10 @@ enum AltitudeBinding
 };
 
 
+/** \ingroup 3d
+ * Miscellaneous utility functions used from 3D code.
+ * \since QGIS 3.0
+ */
 class _3D_EXPORT Qgs3DUtils
 {
   public:
@@ -34,16 +38,24 @@ class _3D_EXPORT Qgs3DUtils
      */
     static int maxZoomLevel( double tile0width, double tileResolution, double maxError );
 
+    //! Converts a value from AltitudeClamping enum to a string
     static QString altClampingToString( AltitudeClamping altClamp );
+    //! Converts a string to a value from AltitudeClamping enum
     static AltitudeClamping altClampingFromString( const QString &str );
 
+    //! Converts a value from AltitudeBinding enum to a string
     static QString altBindingToString( AltitudeBinding altBind );
+    //! Converts a string to a value from AltitudeBinding enum
     static AltitudeBinding altBindingFromString( const QString &str );
 
+    //! Clamps altitude of vertices of a linestring according to the settings
     static void clampAltitudes( QgsLineString *lineString, AltitudeClamping altClamp, AltitudeBinding altBind, const QgsPoint &centroid, float height, const Qgs3DMapSettings &map );
+    //! Clamps altitude of vertices of a polygon according to the settings
     static bool clampAltitudes( QgsPolygonV2 *polygon, AltitudeClamping altClamp, AltitudeBinding altBind, float height, const Qgs3DMapSettings &map );
 
+    //! Converts a 4x4 transform matrix to a string
     static QString matrix4x4toString( const QMatrix4x4 &m );
+    //! Convert a string to a 4x4 transform matrix
     static QMatrix4x4 stringToMatrix4x4( const QString &str );
 
     /**

diff --git a/src/3d/qgsvectorlayer3drenderer.h b/src/3d/qgsvectorlayer3drenderer.h
@@ -18,31 +18,40 @@ class QgsVectorLayer;
 class QgsAbstract3DSymbol;
 
 
-//! Metadata for vector layer 3D renderer to allow creation of its instances from XML
+/** \ingroup core
+ * Metadata for vector layer 3D renderer to allow creation of its instances from XML
+ * \since QGIS 3.0
+ */
 class _3D_EXPORT QgsVectorLayer3DRendererMetadata : public Qgs3DRendererAbstractMetadata
 {
   public:
     QgsVectorLayer3DRendererMetadata();
 
+    //! Creates an instance of a 3D renderer based on a DOM element with renderer configuration
     virtual QgsAbstract3DRenderer *createRenderer( QDomElement &elem, const QgsReadWriteContext &context ) override;
 };
 
 
-/** 3D renderer that renders all features of a vector layer with the same 3D symbol.
+/** \ingroup core
+ * 3D renderer that renders all features of a vector layer with the same 3D symbol.
  * The appearance is completely defined by the symbol.
+ * \since QGIS 3.0
  */
 class _3D_EXPORT QgsVectorLayer3DRenderer : public QgsAbstract3DRenderer
 {
   public:
     //! Takes ownership of the symbol object
-    explicit QgsVectorLayer3DRenderer( QgsAbstract3DSymbol *s = nullptr );
+    explicit QgsVectorLayer3DRenderer( QgsAbstract3DSymbol *s SIP_TRANSFER = nullptr );
     ~QgsVectorLayer3DRenderer();
 
+    //! Sets vector layer associated with the renderer
     void setLayer( QgsVectorLayer *layer );
+    //! Returns vector layer associated with the renderer
     QgsVectorLayer *layer() const;
 
-    //! takes ownership of the symbol
-    void setSymbol( QgsAbstract3DSymbol *symbol );
+    //! Sets 3D symbol associated with the renderer. Takes ownership of the symbol
+    void setSymbol( QgsAbstract3DSymbol *symbol SIP_TRANSFER );
+    //! Returns 3D symbol associated with the renderer
     const QgsAbstract3DSymbol *symbol() const;
 
     QString type() const override { return "vector"; }

diff --git a/src/3d/symbols/qgspoint3dsymbol.h b/src/3d/symbols/qgspoint3dsymbol.h
@@ -8,7 +8,11 @@
 #include "qgs3dutils.h"
 
 
-//! 3D symbol that draws point geometries as 3D objects using one of the predefined shapes.
+/** \ingroup 3d
+ * 3D symbol that draws point geometries as 3D objects using one of the predefined shapes.
+ *
+ * \since QGIS 3.0
+ */
 class _3D_EXPORT QgsPoint3DSymbol : public QgsAbstract3DSymbol
 {
   public:
@@ -20,13 +24,19 @@ class _3D_EXPORT QgsPoint3DSymbol : public QgsAbstract3DSymbol
     void writeXml( QDomElement &elem, const QgsReadWriteContext &context ) const override;
     void readXml( const QDomElement &elem, const QgsReadWriteContext &context ) override;
 
+    //! Returns material used for shading of the symbol
     QgsPhongMaterialSettings material() const { return mMaterial; }
+    //! Sets material used for shading of the symbol
     void setMaterial( const QgsPhongMaterialSettings &material ) { mMaterial = material; }
 
+    //! Returns a key-value dictionary of point shape properties
     QVariantMap shapeProperties() const { return mShapeProperties; }
+    //! Sets a key-value dictionary of point shape properties
     void setShapeProperties( const QVariantMap &properties ) { mShapeProperties = properties; }
 
+    //! Returns transform for individual objects represented by the symbol
     QMatrix4x4 transform() const { return mTransform; }
+    //! Sets transform for individual objects represented by the symbol
     void setTransform( const QMatrix4x4 &transform ) { mTransform = transform; }
 
   private:

diff --git a/src/3d/terrain/demterraingenerator.h b/src/3d/terrain/demterraingenerator.h
@@ -81,13 +81,16 @@ class DemTerrainChunkLoader : public TerrainChunkLoader
 #include "qgsrectangle.h"
 class QgsRasterDataProvider;
 
-/**
+/** \ingroup 3d
  * Utility class to asynchronously create heightmaps from DEM raster for given tiles of terrain.
+ * \since QGIS 3.0
  */
 class DemHeightMapGenerator : public QObject
 {
     Q_OBJECT
   public:
+    //! Constructs height map generator based on a raster layer with elevation model,
+    //! terrain's tiling scheme and height map resolution (number of height values on each side of tile)
     DemHeightMapGenerator( QgsRasterLayer *dtm, const QgsTilingScheme &tilingScheme, int resolution );
     ~DemHeightMapGenerator();
 
@@ -97,6 +100,7 @@ class DemHeightMapGenerator : public QObject
     //! synchronous terrain read for a tile
     QByteArray renderSynchronously( int x, int y, int z );
 
+    //! Returns resolution(number of height values on each side of tile)
     int resolution() const { return res; }
 
     //! returns height at given position (in terrain's CRS)

diff --git a/src/3d/terrain/demterraintilegeometry.cpp b/src/3d/terrain/demterraintilegeometry.cpp
@@ -188,12 +188,6 @@ DemTerrainTileGeometry::~DemTerrainTileGeometry()
 {
 }
 
-void DemTerrainTileGeometry::setHeightMap( const QByteArray &heightMap )
-{
-  m_heightMap = heightMap;
-  m_vertexBuffer->setDataGenerator( QSharedPointer<PlaneVertexBufferFunctor>::create( m_resolution, m_heightMap ) );
-}
-
 QAttribute *DemTerrainTileGeometry::positionAttribute() const
 {
   return m_positionAttribute;

diff --git a/src/3d/terrain/demterraintilegeometry.h b/src/3d/terrain/demterraintilegeometry.h
@@ -17,6 +17,10 @@ namespace Qt3DRender
 } // Qt3DRender
 
 
+/** \ingroup 3d
+ * Stores attributes and vertex/index buffers for one terrain tile based on DEM.
+ * \since QGIS 3.0
+ */
 class DemTerrainTileGeometry : public Qt3DRender::QGeometry
 {
     Q_OBJECT
@@ -26,17 +30,18 @@ class DemTerrainTileGeometry : public Qt3DRender::QGeometry
     Q_PROPERTY( Qt3DRender::QAttribute *indexAttribute READ indexAttribute CONSTANT )
 
   public:
+    //! Constructs a terrain tile geometry. Resolution is the number of vertices on one side of the tile,
+    //! heightMap is array of float values with one height value for each vertex
     explicit DemTerrainTileGeometry( int resolution, const QByteArray &heightMap, QNode *parent = nullptr );
     ~DemTerrainTileGeometry();
 
-    //void updateVertices();
-    //void updateIndices();
-
-    void setHeightMap( const QByteArray &heightMap );
-
+    //! Returns geometry attribute for vertex positions
     Qt3DRender::QAttribute *positionAttribute() const;
+    //! Returns geometry attribute for vertex normals
     Qt3DRender::QAttribute *normalAttribute() const;
+    //! Returns geometry attribute for texture coordinates for vertices
     Qt3DRender::QAttribute *texCoordAttribute() const;
+    //! Returns attribute for indices of triangles
     Qt3DRender::QAttribute *indexAttribute() const;
 
   private: