Docstring/sip fixes in core/3d

python/CMakeLists.txt

@@ -102,6 +102,7 @@ ENDIF ()
 
 INCLUDE_DIRECTORIES(
   ${CMAKE_SOURCE_DIR}/src/core
+  ${CMAKE_SOURCE_DIR}/src/core/3d
   ${CMAKE_SOURCE_DIR}/src/core/annotations
   ${CMAKE_SOURCE_DIR}/src/core/auth
   ${CMAKE_SOURCE_DIR}/src/core/expression

python/core/3d/qgs3drendererregistry.sip

@@ -0,0 +1,96 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/3d/qgs3drendererregistry.h                                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
+
+class Qgs3DRendererAbstractMetadata
+{
+%Docstring
+ Base metadata class for 3D renderers. Instances of derived classes may be registered in Qgs3DRendererRegistry.
+.. versionadded:: 3.0
+%End
+
+%TypeHeaderCode
+#include "qgs3drendererregistry.h"
+%End
+  public:
+
+    virtual ~Qgs3DRendererAbstractMetadata();
+
+    QString type() const;
+%Docstring
+ Returns unique identifier of the 3D renderer class
+ :rtype: str
+%End
+
+    virtual QgsAbstract3DRenderer *createRenderer( QDomElement &elem, const QgsReadWriteContext &context ) = 0 /Factory/;
+%Docstring
+ Returns new instance of the renderer given the DOM element. Returns NULL on error.
+ Pure virtual function: must be implemented in derived classes.
+ :rtype: QgsAbstract3DRenderer
+%End
+
+  protected:
+
+    explicit Qgs3DRendererAbstractMetadata( const QString &type );
+%Docstring
+ Constructor of the base class
+%End
+
+  protected:
+};
+
+
+class Qgs3DRendererRegistry
+{
+%Docstring
+ Keeps track of available 3D renderers. Should be accessed through QgsApplication.renderer3DRegistry() singleton.
+.. versionadded:: 3.0
+%End
+
+%TypeHeaderCode
+#include "qgs3drendererregistry.h"
+%End
+  public:
+    Qgs3DRendererRegistry();
+
+    ~Qgs3DRendererRegistry();
+
+    void addRenderer( Qgs3DRendererAbstractMetadata *metadata /Transfer/ );
+%Docstring
+ Registers a new 3D renderer type. The call takes ownership of the passed metadata object.
+%End
+
+    void removeRenderer( const QString &type );
+%Docstring
+ Unregisters a 3D renderer type
+%End
+
+    Qgs3DRendererAbstractMetadata *rendererMetadata( const QString &type ) const;
+%Docstring
+ Returns metadata for a 3D renderer type (may be used to create a new instance of the type)
+ :rtype: Qgs3DRendererAbstractMetadata
+%End
+
+    QStringList renderersList() const;
+%Docstring
+ Returns a list of all available 3D renderer types.
+ :rtype: list of str
+%End
+
+};
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/3d/qgs3drendererregistry.h                                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/core/3d/qgsabstract3drenderer.sip

@@ -0,0 +1,68 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/3d/qgsabstract3drenderer.h                                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+
+namespace Qt3DCore
+{
+}
+
+class QgsAbstract3DRenderer
+{
+%Docstring
+ Base class for all renderers that may to participate in 3D view.
+
+ 3D renderers implement the method createEntity() that returns a new 3D entity - that entity
+ will be added to the 3D scene to represent data in renderer's display style.
+
+ Renderers may store some custom properties (e.g. materials, sizes) that are written to and read from
+ XML. It is therefore not recommended to store large amount of data within a renderer (e.g. arrays of vertices).
+
+.. versionadded:: 3.0
+%End
+
+%TypeHeaderCode
+#include "qgsabstract3drenderer.h"
+%End
+  public:
+    virtual ~QgsAbstract3DRenderer();
+
+    virtual QString type() const = 0;
+%Docstring
+Returns unique identifier of the renderer class (used to identify subclass)
+ :rtype: str
+%End
+    virtual QgsAbstract3DRenderer *clone() const = 0 /Factory/;
+%Docstring
+Returns a cloned instance
+ :rtype: QgsAbstract3DRenderer
+%End
+
+    virtual void writeXml( QDomElement &elem, const QgsReadWriteContext &context ) const = 0;
+%Docstring
+Writes renderer's properties to given XML element
+%End
+    virtual void readXml( const QDomElement &elem, const QgsReadWriteContext &context ) = 0;
+%Docstring
+Reads renderer's properties from given XML element
+%End
+    virtual void resolveReferences( const QgsProject &project );
+%Docstring
+Resolves references to other objects - second phase of loading - after readXml()
+%End
+};
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/3d/qgsabstract3drenderer.h                                  *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/

python/core/core_auto.sip

@@ -279,6 +279,8 @@
 %Include geometry/qgssurface.sip
 %Include geometry/qgswkbptr.sip
 %Include geometry/qgswkbtypes.sip
+%Include 3d/qgs3drendererregistry.sip
+%Include 3d/qgsabstract3drenderer.sip
 %Include fieldformatter/qgsdatetimefieldformatter.sip
 %Include fieldformatter/qgsfallbackfieldformatter.sip
 %Include fieldformatter/qgskeyvaluefieldformatter.sip

python/core/qgsapplication.sip

@@ -704,6 +704,15 @@ Returns path to the build output directory. Valid only when running from build d
  :rtype: QgsFieldFormatterRegistry
 %End
 
+    static Qgs3DRendererRegistry *renderer3DRegistry();
+%Docstring
+ Returns registry of available 3D renderers.
+.. note::
+
+   not available in Python bindings
+.. versionadded:: 3.0
+ :rtype: Qgs3DRendererRegistry
+%End
 
     static QString nullRepresentation();
 %Docstring

python/core/qgsmaplayer.sip

@@ -760,7 +760,24 @@ Return pointer to layer's undo stack
  :rtype: QgsMapLayerStyleManager
 %End
 
+    void setRenderer3D( QgsAbstract3DRenderer *renderer /Transfer/ );
+%Docstring
+ Sets 3D renderer for the layer. Takes ownership of the renderer.
+.. note::
 
+   not available in Python bindings
+.. versionadded:: 3.0
+%End
+
+    QgsAbstract3DRenderer *renderer3D() const;
+%Docstring
+ Returns 3D renderer associated with the layer. May be null.
+.. note::
+
+   not available in Python bindings
+.. versionadded:: 3.0
+ :rtype: QgsAbstract3DRenderer
+%End
 
     bool isInScaleRange( double scale ) const;
 %Docstring

scripts/spell_check/check_spelling.sh

@@ -23,7 +23,7 @@
 # fi
 
 # extensions or files that should be excluded from file list if :% is appended in the spelling.dat file
-EXCLUDE_SCRIPT_LIST='(\.(xml|svg|sip|t2t|pl|sh|qgs|badquote|cmake(\.in)?)|^(debian/copyright|cmake_templates/.*|INSTALL|NEWS|tests/testdata/labeling/README.rst|tests/testdata/font/QGIS-Vera/COPYRIGHT.TXT|doc/(news|INSTALL)\.html))$'
+EXCLUDE_SCRIPT_LIST='(\.(xml|svg|sip|t2t|pl|sh|qgs|badquote|cmake(\.in)?)|^(debian/copyright|cmake_templates/.*|INSTALL|NEWS|tests/testdata/labeling/README.rst|tests/testdata/font/QGIS-Vera/COPYRIGHT.TXT|doc/(news|INSTALL)\.html)|src/3d/poly2tri/.*)$'
 
 DIR=$(git rev-parse --show-toplevel)/scripts/spell_check
 

src/core/3d/qgs3drendererregistry.cpp

@@ -1,14 +1,18 @@
 #include "qgs3drendererregistry.h"
 
 
-Qgs3DRendererAbstractMetadata::Qgs3DRendererAbstractMetadata( const QString &name )
+Qgs3DRendererAbstractMetadata::Qgs3DRendererAbstractMetadata( const QString &type )
-  : mName( name )
+  : mType( type )
 {
 }
 
-QString Qgs3DRendererAbstractMetadata::name() const
+Qgs3DRendererAbstractMetadata::~Qgs3DRendererAbstractMetadata()
 {
-  return mName;
+}
+
+QString Qgs3DRendererAbstractMetadata::type() const
+{
+  return mType;
 }
 
 
@@ -26,17 +30,17 @@ Qgs3DRendererRegistry::~Qgs3DRendererRegistry()
 
 void Qgs3DRendererRegistry::addRenderer( Qgs3DRendererAbstractMetadata *metadata )
 {
-  mRenderers.insert( metadata->name(), metadata );
+  mRenderers.insert( metadata->type(), metadata );
 }
 
-void Qgs3DRendererRegistry::removeRenderer( const QString &name )
+void Qgs3DRendererRegistry::removeRenderer( const QString &type )
 {
-  delete mRenderers.take( name );
+  delete mRenderers.take( type );
 }
 
-Qgs3DRendererAbstractMetadata *Qgs3DRendererRegistry::rendererMetadata( const QString &name ) const
+Qgs3DRendererAbstractMetadata *Qgs3DRendererRegistry::rendererMetadata( const QString &type ) const
 {
-  return mRenderers.value( name );
+  return mRenderers.value( type );
 }
 
 QStringList Qgs3DRendererRegistry::renderersList() const

src/core/3d/qgs3drendererregistry.h

@@ -2,6 +2,7 @@
 #define QGS3DRENDERERREGISTRY_H
 
 #include "qgis_core.h"
+#include "qgis_sip.h"
 
 #include <QMap>
 
@@ -19,17 +20,29 @@ class CORE_EXPORT Qgs3DRendererAbstractMetadata
 {
   public:
 
-    Qgs3DRendererAbstractMetadata( const QString &name );
+    virtual ~Qgs3DRendererAbstractMetadata();
 
-    QString name() const;
+    /**
+     * Returns unique identifier of the 3D renderer class
+     */
+    QString type() const;
 
-    /** Return new instance of the renderer given the DOM element. Returns NULL on error.
+    /**
-     * Pure virtual function: must be implemented in derived classes.  */
+     * Returns new instance of the renderer given the DOM element. Returns NULL on error.
-    virtual QgsAbstract3DRenderer *createRenderer( QDomElement &elem, const QgsReadWriteContext &context ) = 0;
+     * Pure virtual function: must be implemented in derived classes.
+     */
+    virtual QgsAbstract3DRenderer *createRenderer( QDomElement &elem, const QgsReadWriteContext &context ) = 0 SIP_FACTORY;
 
   protected:
-    //! name used within QGIS for identification (the same what renderer's type() returns)
+
-    QString mName;
+    /**
+     * Constructor of the base class
+     */
+    explicit Qgs3DRendererAbstractMetadata( const QString &type );
+
+  protected:
+    //! Type used within QGIS for identification (the same what renderer's type() returns)
+    QString mType;
 };
 
 
@@ -45,13 +58,24 @@ class CORE_EXPORT Qgs3DRendererRegistry
 
     ~Qgs3DRendererRegistry();
 
-    //! takes ownership
+    /**
-    void addRenderer( Qgs3DRendererAbstractMetadata *metadata );
+     * Registers a new 3D renderer type. The call takes ownership of the passed metadata object.
+     */
+    void addRenderer( Qgs3DRendererAbstractMetadata *metadata SIP_TRANSFER );
 
-    void removeRenderer( const QString &name );
+    /**
+     * Unregisters a 3D renderer type
+     */
+    void removeRenderer( const QString &type );
 
-    Qgs3DRendererAbstractMetadata *rendererMetadata( const QString &name ) const;
+    /**
+     * Returns metadata for a 3D renderer type (may be used to create a new instance of the type)
+     */
+    Qgs3DRendererAbstractMetadata *rendererMetadata( const QString &type ) const;
 
+    /**
+     * Returns a list of all available 3D renderer types.
+     */
     QStringList renderersList() const;
 
   private:

src/core/3d/qgsabstract3drenderer.h

@@ -2,6 +2,7 @@
 #define QGSABSTRACT3DRENDERER_H
 
 #include "qgis_core.h"
+#include "qgis_sip.h"
 
 #include <QString>
 
@@ -15,22 +16,36 @@ namespace Qt3DCore
   class QEntity;
 }
 
-//! Base class for all renderers that may to participate in 3D view.
+/** \ingroup core
-class CORE_EXPORT QgsAbstract3DRenderer //: public QObject
+ * Base class for all renderers that may to participate in 3D view.
+ *
+ * 3D renderers implement the method createEntity() that returns a new 3D entity - that entity
+ * will be added to the 3D scene to represent data in renderer's display style.
+ *
+ * Renderers may store some custom properties (e.g. materials, sizes) that are written to and read from
+ * XML. It is therefore not recommended to store large amount of data within a renderer (e.g. arrays of vertices).
+ *
+ * \since QGIS 3.0
+ */
+class CORE_EXPORT QgsAbstract3DRenderer
 {
-    //Q_OBJECT
   public:
     virtual ~QgsAbstract3DRenderer();
 
+    //! Returns unique identifier of the renderer class (used to identify subclass)
     virtual QString type() const = 0;
-    virtual QgsAbstract3DRenderer *clone() const = 0;
+    //! Returns a cloned instance
-    virtual Qt3DCore::QEntity *createEntity( const Qgs3DMapSettings &map ) const = 0;
+    virtual QgsAbstract3DRenderer *clone() const = 0 SIP_FACTORY;
+    //! Returns a 3D entity that will be used to show renderer's data in 3D scene
+    virtual Qt3DCore::QEntity *createEntity( const Qgs3DMapSettings &map ) const = 0 SIP_SKIP;
 
+    //! Writes renderer's properties to given XML element
     virtual void writeXml( QDomElement &elem, const QgsReadWriteContext &context ) const = 0;
+    //! Reads renderer's properties from given XML element
     virtual void readXml( const QDomElement &elem, const QgsReadWriteContext &context ) = 0;
+    //! Resolves references to other objects - second phase of loading - after readXml()
     virtual void resolveReferences( const QgsProject &project );
 };
 
 
-
 #endif // QGSABSTRACT3DRENDERER_H

src/core/qgsapplication.h

@@ -589,7 +589,7 @@ class CORE_EXPORT QgsApplication : public QApplication
      * \note not available in Python bindings
      * \since QGIS 3.0
      */
-    static Qgs3DRendererRegistry *renderer3DRegistry() SIP_SKIP;
+    static Qgs3DRendererRegistry *renderer3DRegistry();
 
     /**
      * This string is used to represent the value `NULL` throughout QGIS.

src/core/qgsmaplayer.h

@@ -686,14 +686,14 @@ class CORE_EXPORT QgsMapLayer : public QObject
      * \note not available in Python bindings
      * \since QGIS 3.0
      */
-    void setRenderer3D( QgsAbstract3DRenderer *renderer SIP_TRANSFER ) SIP_SKIP;
+    void setRenderer3D( QgsAbstract3DRenderer *renderer SIP_TRANSFER );
 
     /**
      * Returns 3D renderer associated with the layer. May be null.
      * \note not available in Python bindings
      * \since QGIS 3.0
      */
-    QgsAbstract3DRenderer *renderer3D() const SIP_SKIP;
+    QgsAbstract3DRenderer *renderer3D() const;
 
     /** Tests whether the layer should be visible at the specified \a scale.
      *  The \a scale value indicates the scale denominator, e.g. 1000.0 for a 1:1000 map.