Yet another round of doxygen comments for 3D

Getting there!
qgis · Sep 25, 2017 · d5d6372 · d5d6372
1 parent 6d9240c
commit d5d6372
Show file tree

Hide file tree

Showing 17 changed files with 103 additions and 22 deletions.
diff --git a/python/core/3d/qgsabstract3drenderer.sip b/python/core/3d/qgsabstract3drenderer.sip
@@ -1,7 +1,7 @@
 /************************************************************************
  * This file has been generated automatically from                      *
  *                                                                      *
- * src/core/3d/qgsabstract3drenderer.h                                  *
+ * src/core/./3d/qgsabstract3drenderer.h                                *
  *                                                                      *
  * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
  ************************************************************************/
@@ -59,7 +59,7 @@ Resolves references to other objects - second phase of loading - after readXml()
 /************************************************************************
  * This file has been generated automatically from                      *
  *                                                                      *
- * src/core/3d/qgsabstract3drenderer.h                                  *
+ * src/core/./3d/qgsabstract3drenderer.h                                *
  *                                                                      *
  * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
  ************************************************************************/
diff --git a/src/3d/chunks/chunkboundsentity.h b/src/3d/chunks/chunkboundsentity.h
@@ -6,12 +6,17 @@
 class AABB;
 class AABBMesh;
 
-//! Draws bounds of axis aligned bounding boxes
+/** \ingroup 3d
+ * Draws bounds of axis aligned bounding boxes
+ * \since QGIS 3.0
+ */
 class ChunkBoundsEntity : public Qt3DCore::QEntity
 {
   public:
+    //! Constructs the entity
     ChunkBoundsEntity( Qt3DCore::QNode *parent = nullptr );
 
+    //! Sets a list of bounding boxes to be rendered by the entity
     void setBoxes( const QList<AABB> &bboxes );
 
   private:

diff --git a/src/3d/chunks/chunkedentity.cpp b/src/3d/chunks/chunkedentity.cpp
@@ -59,7 +59,7 @@ ChunkedEntity::ChunkedEntity( const AABB &rootBbox, float rootError, float tau,
 
 ChunkedEntity::~ChunkedEntity()
 {
-  // derived classes have to make sure that any pending active job has finished / been cancelled
+  // derived classes have to make sure that any pending active job has finished / been canceled
   // before getting to this destructor - here it would be too late to cancel them
   // (e.g. objects required for loading/updating have been deleted already)
   Q_ASSERT( !activeJob );

diff --git a/src/3d/chunks/chunkedentity.h b/src/3d/chunks/chunkedentity.h
@@ -26,12 +26,16 @@ class SceneState
 
 #include <QTime>
 
-//! Implementation of entity that handles chunks of data organized in quadtree with loading data when necessary
-//! based on data error and unloading of data when data are not necessary anymore
+/** \ingroup 3d
+ * Implementation of entity that handles chunks of data organized in quadtree with loading data when necessary
+ * based on data error and unloading of data when data are not necessary anymore
+ * \since QGIS 3.0
+ */
 class ChunkedEntity : public Qt3DCore::QEntity
 {
     Q_OBJECT
   public:
+    //! Constructs a chunked entity
     ChunkedEntity( const AABB &rootBbox, float rootError, float tau, int maxLevel, ChunkLoaderFactory *loaderFactory, Qt3DCore::QNode *parent = nullptr );
     ~ChunkedEntity();
 
@@ -40,15 +44,19 @@ class ChunkedEntity : public Qt3DCore::QEntity
 
     bool needsUpdate; //!< A chunk has been loaded recently - let's display it!
 
+    //! Determines whether bounding boxes of tiles should be shown (for debugging)
     void setShowBoundingBoxes( bool enabled );
 
     //! update already loaded nodes (add to the queue)
     void updateNodes( const QList<ChunkNode *> &nodes, ChunkQueueJobFactory *updateJobFactory );
 
+    //! Returns list of active nodes - i.e. nodes that are get rendered
     QList<ChunkNode *> getActiveNodes() const { return activeNodes; }
+    //! Returns the root node of the whole quadtree hierarchy of nodes
     ChunkNode *getRootNode() const { return rootNode; }
 
   protected:
+    //! Cancels the background job that is currently in progress
     void cancelActiveJob();
 
   private:

diff --git a/src/3d/chunks/chunkloader.h b/src/3d/chunks/chunkloader.h
@@ -26,13 +26,15 @@ class ChunkQueueJob : public QObject
 {
     Q_OBJECT
   public:
+    //! Constructs a job for given chunk node
     ChunkQueueJob( ChunkNode *node )
       : node( node )
     {
     }
 
     virtual ~ChunkQueueJob();
 
+    //! Returns chunk node of this job
     ChunkNode *chunk() { return node; }
 
     //! Request that the loading gets canceled.
@@ -41,6 +43,7 @@ class ChunkQueueJob : public QObject
     virtual void cancel();
 
   signals:
+    //! Emitted when the asynchronous job has finished. Not emitted if the job got canceled.
     void finished();
 
   protected:

diff --git a/src/3d/chunks/chunknode.h b/src/3d/chunks/chunknode.h
@@ -16,6 +16,20 @@ class ChunkLoader;
 class ChunkQueueJob;
 class ChunkQueueJobFactory;
 
+
+/** \ingroup 3d
+ * Data structure for keeping track of chunks of data for 3D entities that use "out of core" rendering,
+ * i.e. not all of the data are available in the memory all the time. This is useful for large datasets
+ * where it may be impossible to load all data into memory or the rendering would get very slow.
+ * This is currently used for rendering of terrain, but it is not limited to it and may be used for
+ * other data as well.
+ *
+ * The data structure is essentially a quadtree: each node may have four child nodes. Nodes can exist
+ * in several states (e.g. skeleton or loaded state) and they keep being loaded and unloaded as necessary
+ * by the 3D rendering.
+ *
+ * \since QGIS 3.0
+ */
 class ChunkNode
 {
   public:

diff --git a/src/3d/qgstilingscheme.h b/src/3d/qgstilingscheme.h
@@ -6,8 +6,11 @@
 
 class QgsRectangle;
 
-//! The class encapsulates tiling scheme (just like with WMTS / TMS / XYZ layers).
-//! The origin (tile [0,0]) is in bottom-left corner.
+/** \ingroup 3d
+ * The class encapsulates tiling scheme (just like with WMTS / TMS / XYZ layers).
+ * The origin (tile [0,0]) is in bottom-left corner.
+ * \since QGIS 3.0
+ */
 class QgsTilingScheme
 {
   public:

diff --git a/src/3d/terrain/demterraingenerator.cpp b/src/3d/terrain/demterraingenerator.cpp
@@ -131,7 +131,7 @@ DemTerrainChunkLoader::DemTerrainChunkLoader( Terrain *terrain, ChunkNode *node
   , resolution( 0 )
 {
 
-  const Qgs3DMapSettings &map = mTerrain->map3D();
+  const Qgs3DMapSettings &map = terrain->map3D();
   DemTerrainGenerator *generator = static_cast<DemTerrainGenerator *>( map.terrainGenerator() );
 
   // get heightmap asynchronously
@@ -168,7 +168,7 @@ Qt3DCore::QEntity *DemTerrainChunkLoader::createEntity( Qt3DCore::QEntity *paren
   float zMin, zMax;
   _heightMapMinMax( heightMap, zMin, zMax );
 
-  const Qgs3DMapSettings &map = mTerrain->map3D();
+  const Qgs3DMapSettings &map = terrain()->map3D();
   QgsRectangle extent = map.terrainGenerator()->terrainTilingScheme.tileToExtent( node->x, node->y, node->z ); //node->extent;
   double x0 = extent.xMinimum() - map.originX;
   double y0 = extent.yMinimum() - map.originY;
@@ -225,7 +225,7 @@ static QByteArray _readDtmData( QgsRasterDataProvider *provider, const QgsRectan
   QElapsedTimer t;
   t.start();
 
-  // TODO: use feedback object? (but GDAL currently does not support cancellation anyway)
+  // TODO: use feedback object? (but GDAL currently does not support cancelation anyway)
   QgsRasterBlock *block = provider->block( 1, extent, res, res );
 
   QByteArray data;

diff --git a/src/3d/terrain/demterraingenerator.h b/src/3d/terrain/demterraingenerator.h
@@ -14,20 +14,26 @@ class QgsRasterLayer;
 
 #include "qgsmaplayerref.h"
 
-/**
+/** \ingroup 3d
  * Implementation of terrain generator that uses a raster layer with DEM to build terrain.
+ * \since QGIS 3.0
  */
 class _3D_EXPORT DemTerrainGenerator : public TerrainGenerator
 {
   public:
     DemTerrainGenerator();
 
+    //! Sets raster layer with elevation model to be used for terrain generation
     void setLayer( QgsRasterLayer *layer );
+    //! Returns raster layer with elevation model to be used for terrain generation
     QgsRasterLayer *layer() const;
 
+    //! Sets resolution of the generator (how many elevation samples on one side of a terrain tile)
     void setResolution( int resolution ) { mResolution = resolution; updateGenerator(); }
+    //! Returns resolution of the generator (how many elevation samples on one side of a terrain tile)
     int resolution() const { return mResolution; }
 
+    //! Returns height map generator object - takes care of extraction of elevations from the layer)
     DemHeightMapGenerator *heightMapGenerator() { return mHeightMapGenerator.get(); }
 
     virtual TerrainGenerator *clone() const override;
@@ -53,10 +59,15 @@ class _3D_EXPORT DemTerrainGenerator : public TerrainGenerator
 
 
 
+/** \ingroup 3d
+ * Chunk loader for DEM terrain tiles.
+ * \since QGIS 3.0
+ */
 class DemTerrainChunkLoader : public TerrainChunkLoader
 {
     Q_OBJECT
   public:
+    //! Constructs loader for the given chunk node
     DemTerrainChunkLoader( Terrain *terrain, ChunkNode *node );
     ~DemTerrainChunkLoader();
 

diff --git a/src/3d/terrain/flatterraingenerator.cpp b/src/3d/terrain/flatterraingenerator.cpp
@@ -9,10 +9,13 @@
 #include "chunknode.h"
 #include "terrainchunkloader.h"
 
+/// @cond PRIVATE
 
+//! Chunk loader for flat terrain implementation
 class FlatTerrainChunkLoader : public TerrainChunkLoader
 {
   public:
+    //! Construct the loader for a node
     FlatTerrainChunkLoader( Terrain *terrain, ChunkNode *node );
 
     virtual Qt3DCore::QEntity *createEntity( Qt3DCore::QEntity *parent ) override;
@@ -21,6 +24,8 @@ class FlatTerrainChunkLoader : public TerrainChunkLoader
     Qt3DExtras::QPlaneGeometry *mTileGeometry = nullptr;
 };
 
+/// @endcond
+
 
 //---------------
 
@@ -39,7 +44,7 @@ Qt3DCore::QEntity *FlatTerrainChunkLoader::createEntity( Qt3DCore::QEntity *pare
   // make geometry renderer
 
   // simple quad geometry shared by all tiles
-  // QPlaneGeometry by default is 1x1 with mesh resultion QSize(2,2), centered at 0
+  // QPlaneGeometry by default is 1x1 with mesh resolution QSize(2,2), centered at 0
   // TODO: the geometry could be shared inside Terrain instance (within terrain-generator specific data?)
   mTileGeometry = new Qt3DExtras::QPlaneGeometry;
 

diff --git a/src/3d/terrain/maptexturegenerator.cpp b/src/3d/terrain/maptexturegenerator.cpp
@@ -39,7 +39,7 @@ void MapTextureGenerator::cancelJob( int jobId )
   {
     if ( jd.jobId == jobId )
     {
-      //qDebug() << "cancelling job " << jobId;
+      //qDebug() << "canceling job " << jobId;
       jd.job->cancelWithoutBlocking();
       disconnect( jd.job, &QgsMapRendererJob::finished, this, &MapTextureGenerator::onRenderingFinished );
       jd.job->deleteLater();

diff --git a/src/3d/terrain/quantizedmeshgeometry.cpp b/src/3d/terrain/quantizedmeshgeometry.cpp
@@ -15,7 +15,7 @@
  * @brief Decompresses the given buffer using the standard GZIP algorithm
  * @param input The buffer to be decompressed
  * @param output The result of the decompression
- * @return @c true if the decompression was successfull, @c false otherwise
+ * @return @c true if the decompression was successful, @c false otherwise
  */
 bool gzipDecompress( QByteArray input, QByteArray &output )
 {

diff --git a/src/3d/terrain/quantizedmeshgeometry.h b/src/3d/terrain/quantizedmeshgeometry.h
@@ -54,12 +54,19 @@ class QgsMapToPixel;
 
 class Map3D;
 
+/** \ingroup 3d
+ * Stores vertex and index buffer for one tile of quantized mesh terrain.
+ * \since QGIS 3.0
+ */
 class QuantizedMeshGeometry : public Qt3DRender::QGeometry
 {
   public:
+    //! Constructs geometry based on the loaded tile data
     QuantizedMeshGeometry( QuantizedMeshTile *t, const Map3D &map, const QgsMapToPixel &mapToPixel, const QgsCoordinateTransform &terrainToMap, QNode *parent = nullptr );
 
+    //! Reads a tile from a file in the local disk cache
     static QuantizedMeshTile *readTile( int tx, int ty, int tz, const QgsRectangle &extent );
+    //! Downloads a tile to to a file in the local disk cache
     static void downloadTileIfMissing( int tx, int ty, int tz );
 
   private:

diff --git a/src/3d/terrain/quantizedmeshterraingenerator.cpp b/src/3d/terrain/quantizedmeshterraingenerator.cpp
@@ -11,7 +11,9 @@
 #include "chunknode.h"
 #include "terrainchunkloader.h"
 
+/// @cond PRIVATE
 
+//! Chunk loader for quantized mesh terrain
 class QuantizedMeshTerrainChunkLoader : public TerrainChunkLoader
 {
   public:
@@ -87,6 +89,8 @@ class QuantizedMeshTerrainChunkLoader : public TerrainChunkLoader
     QgsRectangle tileRect;
 };
 
+/// @endcond
+
 
 // ---------------
 

diff --git a/src/3d/terrain/quantizedmeshterraingenerator.h b/src/3d/terrain/quantizedmeshterraingenerator.h
@@ -4,13 +4,19 @@
 #include "terraingenerator.h"
 
 
+/** \ingroup 3d
+ * Terrain generator using downloaded terrain tiles using quantized mesh specification
+ * \since QGIS 3.0
+ */
 class QuantizedMeshTerrainGenerator : public TerrainGenerator
 {
   public:
     QuantizedMeshTerrainGenerator();
 
+    //! Determines base tile from map extent
     void setBaseTileFromExtent( const QgsRectangle &extentInTerrainCrs );
 
+    //! Converts tile coordinates (x,y,z) in our quadtree to tile coordinates of quantized mesh tree
     void quadTreeTileToBaseTile( int x, int y, int z, int &tx, int &ty, int &tz ) const;
 
     TerrainGenerator::Type type() const override;

diff --git a/src/3d/terrain/terrainchunkloader.h b/src/3d/terrain/terrainchunkloader.h
@@ -9,21 +9,31 @@
 class Terrain;
 class TerrainChunkEntity;
 
+
+/** \ingroup 3d
+ * Base class for chunk loaders for terrain tiles.
+ * Adds functionality for asynchronous rendering of terrain tile map texture and access to the terrain entity.
+ * \since QGIS 3.0
+ */
 class TerrainChunkLoader : public ChunkLoader
 {
   public:
+    //! Constructs loader for a chunk node
     TerrainChunkLoader( Terrain *terrain, ChunkNode *node );
 
+  protected:
+    //! Starts asynchronous rendering of map texture
     void loadTexture();
+    //! Creates material component for the entity with the rendered map as a texture
     void createTextureComponent( TerrainChunkEntity *entity );
-
-  protected:
-    Terrain *mTerrain;
+    //! Gives access to the terain entity
+    Terrain *terrain() { return mTerrain; }
 
   private slots:
     void onImageReady( int jobId, const QImage &image );
 
   private:
+    Terrain *mTerrain;
     QgsRectangle mExtentMapCrs;
     QString mTileDebugText;
     int mTextureJobId;