More class documentation

Author: wonder-sk

python/core/3d/qgsabstract3drenderer.sip

@@ -1,17 +1,14 @@
 /************************************************************************
  * 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   *
  ************************************************************************/
 
 
 
 
-namespace Qt3DCore
-{
-}
 
 class QgsAbstract3DRenderer
 {
@@ -62,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   *
  ************************************************************************/

src/3d/qgs3dmapsettings.h

@@ -22,7 +22,11 @@ class QgsProject;
 
 class QDomElement;
 
-//! Definition of the world
+/** \ingroup 3d
+ * Definition of the world
+ *
+ * \since QGIS 3.0
+ */
 class _3D_EXPORT Qgs3DMapSettings : public QObject
 {
     Q_OBJECT
@@ -31,42 +35,71 @@ class _3D_EXPORT Qgs3DMapSettings : public QObject
     Qgs3DMapSettings( const Qgs3DMapSettings &other );
     ~Qgs3DMapSettings();
 
+    //! Reads configuration from a DOM element previously written by writeXml()
     void readXml( const QDomElement &elem, const QgsReadWriteContext &context );
-
+    //! Writes configuration to a DOM element, to be used later with readXml()
     QDomElement writeXml( QDomDocument &doc, const QgsReadWriteContext &context ) const;
-
+    //! Resolves references to other objects (map layers) after the call to readXml()
     void resolveReferences( const QgsProject &project );
 
     double originX, originY, originZ;   //!< Coordinates in map CRS at which our 3D world has origin (0,0,0)
     QgsCoordinateReferenceSystem crs;   //!< Destination coordinate system of the world  (TODO: not needed? can be
 
+    //! Sets background color of the 3D map view
     void setBackgroundColor( const QColor &color );
+    //! Returns background color of the 3D map view
     QColor backgroundColor() const;
 
+    //! Sets color used for selected features
     void setSelectionColor( const QColor &color );
+    //! Returns color used for selected features
     QColor selectionColor() const;
 
     //
     // terrain related config
     //
 
+    //! Sets vertical scale (exaggeration) of terrain
+    //! (1 = true scale, > 1 = hills get more pronounced)
     void setTerrainVerticalScale( double zScale );
+    //! Returns vertical scale (exaggeration) of terrain
     double terrainVerticalScale() const;
 
+    //! Sets the list of map layers to be rendered as a texture of the terrain
     void setLayers( const QList<QgsMapLayer *> &layers );
+    //! Returns the list of map layers to be rendered as a texture of the terrain
     QList<QgsMapLayer *> layers() const;
 
+    //! Sets resolution (in pixels) of the texture of a terrain tile
+    //! \sa mapTileResolution()
     void setMapTileResolution( int res );
+    //! Returns resolution (in pixels) of the texture of a terrain tile. This parameter influences
+    //! how many zoom levels for terrain tiles there will be (together with maxTerrainGroundError())
     int mapTileResolution() const;
 
+    //! Sets maximum allowed screen error of terrain tiles in pixels.
+    //! \sa maxTerrainScreenError()
     void setMaxTerrainScreenError( float error );
+    //! Returns maximum allowed screen error of terrain tiles in pixels. This parameter decides
+    //! how aggressively less detailed terrain tiles are swapped to more detailed ones as camera gets closer.
+    //! Each tile has its error defined in world units - this error gets projected to screen pixels
+    //! according to camera view and if the tile's error is greater than the allowed error, it will
+    //! be swapped by more detailed tiles with lower error.
     float maxTerrainScreenError() const;
 
+    //! Returns maximum ground error of terrain tiles in world units.
+    //! \sa maxTerrainGroundError()
     void setMaxTerrainGroundError( float error );
+    //! Returns maximum ground error of terrain tiles in world units. This parameter influences
+    //! how many zoom levels there will be (together with mapTileResolution()).
+    //! This value tells that when the given ground error is reached (e.g. 10 meters), it makes no sense
+    //! to further split terrain tiles into finer ones because they will not add extra details anymore.
     float maxTerrainGroundError() const;
 
+    //! Sets terrain generator. It takes care of producing terrain tiles from the input data.
     //! Takes ownership of the generator
     void setTerrainGenerator( TerrainGenerator *gen );
+    //! Returns terrain generator. It takes care of producing terrain tiles from the input data.
     TerrainGenerator *terrainGenerator() const { return mTerrainGenerator.get(); }
 
     //
@@ -79,21 +112,35 @@ class _3D_EXPORT Qgs3DMapSettings : public QObject
     QString skyboxFileBase;
     QString skyboxFileExtension;
 
+    //! Sets whether to display bounding boxes of terrain tiles (for debugging)
     void setShowTerrainBoundingBoxes( bool enabled );
+    //! Returns whether to display bounding boxes of terrain tiles (for debugging)
     bool showTerrainBoundingBoxes() const { return mShowTerrainBoundingBoxes; }
+    //! Sets whether to display extra tile info on top of terrain tiles (for debugging)
     void setShowTerrainTilesInfo( bool enabled );
+    //! Returns whether to display extra tile info on top of terrain tiles (for debugging)
     bool showTerrainTilesInfo() const { return mShowTerrainTileInfo; }
 
   signals:
+    //! Emitted when the background color has changed
     void backgroundColorChanged();
+    //! Emitted when the selection color has changed
     void selectionColorChanged();
+    //! Emitted when the list of map layers for terrain texture has changed
     void layersChanged();
+    //! Emitted when the terrain generator has changed
     void terrainGeneratorChanged();
+    //! Emitted when the vertical scale of the terrain has changed
     void terrainVerticalScaleChanged();
+    //! Emitted when the map tile resoulution has changed
     void mapTileResolutionChanged();
+    //! Emitted when the maximum terrain screen error has changed
     void maxTerrainScreenErrorChanged();
+    //! Emitted when the maximum terrain ground error has changed
     void maxTerrainGroundErrorChanged();
+    //! Emitted when the flag whether terrain's bounding boxes are shown has changed
     void showTerrainBoundingBoxesChanged();
+    //! Emitted when the flag whether terrain's tile info is shown has changed
     void showTerrainTilesInfoChanged();
 
   private:

src/3d/qgstessellatedpolygongeometry.cpp

@@ -20,7 +20,7 @@ QgsTessellatedPolygonGeometry::QgsTessellatedPolygonGeometry( QNode *parent )
   m_vertexBuffer = new Qt3DRender::QBuffer( Qt3DRender::QBuffer::VertexBuffer, this );
 
   QgsTessellator tmpTess( 0, 0, m_withNormals );
-  const int stride = tmpTess.stride;
+  const int stride = tmpTess.stride();
 
   m_positionAttribute = new Qt3DRender::QAttribute( this );
   m_positionAttribute->setName( Qt3DRender::QAttribute::defaultPositionAttributeName() );
@@ -73,8 +73,8 @@ void QgsTessellatedPolygonGeometry::setPolygons( const QList<QgsPolygonV2 *> &po
     ++i;
   }
 
-  QByteArray data( ( const char * )tesselator.data.constData(), tesselator.data.count() * sizeof( float ) );
-  int nVerts = data.count() / tesselator.stride;
+  QByteArray data( ( const char * )tesselator.data().constData(), tesselator.data().count() * sizeof( float ) );
+  int nVerts = data.count() / tesselator.stride();
 
   m_vertexBuffer->setData( data );
   m_positionAttribute->setCount( nVerts );

src/3d/qgstessellatedpolygongeometry.h

@@ -10,14 +10,22 @@ namespace Qt3DRender
   class QBuffer;
 }
 
-//! Class that represents polygons tessellated into 3D geometry
+/** \ingroup 3d
+ * Class derived from Qt3DRender::QGeometry that represents polygons tessellated into 3D geometry.
+ *
+ * Takes a list of polygons as input, internally it does tessellation and writes output to the internal
+ * vertex buffer. Optionally it can add "walls" if the extrusion height is non-zero.
+ *
+ * \since QGIS 3.0
+ */
 class QgsTessellatedPolygonGeometry : public Qt3DRender::QGeometry
 {
   public:
+    //! Constructor
     QgsTessellatedPolygonGeometry( QNode *parent = nullptr );
     ~QgsTessellatedPolygonGeometry();
 
-    // takes ownership of passed polygon geometries
+    //! Initializes vertex buffer from given polygons. Takes ownership of passed polygon geometries
     void setPolygons( const QList<QgsPolygonV2 *> &polygons, const QgsPointXY &origin, float extrusionHeight );
 
   private:

src/3d/qgstessellator.cpp

@@ -44,13 +44,13 @@ static void make_quad( float x0, float y0, float x1, float y1, float zLow, float
 
 
 QgsTessellator::QgsTessellator( double originX, double originY, bool addNormals )
-  : originX( originX )
-  , originY( originY )
-  , addNormals( addNormals )
+  : mOriginX( originX )
+  , mOriginY( originY )
+  , mAddNormals( addNormals )
 {
-  stride = 3 * sizeof( float );
+  mStride = 3 * sizeof( float );
   if ( addNormals )
-    stride += 3 * sizeof( float );
+    mStride += 3 * sizeof( float );
 }
 
 
@@ -112,7 +112,7 @@ void QgsTessellator::addPolygon( const QgsPolygonV2 &polygon, float extrusionHei
     exterior->pointAt( i, pt, vt );
     if ( i == 0 || pt != ptPrev )
     {
-      p2t::Point *pt2 = new p2t::Point( pt.x() - originX, pt.y() - originY );
+      p2t::Point *pt2 = new p2t::Point( pt.x() - mOriginX, pt.y() - mOriginY );
       polyline.push_back( pt2 );
       float zPt = qIsNaN( pt.z() ) ? 0 : pt.z();
       z[pt2] = zPt;
@@ -134,7 +134,7 @@ void QgsTessellator::addPolygon( const QgsPolygonV2 &polygon, float extrusionHei
       hole->pointAt( j, pt, vt );
       if ( j == 0 || pt != ptPrev )
       {
-        p2t::Point *pt2 = new p2t::Point( pt.x() - originX, pt.y() - originY );
+        p2t::Point *pt2 = new p2t::Point( pt.x() - mOriginX, pt.y() - mOriginY );
         holePolyline.push_back( pt2 );
         float zPt = qIsNaN( pt.z() ) ? 0 : pt.z();
         z[pt2] = zPt;
@@ -158,9 +158,9 @@ void QgsTessellator::addPolygon( const QgsPolygonV2 &polygon, float extrusionHei
     {
       p2t::Point *p = t->GetPoint( j );
       float zPt = z[p];
-      data << p->x << extrusionHeight + zPt << -p->y;
-      if ( addNormals )
-        data << 0.f << 1.f << 0.f;
+      mData << p->x << extrusionHeight + zPt << -p->y;
+      if ( mAddNormals )
+        mData << 0.f << 1.f << 0.f;
     }
   }
 
@@ -171,9 +171,9 @@ void QgsTessellator::addPolygon( const QgsPolygonV2 &polygon, float extrusionHei
   // add walls if extrusion is enabled
   if ( extrusionHeight != 0 )
   {
-    _makeWalls( *exterior, false, extrusionHeight, data, addNormals, originX, originY );
+    _makeWalls( *exterior, false, extrusionHeight, mData, mAddNormals, mOriginX, mOriginY );
 
     for ( int i = 0; i < polygon.numInteriorRings(); ++i )
-      _makeWalls( *polygon.interiorRing( i ), true, extrusionHeight, data, addNormals, originX, originY );
+      _makeWalls( *polygon.interiorRing( i ), true, extrusionHeight, mData, mAddNormals, mOriginX, mOriginY );
   }
 }

src/3d/qgstessellator.h

@@ -5,25 +5,36 @@ class QgsPolygonV2;
 
 #include <QVector>
 
+
+/** \ingroup 3d
+ * Class that takes care of tessellation of polygons into triangles.
+ *
+ * It is expected that client code will create the tessellator object, then repeatedly call
+ * addPolygon() method that will generate triangles, and finally call data() to get final vertex data.
+ *
+ * Optionally provides extrusion by adding triangles that serve as walls when extrusion height is non-zero.
+ *
+ * \since QGIS 3.0
+ */
 class QgsTessellator
 {
   public:
+    //! Creates tessellator with a specified origin point of the world (in map coordinates)
     QgsTessellator( double originX, double originY, bool addNormals );
 
+    //! Tessellates a triangle and adds its vertex entries to the output data array
     void addPolygon( const QgsPolygonV2 &polygon, float extrusionHeight );
 
-    // input:
-    // - origin X/Y
-    // - whether to add walls
-    // - stream of geometries
-    // output:
-    // - vertex buffer data (+ index buffer data ?)
-
-    double originX, originY;
-    bool addNormals;
-    //QByteArray data;
-    QVector<float> data;
-    int stride;  //!< Size of one vertex entry in bytes
+    //! Returns array of triangle vertex data
+    QVector<float> data() const { return mData; }
+    //! Returns size of one vertex entry in bytes
+    int stride() const { return mStride; }
+
+  private:
+    double mOriginX, mOriginY;
+    bool mAddNormals;
+    QVector<float> mData;
+    int mStride;
 };
 
 #endif // QGSTESSELLATOR_H

src/3d/terrain/demterraintilegeometry.cpp

@@ -9,7 +9,7 @@
 using namespace Qt3DRender;
 
 
-QByteArray createPlaneVertexData( int res, const QByteArray &heights )
+static QByteArray createPlaneVertexData( int res, const QByteArray &heights )
 {
   Q_ASSERT( res >= 2 );
   Q_ASSERT( heights.count() == res * res * ( int )sizeof( float ) );
@@ -67,7 +67,7 @@ QByteArray createPlaneVertexData( int res, const QByteArray &heights )
 }
 
 
-QByteArray createPlaneIndexData( int res )
+static QByteArray createPlaneIndexData( int res )
 {
   QSize resolution( res, res );
   // Create the index data. 2 triangles per rectangular face
@@ -101,7 +101,10 @@ QByteArray createPlaneIndexData( int res )
   return indexBytes;
 }
 
+///@cond PRIVATE
 
+
+//! Generates vertex buffer for DEM terrain tiles
 class PlaneVertexBufferFunctor : public QBufferDataGenerator
 {
   public:
@@ -133,6 +136,8 @@ class PlaneVertexBufferFunctor : public QBufferDataGenerator
     QByteArray m_heightMap;
 };
 
+
+//! Generates index buffer for DEM terrain tiles
 class PlaneIndexBufferFunctor : public QBufferDataGenerator
 {
   public:
@@ -161,6 +166,7 @@ class PlaneIndexBufferFunctor : public QBufferDataGenerator
     int m_resolution;
 };
 
+/// @endcond
 
 
 

src/3d/terrain/flatterraingenerator.h

@@ -10,6 +10,11 @@
 #include "chunkloader.h"
 
 
+/** \ingroup 3d
+ * Terrain generator that creates a simple square flat area.
+ *
+ * \since QGIS 3.0
+ */
 class _3D_EXPORT FlatTerrainGenerator : public TerrainGenerator
 {
   public:
@@ -24,9 +29,12 @@ class _3D_EXPORT FlatTerrainGenerator : public TerrainGenerator
     virtual void writeXml( QDomElement &elem ) const override;
     virtual void readXml( const QDomElement &elem ) override;
 
+    //! Sets extent of the terrain
     void setExtent( const QgsRectangle &extent );
 
+    //! Sets CRS of the terrain
     void setCrs( const QgsCoordinateReferenceSystem &crs );
+    //! Returns CRS of the terrain
     QgsCoordinateReferenceSystem crs() const { return mCrs; }
 
   private: