qgsline3dsymbol: Rename height property to offset

The `height` property is in fact a vertical offset applied to the
line. Also, the `offset` phrase is already used by the terrain for
similar purposes.

height() are setHeight() are kept for API compatibility reasons.

python/3d/auto_generated/symbols/qgsline3dsymbol.sip.in

@@ -80,13 +80,34 @@ Returns width of the line symbol (in map units)
 Sets width of the line symbol (in map units)
 %End
 
-    float height() const;
+ float height() const /Deprecated/;
 %Docstring
 Returns height (altitude) of the symbol (in map units)
+
+.. deprecated:: QGIS 3.36.
+   Use :py:func:`~QgsLine3DSymbol.offset` instead.
 %End
-    void setHeight( float height );
+
+ void setHeight( float height ) /Deprecated/;
 %Docstring
 Sets height (altitude) of the symbol (in map units)
+
+.. deprecated:: QGIS 3.36.
+   Use :py:func:`~QgsLine3DSymbol.setOffset` instead.
+%End
+
+    float offset() const;
+%Docstring
+Returns vertical offset of the symbol (in map units)
+
+.. versionadded:: 3.36
+%End
+
+    void setOffset( float offset );
+%Docstring
+Sets vertical offset of the symbol (in map units)
+
+.. versionadded:: 3.36
 %End
 
     float extrusionHeight() const;

src/3d/symbols/qgsline3dsymbol.cpp

@@ -36,7 +36,7 @@ QgsAbstract3DSymbol *QgsLine3DSymbol::clone() const
   result->mAltClamping = mAltClamping;
   result->mAltBinding = mAltBinding;
   result->mWidth = mWidth;
-  result->mHeight = mHeight;
+  result->mOffset = mOffset;
   result->mExtrusionHeight = mExtrusionHeight;
   result->mRenderAsSimpleLines = mRenderAsSimpleLines;
   result->mMaterialSettings.reset( mMaterialSettings->clone() );
@@ -53,7 +53,7 @@ void QgsLine3DSymbol::writeXml( QDomElement &elem, const QgsReadWriteContext &co
   QDomElement elemDataProperties = doc.createElement( QStringLiteral( "data" ) );
   elemDataProperties.setAttribute( QStringLiteral( "alt-clamping" ), Qgs3DUtils::altClampingToString( mAltClamping ) );
   elemDataProperties.setAttribute( QStringLiteral( "alt-binding" ), Qgs3DUtils::altBindingToString( mAltBinding ) );
-  elemDataProperties.setAttribute( QStringLiteral( "height" ), mHeight );
+  elemDataProperties.setAttribute( QStringLiteral( "offset" ), mOffset );
   elemDataProperties.setAttribute( QStringLiteral( "extrusion-height" ), mExtrusionHeight );
   elemDataProperties.setAttribute( QStringLiteral( "simple-lines" ), mRenderAsSimpleLines ? QStringLiteral( "1" ) : QStringLiteral( "0" ) );
   elemDataProperties.setAttribute( QStringLiteral( "width" ), mWidth );
@@ -72,7 +72,7 @@ void QgsLine3DSymbol::readXml( const QDomElement &elem, const QgsReadWriteContex
   const QDomElement elemDataProperties = elem.firstChildElement( QStringLiteral( "data" ) );
   mAltClamping = Qgs3DUtils::altClampingFromString( elemDataProperties.attribute( QStringLiteral( "alt-clamping" ) ) );
   mAltBinding = Qgs3DUtils::altBindingFromString( elemDataProperties.attribute( QStringLiteral( "alt-binding" ) ) );
-  mHeight = elemDataProperties.attribute( QStringLiteral( "height" ) ).toFloat();
+  mOffset = elemDataProperties.attribute( QStringLiteral( "offset" ) ).toFloat();
   mExtrusionHeight = elemDataProperties.attribute( QStringLiteral( "extrusion-height" ) ).toFloat();
   mWidth = elemDataProperties.attribute( QStringLiteral( "width" ) ).toFloat();
   mRenderAsSimpleLines = elemDataProperties.attribute( QStringLiteral( "simple-lines" ), QStringLiteral( "0" ) ).toInt();
@@ -110,7 +110,7 @@ void QgsLine3DSymbol::setDefaultPropertiesFromLayer( const QgsVectorLayer *layer
   mAltClamping = props->clamping();
   mAltBinding = props->binding();
   mExtrusionHeight = props->extrusionEnabled() ? static_cast< float>( props->extrusionHeight() ) : 0.0f;
-  mHeight = static_cast< float >( props->zOffset() );
+  mOffset = static_cast< float >( props->zOffset() );
 }
 
 QgsAbstract3DSymbol *QgsLine3DSymbol::create()

src/3d/symbols/qgsline3dsymbol.h

@@ -69,10 +69,33 @@ class _3D_EXPORT QgsLine3DSymbol : public QgsAbstract3DSymbol SIP_NODEFAULTCTORS
     //! 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; }
+     * Returns height (altitude) of the symbol (in map units)
-    //! Sets height (altitude) of the symbol (in map units)
+     *
-    void setHeight( float height ) { mHeight = height; }
+     * \deprecated since QGIS 3.36. Use offset() instead.
+     */
+    Q_DECL_DEPRECATED float height() const SIP_DEPRECATED { return mOffset; }
+
+    /**
+     * Sets height (altitude) of the symbol (in map units)
+     *
+     * \deprecated since QGIS 3.36. Use setOffset() instead.
+     */
+    Q_DECL_DEPRECATED void setHeight( float height ) SIP_DEPRECATED { mOffset = height; }
+
+    /**
+     * Returns vertical offset of the symbol (in map units)
+     *
+     * \since QGIS 3.36
+     */
+    float offset() const { return mOffset; }
+
+    /**
+     * Sets vertical offset of the symbol (in map units)
+     *
+     * \since QGIS 3.36
+     */
+    void setOffset( float offset ) { mOffset = offset; }
 
     //! Returns extrusion height (in map units)
     float extrusionHeight() const { return mExtrusionHeight; }
@@ -107,7 +130,7 @@ class _3D_EXPORT QgsLine3DSymbol : public QgsAbstract3DSymbol SIP_NODEFAULTCTORS
     Qgis::AltitudeBinding mAltBinding = Qgis::AltitudeBinding::Centroid;
 
     float mWidth = 2.0f;            //!< Line width (horizontally)
-    float mHeight = 0.0f;           //!< Base height of polygons
+    float mOffset = 0.0f;           //!< Base height of polygons
     float mExtrusionHeight = 0.0f;  //!< How much to extrude (0 means no walls)
     bool mRenderAsSimpleLines = false;   //!< Whether to render data with simple lines (otherwise it uses buffer)
     std::unique_ptr< QgsAbstractMaterialSettings > mMaterialSettings;  //!< Defines appearance of objects

src/3d/symbols/qgsline3dsymbol_p.cpp

@@ -150,7 +150,7 @@ void QgsBufferedLine3DSymbolHandler::processFeature( const QgsFeature &f, const
   if ( QgsWkbTypes::flatType( buffered->wkbType() ) == Qgis::WkbType::Polygon )
   {
     QgsPolygon *polyBuffered = static_cast<QgsPolygon *>( buffered );
-    processPolygon( polyBuffered, f.id(), mSymbol->height(), mSymbol->extrusionHeight(), context, out );
+    processPolygon( polyBuffered, f.id(), mSymbol->offset(), mSymbol->extrusionHeight(), context, out );
   }
   else if ( QgsWkbTypes::flatType( buffered->wkbType() ) == Qgis::WkbType::MultiPolygon )
   {
@@ -158,7 +158,7 @@ void QgsBufferedLine3DSymbolHandler::processFeature( const QgsFeature &f, const
     for ( int i = 0; i < mpolyBuffered->numGeometries(); ++i )
     {
       QgsPolygon *polyBuffered = static_cast<QgsPolygon *>( mpolyBuffered->polygonN( i ) )->clone(); // need to clone individual geometry parts
-      processPolygon( polyBuffered, f.id(), mSymbol->height(), mSymbol->extrusionHeight(), context, out );
+      processPolygon( polyBuffered, f.id(), mSymbol->offset(), mSymbol->extrusionHeight(), context, out );
     }
     delete buffered;
   }
@@ -262,8 +262,8 @@ bool QgsSimpleLine3DSymbolHandler::prepare( const Qgs3DRenderContext &context, Q
 {
   Q_UNUSED( attributeNames )
 
-  outNormal.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->height(), &context.map() );
+  outNormal.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->offset(), &context.map() );
-  outSelected.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->height(), &context.map() );
+  outSelected.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->offset(), &context.map() );
 
   return true;
 }
@@ -377,8 +377,8 @@ bool QgsThickLine3DSymbolHandler::prepare( const Qgs3DRenderContext &context, QS
 
   outNormal.withAdjacency = true;
   outSelected.withAdjacency = true;
-  outNormal.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->height(), &context.map() );
+  outNormal.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->offset(), &context.map() );
-  outSelected.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->height(), &context.map() );
+  outSelected.init( mSymbol->altitudeClamping(), mSymbol->altitudeBinding(), mSymbol->offset(), &context.map() );
 
   return true;
 }

src/app/3d/qgsline3dsymbolwidget.cpp

@@ -59,7 +59,7 @@ void QgsLine3DSymbolWidget::setSymbol( const QgsAbstract3DSymbol *symbol, QgsVec
     return;
 
   spinWidth->setValue( lineSymbol->width() );
-  spinHeight->setValue( lineSymbol->height() );
+  spinHeight->setValue( lineSymbol->offset() );
   spinExtrusion->setValue( lineSymbol->extrusionHeight() );
   cboAltClamping->setCurrentIndex( cboAltClamping->findData( static_cast< int >( lineSymbol->altitudeClamping() ) ) );
   cboAltBinding->setCurrentIndex( static_cast<int>( lineSymbol->altitudeBinding() ) );
@@ -74,7 +74,7 @@ QgsAbstract3DSymbol *QgsLine3DSymbolWidget::symbol()
 {
   std::unique_ptr< QgsLine3DSymbol > sym = std::make_unique< QgsLine3DSymbol >();
   sym->setWidth( spinWidth->value() );
-  sym->setHeight( spinHeight->value() );
+  sym->setOffset( spinHeight->value() );
   sym->setExtrusionHeight( spinExtrusion->value() );
   sym->setAltitudeClamping( static_cast<Qgis::AltitudeClamping>( cboAltClamping->currentData().toInt() ) );
   sym->setAltitudeBinding( static_cast<Qgis::AltitudeBinding>( cboAltBinding->currentIndex() ) );

tests/src/3d/testqgs3drendering.cpp

@@ -735,7 +735,7 @@ void TestQgs3DRendering::testBufferedLineRenderingWidth()
   QgsLine3DSymbol *lineSymbol = new QgsLine3DSymbol;
   lineSymbol->setWidth( 20 );
   lineSymbol->setExtrusionHeight( 30 );
-  lineSymbol->setHeight( 10 );
+  lineSymbol->setOffset( 10 );
   QgsPhongMaterialSettings matSettings;
   matSettings.setAmbient( Qt::red );
   lineSymbol->setMaterialSettings( matSettings.clone() );