Skip to content
Permalink
Browse files

Another round of doxygen comments

  • Loading branch information
wonder-sk committed Sep 24, 2017
1 parent 990f353 commit 4bf44d5e816dd71757580a9e69901e7e8aede765
@@ -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 )
@@ -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:
@@ -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;
};

@@ -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:
@@ -32,6 +32,7 @@ class _3D_EXPORT Qgs3DMapSettings : public QObject
Q_OBJECT
public:
Qgs3DMapSettings();
//! Copy constructor
Qgs3DMapSettings( const Qgs3DMapSettings &other );
~Qgs3DMapSettings();

@@ -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 );

/**
@@ -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"; }
@@ -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:
@@ -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)
@@ -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;
@@ -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:

0 comments on commit 4bf44d5

Please sign in to comment.
You can’t perform that action at this time.