Skip to content
Permalink
Browse files

More doxygen comments

  • Loading branch information
wonder-sk committed Sep 24, 2017
1 parent 7389588 commit 990f353ae0d59c98f6a268bfd6e9a606a088123b
@@ -10,7 +10,7 @@



class QgsAbstract3DRenderer
class QgsAbstract3DRenderer /Abstract/
{
%Docstring
Base class for all renderers that may to participate in 3D view.
@@ -7,15 +7,20 @@
#include <QList>
#include <QVector3D>

//! axis-aligned bounding box - in world coords
/** \ingroup 3d
* Axis-aligned bounding box - in world coords.
* \since QGIS 3.0
*/
class _3D_EXPORT AABB
{
public:
//! Constructs bounding box with null coordinates
AABB()
: xMin( 0 ), yMin( 0 ), zMin( 0 ), xMax( 0 ), yMax( 0 ), zMax( 0 )
{
}

//! Constructs bounding box
AABB( float xMin, float yMin, float zMin, float xMax, float yMax, float zMax )
: xMin( xMin ), yMin( yMin ), zMin( zMin ), xMax( xMax ), yMax( yMax ), zMax( zMax )
{
@@ -28,32 +33,44 @@ class _3D_EXPORT AABB
qSwap( this->zMin, this->zMax );
}

//! Returns box width in X axis
float xExtent() const { return xMax - xMin; }
//! Returns box width in Y axis
float yExtent() const { return yMax - yMin; }
//! Returns box width in Z axis
float zExtent() const { return zMax - zMin; }

//! Returns center in X axis
float xCenter() const { return ( xMax + xMin ) / 2; }
//! Returns center in Y axis
float yCenter() const { return ( yMax + yMin ) / 2; }
//! Returns center in Z axis
float zCenter() const { return ( zMax + zMin ) / 2; }

//! Returns coordinates of the center of the box
QVector3D center() const { return QVector3D( xCenter(), yCenter(), zCenter() ); }
//! Returns corner of the box with minimal coordinates
QVector3D minimum() const { return QVector3D( xMin, yMin, zMin ); }
//! Returns corner of the box with maximal coordinates
QVector3D maximum() const { return QVector3D( xMax, yMax, zMax ); }

//! Determines whether the box intersects some other axis aligned box
bool intersects( const AABB &other ) const
{
return xMin < other.xMax && other.xMin < xMax &&
yMin < other.yMax && other.yMin < yMax &&
zMin < other.zMax && other.zMin < zMax;
}

//! Determines whether given coordinate is inside the box
bool intersects( float x, float y, float z ) const
{
return xMin <= x && xMax >= x &&
yMin <= y && yMax >= y &&
zMin <= z && zMax >= z;
}

//! Returns shortest distance from the box to a point
float distanceFromPoint( float x, float y, float z ) const
{
float dx = qMax( xMin - x, qMax( 0.f, x - xMax ) );
@@ -62,11 +79,13 @@ class _3D_EXPORT AABB
return sqrt( dx * dx + dy * dy + dz * dz );
}

//! Returns shortest distance from the box to a point
float distanceFromPoint( const QVector3D &v ) const
{
return distanceFromPoint( v.x(), v.y(), v.z() );
}

//! Returns a list of pairs of vertices (useful for display of bounding boxes)
QList<QVector3D> verticesForLines() const
{
QList<QVector3D> vertices;
@@ -24,6 +24,7 @@ class ChunkNode

~ChunkNode();

//! Returns true if all child chunks are available and thus this node could be swapped to the child nodes
bool allChildChunksResident( const QTime &currentTime ) const;

//! make sure that all child nodes are at least skeleton nodes
@@ -32,6 +33,7 @@ class ChunkNode
//! how deep is the node in the tree (zero means root node, every level adds one)
int level() const;

//! Returns list of all descendants (recursive, not just direct children)
QList<ChunkNode *> descendants();

//
@@ -88,16 +90,16 @@ class ChunkNode
* Enjoy the ASCII art for the state machine:
*
* |<---------------------------------------------------------------------(unloaded)--------+
* |<---------------------------------------(cancelled)-------------+ |
* |<--------(cancelled)-----------+ | |
* |<---------------------------------------(canceled)--------------+ |
* |<--------(canceled)------------+ | |
* | | | |
* Skeleton --(requested)--> QueuedForLoad --(started load)--> Loading --(finished)--> Loaded
* | |
* | |
* Updating <--(started update)-- QueuedForUpdate <--(needs update)--+ |
* | | |
* | +---------(cancelled)---------->|
* +-------(finished / cancelled)-------------------------------------->|
* | +---------(canceled)----------->|
* +-------(finished / canceled)--------------------------------------->|
*
*/
enum State
@@ -8,32 +8,44 @@
#include <Qt3DRender>


//! Object that controls camera movement based on user input
/** \ingroup 3d
* Object that controls camera movement based on user input
* \since QGIS 3.0
*/
class _3D_EXPORT QgsCameraController : public Qt3DCore::QEntity
{
Q_OBJECT
Q_PROPERTY( Qt3DRender::QCamera *camera READ camera WRITE setCamera NOTIFY cameraChanged )
Q_PROPERTY( QRect viewport READ viewport WRITE setViewport NOTIFY viewportChanged )
public:
//! Constructs the camera controller with optional parent node that will take ownership
QgsCameraController( Qt3DCore::QNode *parent = nullptr );

//! Returns camera that is being controlled
Qt3DRender::QCamera *camera() const { return mCamera; }
//! Returns viewport rectangle
QRect viewport() const { return mViewport; }

//! Connects to object picker attached to terrain entity. Called internally from 3D scene.
//! This allows camera controller understand how far from the camera is the terrain under mouse cursor
void addTerrainPicker( Qt3DRender::QObjectPicker *picker );

//! Assigns camera that should be controlled by this class. Called internally from 3D scene.
void setCamera( Qt3DRender::QCamera *camera );
//! Sets viewport rectangle. Called internally from 3D canvas. Allows conversion of mouse coordinates.
void setViewport( const QRect &viewport );

void setCameraData( float x, float y, float dist, float pitch = 0, float yaw = 0 );

//! Called internally from 3D scene when a new frame is generated. Updates camera according to keyboard/mouse input
void frameTriggered( float dt );

//! Move camera back to the initial position (looking down towards origin of world's coordinates)
void resetView( float distance );

private:
void setCameraData( float x, float y, float dist, float pitch = 0, float yaw = 0 );

signals:
//! Emitted when camera has been updated
void cameraChanged();
//! Emitted when viewport rectangle has been updated
void viewportChanged();

private slots:
@@ -7,7 +7,11 @@

class QDomElement;

//! Basic shading material used for rendering
/** \ingroup 3d
* Basic shading material used for rendering based on the Phong shading model
* with three color components: ambient, diffuse and specular.
* \since QGIS 3.0
*/
class _3D_EXPORT QgsPhongMaterialSettings
{
public:
@@ -19,17 +23,27 @@ class _3D_EXPORT QgsPhongMaterialSettings
{
}

//! Returns ambient color component
QColor ambient() const { return mAmbient; }
//! Returns diffuse color component
QColor diffuse() const { return mDiffuse; }
//! Returns specular color component
QColor specular() const { return mSpecular; }
//! Returns shininess of the surface
float shininess() const { return mShininess; }

//! Sets ambient color component
void setAmbient( const QColor &ambient ) { mAmbient = ambient; }
//! Sets diffuse color component
void setDiffuse( const QColor &diffuse ) { mDiffuse = diffuse; }
//! Sets specular color component
void setSpecular( const QColor &specular ) { mSpecular = specular; }
//! Sets shininess of the surface
void setShininess( float shininess ) { mShininess = shininess; }

//! Reads settings from a DOM element
void readXml( const QDomElement &elem );
//! Writes settings to a DOM element
void writeXml( QDomElement &elem ) const;

private:
@@ -8,7 +8,10 @@
#include "qgs3dutils.h"


//! 3D symbol that draws linestring geometries as planar polygons (created from lines using a buffer with given thickness).
/** \ingroup 3d
* 3D symbol that draws linestring geometries as planar polygons (created from lines using a buffer with given thickness).
* \since QGIS 3.0
*/
class _3D_EXPORT QgsLine3DSymbol : public QgsAbstract3DSymbol
{
public:
@@ -20,22 +23,34 @@ class _3D_EXPORT QgsLine3DSymbol : public QgsAbstract3DSymbol
void writeXml( QDomElement &elem, const QgsReadWriteContext &context ) const override;
void readXml( const QDomElement &elem, const QgsReadWriteContext &context ) override;

//! Returns method that determines altitude (whether to clamp to feature to terrain)
AltitudeClamping altitudeClamping() const { return mAltClamping; }
//! Sets method that determines altitude (whether to clamp to feature to terrain)
void setAltitudeClamping( AltitudeClamping altClamping ) { mAltClamping = altClamping; }

//! Returns method that determines how altitude is bound to individual vertices
AltitudeBinding altitudeBinding() const { return mAltBinding; }
//! Sets method that determines how altitude is bound to individual vertices
void setAltitudeBinding( AltitudeBinding altBinding ) { mAltBinding = altBinding; }

//! Returns width of the line symbol (in map units)
float width() const { return mWidth; }
//! Sets width of the line symbol (in map units)
void setWidth( float width ) { mWidth = width; }

//! Returns height (altitude) of the symbol (in map units)
float height() const { return mHeight; }
//! Sets height (altitude) of the symbol (in map units)
void setHeight( float height ) { mHeight = height; }

//! Returns extrusion height (in map units)
float extrusionHeight() const { return mExtrusionHeight; }
//! Sets extrusion height (in map units)
void setExtrusionHeight( float extrusionHeight ) { mExtrusionHeight = extrusionHeight; }

//! 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; }

private:
@@ -8,7 +8,10 @@
#include "qgs3dutils.h"


//! 3D symbol that draws polygon geometries as planar polygons, optionally extruded (with added walls).
/** \ingroup 3d
* 3D symbol that draws polygon geometries as planar polygons, optionally extruded (with added walls).
* \since QGIS 3.0
*/
class _3D_EXPORT QgsPolygon3DSymbol : public QgsAbstract3DSymbol
{
public:
@@ -20,19 +23,29 @@ class _3D_EXPORT QgsPolygon3DSymbol : public QgsAbstract3DSymbol
void writeXml( QDomElement &elem, const QgsReadWriteContext &context ) const override;
void readXml( const QDomElement &elem, const QgsReadWriteContext &context ) override;

//! Returns method that determines altitude (whether to clamp to feature to terrain)
AltitudeClamping altitudeClamping() const { return mAltClamping; }
//! Sets method that determines altitude (whether to clamp to feature to terrain)
void setAltitudeClamping( AltitudeClamping altClamping ) { mAltClamping = altClamping; }

//! Returns method that determines how altitude is bound to individual vertices
AltitudeBinding altitudeBinding() const { return mAltBinding; }
//! Sets method that determines how altitude is bound to individual vertices
void setAltitudeBinding( AltitudeBinding altBinding ) { mAltBinding = altBinding; }

//! Returns height (altitude) of the symbol (in map units)
float height() const { return mHeight; }
//! Sets height (altitude) of the symbol (in map units)
void setHeight( float height ) { mHeight = height; }

//! Returns extrusion height (in map units)
float extrusionHeight() const { return mExtrusionHeight; }
//! Sets extrusion height (in map units)
void setExtrusionHeight( float extrusionHeight ) { mExtrusionHeight = extrusionHeight; }

//! 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; }

private:
@@ -12,7 +12,9 @@
#include <Qt3DRender/QObjectPicker>


///@cond PRIVATE

//! Factory for map update jobs
class TerrainMapUpdateJobFactory : public ChunkQueueJobFactory
{
public:
@@ -30,6 +32,7 @@ class TerrainMapUpdateJobFactory : public ChunkQueueJobFactory
MapTextureGenerator *mMapTextureGenerator;
};

/// @endcond



@@ -57,6 +57,7 @@ class Terrain : public ChunkedEntity
QList<QgsMapLayer *> mLayers;
};

///@cond PRIVATE

#include "chunkloader.h"

@@ -77,4 +78,7 @@ class TerrainMapUpdateJob : public ChunkQueueJob
int mJobId;
};

/// @endcond


#endif // TERRAIN_H
@@ -29,7 +29,7 @@ namespace Qt3DCore
*
* \since QGIS 3.0
*/
class CORE_EXPORT QgsAbstract3DRenderer
class CORE_EXPORT QgsAbstract3DRenderer SIP_ABSTRACT
{
public:
virtual ~QgsAbstract3DRenderer();

0 comments on commit 990f353

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