qgstextrenderer.cpp

Go to the documentation of this file.

/***************************************************************************
  qgstextrenderer.cpp
  -------------------
   begin                : September 2015
   copyright            : (C) Nyall Dawson
   email                : nyall dot dawson at gmail dot com
 ***************************************************************************
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU General Public License as published by  *
 *   the Free Software Foundation; either version 2 of the License, or     *
 *   (at your option) any later version.                                   *
 *                                                                         *
 ***************************************************************************/
 
#include "qgstextrenderer.h"
 
#include <memory>
#include <optional>
 
#include "qgsapplication.h"
#include "qgsfillsymbol.h"
#include "qgsgeos.h"
#include "qgsimagecache.h"
#include "qgsmarkersymbol.h"
#include "qgsmarkersymbollayer.h"
#include "qgspainteffect.h"
#include "qgspainterswapper.h"
#include "qgspainting.h"
#include "qgspallabeling.h"
#include "qgssymbollayerutils.h"
#include "qgstextdocument.h"
#include "qgstextdocumentmetrics.h"
#include "qgstextformat.h"
#include "qgstextfragment.h"
#include "qgstextmetrics.h"
#include "qgstextrendererutils.h"
#include "qgsunittypes.h"
 
#include <QString>
#include <QTextBoundaryFinder>
 
using namespace Qt::StringLiterals;
 
Qgis::TextHorizontalAlignment QgsTextRenderer::convertQtHAlignment( Qt::Alignment alignment )
{
  if ( alignment & Qt::AlignLeft )
    return Qgis::TextHorizontalAlignment::Left;
  else if ( alignment & Qt::AlignRight )
    return Qgis::TextHorizontalAlignment::Right;
  else if ( alignment & Qt::AlignHCenter )
    return Qgis::TextHorizontalAlignment::Center;
  else if ( alignment & Qt::AlignJustify )
    return Qgis::TextHorizontalAlignment::Justify;
 
  // not supported?
  return Qgis::TextHorizontalAlignment::Left;
}
 
Qgis::TextVerticalAlignment QgsTextRenderer::convertQtVAlignment( Qt::Alignment alignment )
{
  if ( alignment & Qt::AlignTop )
    return Qgis::TextVerticalAlignment::Top;
  else if ( alignment & Qt::AlignBottom )
    return Qgis::TextVerticalAlignment::Bottom;
  else if ( alignment & Qt::AlignVCenter )
    return Qgis::TextVerticalAlignment::VerticalCenter;
  //not supported
  else if ( alignment & Qt::AlignBaseline )
    return Qgis::TextVerticalAlignment::Bottom;
 
  return Qgis::TextVerticalAlignment::Top;
}
 
int QgsTextRenderer::sizeToPixel( double size, const QgsRenderContext &c, Qgis::RenderUnit unit, const QgsMapUnitScale &mapUnitScale )
{
  return static_cast< int >( c.convertToPainterUnits( size, unit, mapUnitScale ) + 0.5 ); //NOLINT
}
 
void QgsTextRenderer::drawText(
  const QRectF &rect,
  double rotation,
  Qgis::TextHorizontalAlignment alignment,
  const QStringList &text,
  QgsRenderContext &context,
  const QgsTextFormat &_format,
  bool,
  Qgis::TextVerticalAlignment vAlignment,
  Qgis::TextRendererFlags flags,
  Qgis::TextLayoutMode mode
)
{
  QgsTextFormat lFormat = _format;
  if ( _format.dataDefinedProperties().hasActiveProperties() ) // note, we use format instead of tmpFormat here, it's const and potentially avoids a detach
    lFormat.updateDataDefinedProperties( context );
 
  // DO NOT USE _format in the following code, always use lFormat!!
  QgsTextDocumentRenderContext documentContext;
  documentContext.setFlags( flags );
  documentContext.setMaximumWidth( rect.width() );
 
  const QgsTextDocument document = QgsTextDocument::fromTextAndFormat( text, lFormat );
 
  const double fontScale = calculateScaleFactorForFormat( context, lFormat );
  const QgsTextDocumentMetrics metrics = QgsTextDocumentMetrics::calculateMetrics( document, lFormat, context, fontScale, documentContext );
 
  drawDocument( rect, lFormat, metrics.document(), metrics, context, alignment, vAlignment, rotation, mode, flags );
}
 
void QgsTextRenderer::drawDocument(
  const QRectF &rect,
  const QgsTextFormat &format,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  QgsRenderContext &context,
  Qgis::TextHorizontalAlignment horizontalAlignment,
  Qgis::TextVerticalAlignment verticalAlignment,
  double rotation,
  Qgis::TextLayoutMode mode,
  Qgis::TextRendererFlags
)
{
  const QgsTextFormat tmpFormat = updateShadowPosition( format );
 
  Qgis::TextComponents components = Qgis::TextComponent::Text;
  if ( tmpFormat.background().enabled() )
  {
    components |= Qgis::TextComponent::Background;
  }
 
  if ( tmpFormat.shadow().enabled() )
  {
    components |= Qgis::TextComponent::Shadow;
  }
 
  if ( tmpFormat.buffer().enabled() )
  {
    components |= Qgis::TextComponent::Buffer;
  }
 
  drawParts( rect, rotation, horizontalAlignment, verticalAlignment, document, metrics, context, tmpFormat, components, mode );
}
 
void QgsTextRenderer::drawText( QPointF point, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &_format, bool )
{
  QgsTextFormat lFormat = _format;
  if ( _format.dataDefinedProperties().hasActiveProperties() ) // note, we use _format instead of tmpFormat here, it's const and potentially avoids a detach
    lFormat.updateDataDefinedProperties( context );
  lFormat = updateShadowPosition( lFormat );
 
  // DO NOT USE _format in the following code, always use lFormat!!
  const QgsTextDocument document = QgsTextDocument::fromTextAndFormat( textLines, lFormat );
  const double fontScale = calculateScaleFactorForFormat( context, lFormat );
  const QgsTextDocumentMetrics metrics = QgsTextDocumentMetrics::calculateMetrics( document, lFormat, context, fontScale );
 
  drawDocument( point, lFormat, metrics.document(), metrics, context, alignment, rotation );
}
 
void QgsTextRenderer::drawDocument(
  QPointF point,
  const QgsTextFormat &_format,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  QgsRenderContext &context,
  Qgis::TextHorizontalAlignment alignment,
  double rotation,
  Qgis::TextLayoutMode mode
)
{
  const QgsTextFormat lFormat = updateShadowPosition( _format );
  // DO NOT USE _format in the following code, always use lFormat!!
 
  Qgis::TextComponents components = Qgis::TextComponent::Text;
  if ( lFormat.background().enabled() )
  {
    components |= Qgis::TextComponent::Background;
  }
 
  if ( lFormat.shadow().enabled() )
  {
    components |= Qgis::TextComponent::Shadow;
  }
 
  if ( lFormat.buffer().enabled() )
  {
    components |= Qgis::TextComponent::Buffer;
  }
 
  drawParts( point, rotation, alignment, document, metrics, context, lFormat, components, mode );
}
 
void QgsTextRenderer::drawTextOnLine(
  const QPolygonF &line, const QString &text, QgsRenderContext &context, const QgsTextFormat &_format, double offsetAlongLine, double offsetFromLine, Qgis::CurvedTextFlags flags, Qgis::TextAnchorPoint textAnchor
)
{
  QgsTextFormat lFormat = _format;
  if ( _format.dataDefinedProperties().hasActiveProperties() ) // note, we use _format instead of tmpFormat here, it's const and potentially avoids a detach
    lFormat.updateDataDefinedProperties( context );
  lFormat = updateShadowPosition( lFormat );
 
  // DO NOT USE _format in the following code, always use lFormat!!
 
  // todo handle newlines??
  const QgsTextDocument document = QgsTextDocument::fromTextAndFormat( { text }, lFormat );
 
  drawDocumentOnLine( line, lFormat, document, context, offsetAlongLine, offsetFromLine, flags, textAnchor );
}
 
void QgsTextRenderer::drawDocumentOnLine(
  const QPolygonF &line,
  const QgsTextFormat &format,
  const QgsTextDocument &document,
  QgsRenderContext &context,
  double offsetAlongLine,
  double offsetFromLine,
  Qgis::CurvedTextFlags flags,
  Qgis::TextAnchorPoint textAnchor
)
{
  QPolygonF labelBaselineCurve = line;
  if ( !qgsDoubleNear( offsetFromLine, 0 ) )
  {
    std::unique_ptr< QgsLineString > ring( QgsLineString::fromQPolygonF( line ) );
    QgsGeos geos( ring.get() );
    std::unique_ptr< QgsLineString > offsetCurve( dynamic_cast< QgsLineString * >( geos.offsetCurve( offsetFromLine, 4, Qgis::JoinStyle::Round, 2 ) ) );
    if ( !offsetCurve )
      return;
 
#if GEOS_VERSION_MAJOR == 3 && GEOS_VERSION_MINOR < 11
    if ( offsetFromLine < 0 )
    {
      // geos < 3.11 reverses the direction of offset curves with negative distances -- we don't want that!
      std::unique_ptr< QgsLineString > reversed( offsetCurve->reversed() );
      if ( !reversed )
        return;
 
      offsetCurve = std::move( reversed );
    }
#endif
 
    labelBaselineCurve = offsetCurve->asQPolygonF();
  }
 
  const double fontScale = calculateScaleFactorForFormat( context, format );
 
  const QFont baseFont = format.scaledFont( context, fontScale );
  const double letterSpacing = baseFont.letterSpacing() / fontScale;
  const double wordSpacing = baseFont.wordSpacing() / fontScale;
 
  QStringList graphemes;
  QVector< QgsTextCharacterFormat > graphemeFormats;
  QVector< QgsTextDocumentMetrics > graphemeMetrics;
 
  for ( const QgsTextBlock &block : std::as_const( document ) )
  {
    for ( const QgsTextFragment &fragment : block )
    {
      const QStringList fragmentGraphemes = QgsPalLabeling::splitToGraphemes( fragment.text() );
      for ( const QString &grapheme : fragmentGraphemes )
      {
        graphemes.append( grapheme );
        graphemeFormats.append( fragment.characterFormat() );
 
        QgsTextDocument document;
        document.append( QgsTextBlock( QgsTextFragment( grapheme, fragment.characterFormat() ) ) );
 
        graphemeMetrics.append( QgsTextDocumentMetrics::calculateMetrics( document, format, context, fontScale ) );
      }
    }
  }
 
  QVector< double > characterWidths( graphemes.count() );
  QVector< double > characterHeights( graphemes.count() );
  QVector< double > characterDescents( graphemes.count() );
  QFont previousNonSuperSubScriptFont;
 
  for ( int i = 0; i < graphemes.count(); i++ )
  {
    // reconstruct how Qt creates word spacing, then adjust per individual stored character
    // this will allow the text renderer to create each candidate width = character width + correct spacing
 
    double graphemeFirstCharHorizontalAdvanceWithLetterSpacing = 0;
    double graphemeFirstCharHorizontalAdvance = 0;
    double graphemeHorizontalAdvance = 0;
    double characterDescent = 0;
    double characterHeight = 0;
    const QgsTextCharacterFormat *graphemeFormat = &graphemeFormats[i];
 
    QFont graphemeFont = baseFont;
    graphemeFormat->updateFontForFormat( graphemeFont, context, fontScale );
 
    if ( i == 0 )
      previousNonSuperSubScriptFont = graphemeFont;
 
    if ( graphemeFormat->hasVerticalAlignmentSet() )
    {
      switch ( graphemeFormat->verticalAlignment() )
      {
        case Qgis::TextCharacterVerticalAlignment::Normal:
          previousNonSuperSubScriptFont = graphemeFont;
          break;
 
        case Qgis::TextCharacterVerticalAlignment::SuperScript:
        case Qgis::TextCharacterVerticalAlignment::SubScript:
        {
          if ( graphemeFormat->fontPointSize() < 0 )
          {
            // if fragment has no explicit font size set, then we scale the inherited font size to 60% of base font size
            // this allows for easier use of super/subscript in labels as "my text<sup>2</sup>" will automatically render
            // the superscript in a smaller font size. BUT if the fragment format HAS a non -1 font size then it indicates
            // that the document has an explicit font size for the super/subscript element, eg "my text<sup style="font-size: 6pt">2</sup>"
            // which we should respect
            graphemeFont.setPixelSize( static_cast< int >( std::round( graphemeFont.pixelSize() * SUPERSCRIPT_SUBSCRIPT_FONT_SIZE_SCALING_FACTOR ) ) );
          }
          break;
        }
      }
    }
    else
    {
      previousNonSuperSubScriptFont = graphemeFont;
    }
 
    const QFontMetricsF graphemeFontMetrics( graphemeFont );
    graphemeFirstCharHorizontalAdvance = graphemeFontMetrics.horizontalAdvance( QString( graphemes[i].at( 0 ) ) ) / fontScale;
    graphemeFirstCharHorizontalAdvanceWithLetterSpacing = graphemeFontMetrics.horizontalAdvance( graphemes[i].at( 0 ) ) / fontScale + letterSpacing;
    graphemeHorizontalAdvance = graphemeFontMetrics.horizontalAdvance( QString( graphemes[i] ) ) / fontScale;
    characterDescent = graphemeFontMetrics.descent() / fontScale;
    characterHeight = graphemeFontMetrics.height() / fontScale;
 
    qreal wordSpaceFix = qreal( 0.0 );
    if ( graphemes[i] == " "_L1 )
    {
      // word spacing only gets added once at end of consecutive run of spaces, see QTextEngine::shapeText()
      int nxt = i + 1;
      wordSpaceFix = ( nxt < graphemes.count() && graphemes[nxt] != " "_L1 ) ? wordSpacing : qreal( 0.0 );
    }
 
    // this workaround only works for clusters with a single character. Not sure how it should be handled
    // with multi-character clusters.
    if ( graphemes[i].length() == 1 && !qgsDoubleNear( graphemeFirstCharHorizontalAdvance, graphemeFirstCharHorizontalAdvanceWithLetterSpacing ) )
    {
      // word spacing applied when it shouldn't be
      wordSpaceFix -= wordSpacing;
    }
 
    const double charWidth = graphemeHorizontalAdvance + wordSpaceFix;
    characterWidths[i] = charWidth;
    characterHeights[i] = characterHeight;
    characterDescents[i] = characterDescent;
  }
 
  QgsPrecalculatedTextMetrics metrics( graphemes, std::move( characterWidths ), std::move( characterHeights ), std::move( characterDescents ) );
  metrics.setGraphemeFormats( graphemeFormats );
 
  std::unique_ptr< QgsTextRendererUtils::CurvePlacementProperties > placement
    = QgsTextRendererUtils::generateCurvedTextPlacement( metrics, labelBaselineCurve, offsetAlongLine, QgsTextRendererUtils::RespectPainterOrientation, -1, -1, flags, textAnchor );
 
  if ( placement->graphemePlacement.empty() )
    return;
 
  // We may have deliberately skipped over some graphemes during curved text placement (such as zero-width graphemes).
  // So we need to use a hash of the original grapheme index to place generated components in, as there may accordingly
  // be graphemes which don't result in components, and we can't just blindly assume the component array position
  // will match the original grapheme index
  QHash< int, QgsTextRenderer::Component > components;
  components.reserve( placement->graphemePlacement.size() );
  for ( const QgsTextRendererUtils::CurvedGraphemePlacement &grapheme : std::as_const( placement->graphemePlacement ) )
  {
    QgsTextRenderer::Component component;
    component.origin = QPointF( grapheme.x, grapheme.y );
    component.rotation = -grapheme.angle;
 
    QgsTextDocumentMetrics &metrics = graphemeMetrics[grapheme.graphemeIndex];
    const double verticalOffset = metrics.fragmentVerticalOffset( 0, 0, Qgis::TextLayoutMode::Point );
    if ( !qgsDoubleNear( verticalOffset, 0 ) )
    {
      component.origin.rx() += verticalOffset * std::cos( grapheme.angle + M_PI_2 );
      component.origin.ry() += verticalOffset * std::sin( grapheme.angle + M_PI_2 );
    }
 
    components.insert( grapheme.graphemeIndex, component );
  }
 
  if ( format.background().enabled() )
  {
    for ( const QgsTextRendererUtils::CurvedGraphemePlacement &grapheme : std::as_const( placement->graphemePlacement ) )
    {
      const QgsTextDocumentMetrics &metrics = graphemeMetrics.at( grapheme.graphemeIndex );
      const QgsTextRenderer::Component &component = components[grapheme.graphemeIndex];
      drawBackground( context, component, format, metrics, Qgis::TextLayoutMode::Point );
    }
  }
 
  if ( format.buffer().enabled() )
  {
    for ( const QgsTextRendererUtils::CurvedGraphemePlacement &grapheme : std::as_const( placement->graphemePlacement ) )
    {
      const QgsTextDocumentMetrics &metrics = graphemeMetrics.at( grapheme.graphemeIndex );
      const QgsTextRenderer::Component &component = components[grapheme.graphemeIndex];
 
      drawTextInternal( Qgis::TextComponent::Buffer, context, format, component, metrics.document(), metrics, Qgis::TextHorizontalAlignment::Left, Qgis::TextVerticalAlignment::Top, Qgis::TextLayoutMode::Point );
    }
  }
 
  for ( const QgsTextRendererUtils::CurvedGraphemePlacement &grapheme : std::as_const( placement->graphemePlacement ) )
  {
    const QgsTextDocumentMetrics &metrics = graphemeMetrics.at( grapheme.graphemeIndex );
    const QgsTextRenderer::Component &component = components[grapheme.graphemeIndex];
 
    drawTextInternal( Qgis::TextComponent::Text, context, format, component, metrics.document(), metrics, Qgis::TextHorizontalAlignment::Left, Qgis::TextVerticalAlignment::Top, Qgis::TextLayoutMode::Point );
  }
}
 
QgsTextFormat QgsTextRenderer::updateShadowPosition( const QgsTextFormat &format )
{
  if ( !format.shadow().enabled() || format.shadow().shadowPlacement() != QgsTextShadowSettings::ShadowLowest )
    return format;
 
  QgsTextFormat tmpFormat = format;
  if ( tmpFormat.background().enabled() && tmpFormat.background().type() != QgsTextBackgroundSettings::ShapeMarkerSymbol ) // background shadow not compatible with marker symbol backgrounds
  {
    tmpFormat.shadow().setShadowPlacement( QgsTextShadowSettings::ShadowShape );
  }
  else if ( tmpFormat.buffer().enabled() )
  {
    tmpFormat.shadow().setShadowPlacement( QgsTextShadowSettings::ShadowBuffer );
  }
  else
  {
    tmpFormat.shadow().setShadowPlacement( QgsTextShadowSettings::ShadowText );
  }
  return tmpFormat;
}
 
void QgsTextRenderer::drawPart(
  const QRectF &rect, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponent part, bool
)
{
  const QgsTextDocument document = QgsTextDocument::fromTextAndFormat( textLines, format );
  const double fontScale = calculateScaleFactorForFormat( context, format );
  const QgsTextDocumentMetrics metrics = QgsTextDocumentMetrics::calculateMetrics( document, format, context, fontScale );
 
  drawParts( rect, rotation, alignment, Qgis::TextVerticalAlignment::Top, metrics.document(), metrics, context, format, part, Qgis::TextLayoutMode::Rectangle );
}
 
void QgsTextRenderer::drawParts(
  const QRectF &rect,
  double rotation,
  Qgis::TextHorizontalAlignment alignment,
  Qgis::TextVerticalAlignment vAlignment,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  QgsRenderContext &context,
  const QgsTextFormat &format,
  Qgis::TextComponents parts,
  Qgis::TextLayoutMode mode
)
{
  if ( !context.painter() )
  {
    return;
  }
 
  Component component;
  component.dpiRatio = 1.0;
  component.origin = rect.topLeft();
  component.rotation = rotation;
  component.size = rect.size();
  component.hAlign = alignment;
 
  if ( ( parts & Qgis::TextComponent::Background ) && format.background().enabled() )
  {
    Component backgroundComponent = component;
    if ( !qgsDoubleNear( rotation, 0.0 ) )
    {
      // get rotated label's center point
 
      double xc = rect.width() / 2.0;
      double yc = rect.height() / 2.0;
 
      double angle = -rotation;
      double xd = xc * std::cos( angle ) - yc * std::sin( angle );
      double yd = xc * std::sin( angle ) + yc * std::cos( angle );
 
      backgroundComponent.center = QPointF( backgroundComponent.origin.x() + xd, backgroundComponent.origin.y() + yd );
    }
    else
    {
      backgroundComponent.center = rect.center();
    }
 
    switch ( vAlignment )
    {
      case Qgis::TextVerticalAlignment::Top:
        break;
      case Qgis::TextVerticalAlignment::VerticalCenter:
        backgroundComponent.origin.ry() += ( rect.height() - metrics.documentSize( mode, format.orientation() ).height() ) / 2;
        break;
      case Qgis::TextVerticalAlignment::Bottom:
        backgroundComponent.origin.ry() += ( rect.height() - metrics.documentSize( mode, format.orientation() ).height() );
        break;
    }
 
    QgsTextRenderer::drawBackground( context, backgroundComponent, format, metrics, Qgis::TextLayoutMode::Rectangle );
  }
 
  if ( parts == Qgis::TextComponents( Qgis::TextComponent::Buffer ) && !format.buffer().enabled() )
  {
    return;
  }
 
  if ( parts & Qgis::TextComponent::Buffer || parts & Qgis::TextComponent::Text || parts & Qgis::TextComponent::Shadow )
  {
    drawTextInternal( parts, context, format, component, document, metrics, alignment, vAlignment, mode );
  }
}
 
void QgsTextRenderer::drawPart(
  QPointF origin, double rotation, Qgis::TextHorizontalAlignment alignment, const QStringList &textLines, QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponent part, bool
)
{
  const QgsTextDocument document = QgsTextDocument::fromTextAndFormat( textLines, format );
  const double fontScale = calculateScaleFactorForFormat( context, format );
  const QgsTextDocumentMetrics metrics = QgsTextDocumentMetrics::calculateMetrics( document, format, context, fontScale );
 
  drawParts( origin, rotation, alignment, metrics.document(), metrics, context, format, part, Qgis::TextLayoutMode::Point );
}
 
void QgsTextRenderer::drawParts(
  QPointF origin,
  double rotation,
  Qgis::TextHorizontalAlignment alignment,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  QgsRenderContext &context,
  const QgsTextFormat &format,
  Qgis::TextComponents parts,
  Qgis::TextLayoutMode mode
)
{
  if ( !context.painter() )
  {
    return;
  }
 
  Component component;
  component.dpiRatio = 1.0;
  component.origin = origin;
  component.rotation = rotation;
  component.hAlign = alignment;
 
  if ( ( parts & Qgis::TextComponent::Background ) && format.background().enabled() )
  {
    QgsTextRenderer::drawBackground( context, component, format, metrics, mode );
  }
 
  if ( parts == Qgis::TextComponents( Qgis::TextComponent::Buffer ) && !format.buffer().enabled() )
  {
    return;
  }
 
  if ( parts & Qgis::TextComponent::Buffer || parts & Qgis::TextComponent::Text || parts & Qgis::TextComponent::Shadow )
  {
    drawTextInternal( parts, context, format, component, document, metrics, alignment, Qgis::TextVerticalAlignment::Top, mode );
  }
}
 
QFontMetricsF QgsTextRenderer::fontMetrics( QgsRenderContext &context, const QgsTextFormat &format, const double scaleFactor )
{
  return QFontMetricsF( format.scaledFont( context, scaleFactor ), context.painter() ? context.painter()->device() : nullptr );
}
 
double QgsTextRenderer::drawBuffer( QgsRenderContext &context, const QgsTextRenderer::Component &component, const QgsTextFormat &format, const QgsTextDocumentMetrics &metrics, Qgis::TextLayoutMode mode )
{
  QPainter *p = context.painter();
 
  Qgis::TextOrientation orientation = format.orientation();
  if ( format.orientation() == Qgis::TextOrientation::RotationBased )
  {
    if ( component.rotation >= -315 && component.rotation < -90 )
    {
      orientation = Qgis::TextOrientation::Vertical;
    }
    else if ( component.rotation >= -90 && component.rotation < -45 )
    {
      orientation = Qgis::TextOrientation::Vertical;
    }
    else
    {
      orientation = Qgis::TextOrientation::Horizontal;
    }
  }
 
  QgsTextBufferSettings buffer = format.buffer();
 
  const double penSize = buffer.sizeUnit() == Qgis::RenderUnit::Percentage ? context.convertToPainterUnits( format.size(), format.sizeUnit(), format.sizeMapUnitScale() ) * buffer.size() / 100
                                                                           : context.convertToPainterUnits( buffer.size(), buffer.sizeUnit(), buffer.sizeMapUnitScale() );
 
  const double scaleFactor = calculateScaleFactorForFormat( context, format );
 
  std::optional< QgsScopedRenderContextReferenceScaleOverride > referenceScaleOverride;
  if ( mode == Qgis::TextLayoutMode::Labeling )
  {
    // label size has already been calculated using any symbology reference scale factor -- we need
    // to temporarily remove the reference scale here or we'll be applying the scaling twice
    referenceScaleOverride.emplace( QgsScopedRenderContextReferenceScaleOverride( context, -1.0 ) );
  }
 
  if ( metrics.isNullFontSize() )
    return 0;
 
  referenceScaleOverride.reset();
 
  QPainterPath path;
  path.setFillRule( Qt::WindingFill );
  double advance = 0;
  double height = component.size.height();
  switch ( orientation )
  {
    case Qgis::TextOrientation::Horizontal:
    {
      // NOT SUPPORTED BY THIS METHOD ANYMORE -- buffer drawing is handled in drawTextInternalHorizontal since QGIS 3.42
      break;
    }
 
    case Qgis::TextOrientation::Vertical:
    case Qgis::TextOrientation::RotationBased:
    {
      double partYOffset = component.offset.y() * scaleFactor;
 
      const double blockMaximumCharacterWidth = metrics.blockMaximumCharacterWidth( component.blockIndex );
      double partLastDescent = 0;
 
      int fragmentIndex = 0;
      for ( const QgsTextFragment &fragment : component.block )
      {
        const QFont fragmentFont = metrics.fragmentFont( component.blockIndex, component.firstFragmentIndex + fragmentIndex );
        const double letterSpacing = fragmentFont.letterSpacing() / scaleFactor;
 
        const QFontMetricsF fragmentMetrics( fragmentFont );
 
        const double fragmentYOffset = metrics.fragmentVerticalOffset( component.blockIndex, fragmentIndex, mode );
 
        const QStringList parts = QgsPalLabeling::splitToGraphemes( fragment.text() );
        for ( const QString &part : parts )
        {
          double partXOffset = ( blockMaximumCharacterWidth - ( fragmentMetrics.horizontalAdvance( part ) / scaleFactor - letterSpacing ) ) / 2;
          partYOffset += fragmentMetrics.ascent() / scaleFactor;
          path.addText( partXOffset, partYOffset + fragmentYOffset, fragmentFont, part );
          partYOffset += letterSpacing;
        }
        partLastDescent = fragmentMetrics.descent() / scaleFactor;
 
        fragmentIndex++;
      }
      height = partYOffset + partLastDescent;
      advance = partYOffset - component.offset.y() * scaleFactor;
      break;
    }
  }
 
  QColor bufferColor = buffer.color();
  bufferColor.setAlphaF( buffer.opacity() );
  QPen pen( bufferColor );
  pen.setWidthF( penSize * scaleFactor );
  pen.setJoinStyle( buffer.joinStyle() );
  QColor tmpColor( bufferColor );
  // honor pref for whether to fill buffer interior
  if ( !buffer.fillBufferInterior() )
  {
    tmpColor.setAlpha( 0 );
  }
 
  // store buffer's drawing in QPicture for drop shadow call
  QPicture buffPict;
  QPainter buffp;
  buffp.begin( &buffPict );
  if ( buffer.paintEffect() && buffer.paintEffect()->enabled() )
  {
    context.setPainter( &buffp );
    std::unique_ptr< QgsPaintEffect > tmpEffect( buffer.paintEffect()->clone() );
 
    tmpEffect->begin( context );
    context.painter()->setPen( pen );
    context.painter()->setBrush( tmpColor );
    if ( scaleFactor != 1.0 )
      context.painter()->scale( 1 / scaleFactor, 1 / scaleFactor );
    context.painter()->drawPath( path );
    if ( scaleFactor != 1.0 )
      context.painter()->scale( scaleFactor, scaleFactor );
    tmpEffect->end( context );
 
    context.setPainter( p );
  }
  else
  {
    if ( scaleFactor != 1.0 )
      buffp.scale( 1 / scaleFactor, 1 / scaleFactor );
    buffp.setPen( pen );
    buffp.setBrush( tmpColor );
    buffp.drawPath( path );
  }
  buffp.end();
 
  if ( format.shadow().enabled() && format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowBuffer )
  {
    QgsTextRenderer::Component bufferComponent = component;
    bufferComponent.origin = QPointF( 0.0, 0.0 );
    bufferComponent.picture = buffPict;
    bufferComponent.pictureBuffer = penSize / 2.0;
    bufferComponent.size.setHeight( height );
 
    if ( format.orientation() == Qgis::TextOrientation::Vertical || format.orientation() == Qgis::TextOrientation::RotationBased )
    {
      bufferComponent.offset.setY( -bufferComponent.size.height() );
    }
    drawShadow( context, bufferComponent, format );
  }
 
  QgsScopedQPainterState painterState( p );
  context.setPainterFlagsUsingContext( p );
 
  if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
  {
    p->setCompositionMode( buffer.blendMode() );
  }
 
  // scale for any print output or image saving @ specific dpi
  p->scale( component.dpiRatio, component.dpiRatio );
  QgsPainting::applyScaleFixForQPictureDpi( p );
  p->drawPicture( 0, 0, buffPict );
 
  return advance / scaleFactor;
}
 
void QgsTextRenderer::drawMask( QgsRenderContext &context, const QgsTextRenderer::Component &component, const QgsTextFormat &format, const QgsTextDocumentMetrics &metrics, Qgis::TextLayoutMode mode )
{
  QgsTextMaskSettings mask = format.mask();
 
  // the mask is drawn to a side painter
  // or to the main painter for preview
  QPainter *p = context.isGuiPreview() ? context.painter() : context.maskPainter( context.currentMaskId() );
  if ( !p )
    return;
 
  double penSize = mask.sizeUnit() == Qgis::RenderUnit::Percentage ? context.convertToPainterUnits( format.size(), format.sizeUnit(), format.sizeMapUnitScale() ) * mask.size() / 100
                                                                   : context.convertToPainterUnits( mask.size(), mask.sizeUnit(), mask.sizeMapUnitScale() );
 
  // buffer: draw the text with a big pen
  QPainterPath path;
  path.setFillRule( Qt::WindingFill );
 
  const double scaleFactor = calculateScaleFactorForFormat( context, format );
 
  // TODO: vertical text mode was ignored when masking feature was added.
  // Hopefully Oslandia come back and fix this? Hint hint...
 
  std::optional< QgsScopedRenderContextReferenceScaleOverride > referenceScaleOverride;
  if ( mode == Qgis::TextLayoutMode::Labeling )
  {
    // label size has already been calculated using any symbology reference scale factor -- we need
    // to temporarily remove the reference scale here or we'll be applying the scaling twice
    referenceScaleOverride.emplace( QgsScopedRenderContextReferenceScaleOverride( context, -1.0 ) );
  }
 
  if ( metrics.isNullFontSize() )
    return;
 
  referenceScaleOverride.reset();
 
  double xOffset = 0;
  int fragmentIndex = 0;
  for ( const QgsTextFragment &fragment : component.block )
  {
    if ( !fragment.isWhitespace() && !fragment.isImage() )
    {
      const QFont fragmentFont = metrics.fragmentFont( component.blockIndex, fragmentIndex );
 
      const double fragmentYOffset = metrics.fragmentVerticalOffset( component.blockIndex, fragmentIndex, mode );
      path.addText( xOffset, fragmentYOffset, fragmentFont, fragment.text() );
    }
 
    xOffset += metrics.fragmentHorizontalAdvance( component.blockIndex, fragmentIndex, mode ) * scaleFactor;
    fragmentIndex++;
  }
 
  QColor bufferColor( Qt::gray );
  bufferColor.setAlphaF( mask.opacity() );
 
  QPen pen;
  QBrush brush;
  brush.setColor( bufferColor );
  pen.setColor( bufferColor );
  pen.setWidthF( penSize * scaleFactor );
  pen.setJoinStyle( mask.joinStyle() );
 
  QgsScopedQPainterState painterState( p );
  context.setPainterFlagsUsingContext( p );
 
  // scale for any print output or image saving @ specific dpi
  p->scale( component.dpiRatio, component.dpiRatio );
  if ( mask.paintEffect() && mask.paintEffect()->enabled() )
  {
    QgsPainterSwapper swapper( context, p );
    {
      QgsEffectPainter effectPainter( context, mask.paintEffect() );
      if ( scaleFactor != 1.0 )
        context.painter()->scale( 1 / scaleFactor, 1 / scaleFactor );
      context.painter()->setPen( pen );
      context.painter()->setBrush( brush );
      context.painter()->drawPath( path );
      if ( scaleFactor != 1.0 )
        context.painter()->scale( scaleFactor, scaleFactor );
    }
  }
  else
  {
    if ( scaleFactor != 1.0 )
      p->scale( 1 / scaleFactor, 1 / scaleFactor );
    p->setPen( pen );
    p->setBrush( brush );
    p->drawPath( path );
    if ( scaleFactor != 1.0 )
      p->scale( scaleFactor, scaleFactor );
  }
}
 
double QgsTextRenderer::textWidth( const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, QFontMetricsF * )
{
  const QgsTextDocument doc = QgsTextDocument::fromTextAndFormat( textLines, format );
  if ( doc.size() == 0 )
    return 0;
 
  return textWidth( context, format, doc );
}
 
double QgsTextRenderer::textWidth( const QgsRenderContext &context, const QgsTextFormat &format, const QgsTextDocument &document )
{
  //calculate max width of text lines
  const double scaleFactor = calculateScaleFactorForFormat( context, format );
 
  const QgsTextDocumentMetrics metrics = QgsTextDocumentMetrics::calculateMetrics( document, format, context, scaleFactor );
 
  // width doesn't change depending on layout mode, we can use anything here
  return metrics.documentSize( Qgis::TextLayoutMode::Point, format.orientation() ).width();
}
 
double QgsTextRenderer::textHeight(
  const QgsRenderContext &context, const QgsTextFormat &format, const QStringList &textLines, Qgis::TextLayoutMode mode, QFontMetricsF *, Qgis::TextRendererFlags flags, double maxLineWidth
)
{
  QStringList lines;
  for ( const QString &line : textLines )
  {
    if ( flags & Qgis::TextRendererFlag::WrapLines && maxLineWidth > 0 && textRequiresWrapping( context, line, maxLineWidth, format ) )
    {
      lines.append( wrappedText( context, line, maxLineWidth, format ) );
    }
    else
    {
      lines.append( line );
    }
  }
 
  const QgsTextDocument doc = QgsTextDocument::fromTextAndFormat( lines, format );
  return textHeight( context, format, doc, mode );
}
 
double QgsTextRenderer::textHeight( const QgsRenderContext &context, const QgsTextFormat &format, QChar character, bool includeEffects )
{
  const double scaleFactor = calculateScaleFactorForFormat( context, format );
 
  bool isNullSize = false;
  const QFont baseFont = format.scaledFont( context, scaleFactor, &isNullSize );
  if ( isNullSize )
    return 0;
 
  const QFontMetrics fm( baseFont );
  const double height = ( character.isNull() ? fm.height() : fm.boundingRect( character ).height() ) / scaleFactor;
 
  if ( !includeEffects )
    return height;
 
  double maxExtension = 0;
  const double fontSize = context.convertToPainterUnits( format.size(), format.sizeUnit(), format.sizeMapUnitScale() );
  if ( format.buffer().enabled() )
  {
    maxExtension += format.buffer().sizeUnit() == Qgis::RenderUnit::Percentage ? fontSize * format.buffer().size() / 100
                                                                               : context.convertToPainterUnits( format.buffer().size(), format.buffer().sizeUnit(), format.buffer().sizeMapUnitScale() );
  }
  if ( format.shadow().enabled() )
  {
    maxExtension += ( format.shadow().offsetUnit() == Qgis::RenderUnit::Percentage
                      ? fontSize * format.shadow().offsetDistance() / 100
                      : context.convertToPainterUnits( format.shadow().offsetDistance(), format.shadow().offsetUnit(), format.shadow().offsetMapUnitScale() )
                    )
                    + ( format.shadow().blurRadiusUnit() == Qgis::RenderUnit::Percentage
                        ? fontSize * format.shadow().blurRadius() / 100
                        : context.convertToPainterUnits( format.shadow().blurRadius(), format.shadow().blurRadiusUnit(), format.shadow().blurRadiusMapUnitScale() )
                      );
  }
  if ( format.background().enabled() )
  {
    maxExtension += context.convertToPainterUnits( std::fabs( format.background().offset().y() ), format.background().offsetUnit(), format.background().offsetMapUnitScale() )
                    + context.convertToPainterUnits( format.background().strokeWidth(), format.background().strokeWidthUnit(), format.background().strokeWidthMapUnitScale() ) / 2.0;
    if ( format.background().sizeType() == QgsTextBackgroundSettings::SizeBuffer && format.background().size().height() > 0 )
    {
      maxExtension += context.convertToPainterUnits( format.background().size().height(), format.background().sizeUnit(), format.background().sizeMapUnitScale() );
    }
  }
 
  return height + maxExtension;
}
 
bool QgsTextRenderer::textRequiresWrapping( const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format )
{
  if ( qgsDoubleNear( width, 0.0 ) )
    return false;
 
  const QStringList multiLineSplit = text.split( '\n' );
  const double currentTextWidth = QgsTextRenderer::textWidth( context, format, multiLineSplit );
  return currentTextWidth > width;
}
 
QStringList QgsTextRenderer::wrappedText( const QgsRenderContext &context, const QString &text, double width, const QgsTextFormat &format )
{
  const QStringList lines = text.split( '\n' );
  QStringList outLines;
  for ( const QString &line : lines )
  {
    if ( textRequiresWrapping( context, line, width, format ) )
    {
      //first step is to identify words which must be on their own line (too long to fit)
      const QStringList words = line.split( ' ' );
      QStringList linesToProcess;
      QString wordsInCurrentLine;
      for ( const QString &word : words )
      {
        if ( textRequiresWrapping( context, word, width, format ) )
        {
          //too long to fit
          if ( !wordsInCurrentLine.isEmpty() )
            linesToProcess << wordsInCurrentLine;
          wordsInCurrentLine.clear();
          linesToProcess << word;
        }
        else
        {
          if ( !wordsInCurrentLine.isEmpty() )
            wordsInCurrentLine.append( ' ' );
          wordsInCurrentLine.append( word );
        }
      }
      if ( !wordsInCurrentLine.isEmpty() )
        linesToProcess << wordsInCurrentLine;
 
      for ( const QString &line : std::as_const( linesToProcess ) )
      {
        QString remainingText = line;
        int lastPos = remainingText.lastIndexOf( ' ' );
        while ( lastPos > -1 )
        {
          //check if remaining text is short enough to go in one line
          if ( !textRequiresWrapping( context, remainingText, width, format ) )
          {
            break;
          }
 
          if ( !textRequiresWrapping( context, remainingText.left( lastPos ), width, format ) )
          {
            outLines << remainingText.left( lastPos );
            remainingText = remainingText.mid( lastPos + 1 );
            lastPos = 0;
          }
          lastPos = remainingText.lastIndexOf( ' ', lastPos - 1 );
        }
        outLines << remainingText;
      }
    }
    else
    {
      outLines << line;
    }
  }
 
  return outLines;
}
 
double QgsTextRenderer::textHeight( const QgsRenderContext &context, const QgsTextFormat &format, const QgsTextDocument &doc, Qgis::TextLayoutMode mode )
{
  QgsTextDocument document = doc;
  document.applyCapitalization( format.capitalization() );
 
  //calculate max height of text lines
  const double scaleFactor = calculateScaleFactorForFormat( context, format );
 
  const QgsTextDocumentMetrics metrics = QgsTextDocumentMetrics::calculateMetrics( document, format, context, scaleFactor );
  if ( metrics.isNullFontSize() )
    return 0;
 
  return metrics.documentSize( mode, format.orientation() ).height();
}
 
void QgsTextRenderer::drawBackground( QgsRenderContext &context, const QgsTextRenderer::Component &c, const QgsTextFormat &format, const QgsTextDocumentMetrics &metrics, Qgis::TextLayoutMode mode )
{
  Component component = c;
  QgsTextBackgroundSettings background = format.background();
 
  QPainter *prevP = context.painter();
  QPainter *p = context.painter();
  std::unique_ptr< QgsPaintEffect > tmpEffect;
  if ( background.paintEffect() && background.paintEffect()->enabled() )
  {
    tmpEffect.reset( background.paintEffect()->clone() );
    tmpEffect->begin( context );
    p = context.painter();
  }
 
  //QgsDebugMsgLevel( u"Background label rotation: %1"_s.arg( component.rotation() ), 4 );
 
  // shared calculations between shapes and SVG
 
  // configure angles, set component rotation and rotationOffset
  const double originAdjustRotationRadians = -component.rotation;
  if ( background.rotationType() != QgsTextBackgroundSettings::RotationFixed )
  {
    component.rotation = -( component.rotation * 180 / M_PI ); // RotationSync
    component.rotationOffset = background.rotationType() == QgsTextBackgroundSettings::RotationOffset ? background.rotation() : 0.0;
  }
  else // RotationFixed
  {
    component.rotation = 0.0; // don't use label's rotation
    component.rotationOffset = background.rotation();
  }
 
  const double scaleFactor = calculateScaleFactorForFormat( context, format );
 
  if ( mode != Qgis::TextLayoutMode::Labeling )
  {
    // need to calculate size of text
    const QSizeF documentSize = metrics.documentSize( mode, format.orientation() );
    double width = documentSize.width();
    double height = documentSize.height();
 
    switch ( mode )
    {
      case Qgis::TextLayoutMode::Rectangle:
      case Qgis::TextLayoutMode::RectangleCapHeightBased:
      case Qgis::TextLayoutMode::RectangleAscentBased:
        switch ( component.hAlign )
        {
          case Qgis::TextHorizontalAlignment::Left:
          case Qgis::TextHorizontalAlignment::Justify:
            component.center = QPointF( component.origin.x() + width / 2.0, component.origin.y() + height / 2.0 );
            break;
 
          case Qgis::TextHorizontalAlignment::Center:
            component.center = QPointF( component.origin.x() + component.size.width() / 2.0, component.origin.y() + height / 2.0 );
            break;
 
          case Qgis::TextHorizontalAlignment::Right:
            component.center = QPointF( component.origin.x() + component.size.width() - width / 2.0, component.origin.y() + height / 2.0 );
            break;
        }
        break;
 
      case Qgis::TextLayoutMode::Point:
      {
        bool isNullSize = false;
        QFontMetricsF fm( format.scaledFont( context, scaleFactor, &isNullSize ) );
        double originAdjust = isNullSize ? 0 : ( fm.ascent() / scaleFactor / 2.0 - fm.leading() / scaleFactor / 2.0 );
        switch ( component.hAlign )
        {
          case Qgis::TextHorizontalAlignment::Left:
          case Qgis::TextHorizontalAlignment::Justify:
            component.center = QPointF( component.origin.x() + width / 2.0, component.origin.y() - height / 2.0 + originAdjust );
            break;
 
          case Qgis::TextHorizontalAlignment::Center:
            component.center = QPointF( component.origin.x(), component.origin.y() - height / 2.0 + originAdjust );
            break;
 
          case Qgis::TextHorizontalAlignment::Right:
            component.center = QPointF( component.origin.x() - width / 2.0, component.origin.y() - height / 2.0 + originAdjust );
            break;
        }
 
        // apply rotation to center point
        if ( !qgsDoubleNear( originAdjustRotationRadians, 0 ) )
        {
          const double dx = component.center.x() - component.origin.x();
          const double dy = component.center.y() - component.origin.y();
          component.center.setX( component.origin.x() + ( std::cos( originAdjustRotationRadians ) * dx - std::sin( originAdjustRotationRadians ) * dy ) );
          component.center.setY( component.origin.y() + ( std::sin( originAdjustRotationRadians ) * dx + std::cos( originAdjustRotationRadians ) * dy ) );
        }
        break;
      }
 
      case Qgis::TextLayoutMode::Labeling:
        break;
    }
 
    if ( format.background().sizeType() != QgsTextBackgroundSettings::SizeFixed )
      component.size = QSizeF( width, height );
  }
 
  // TODO: the following label-buffered generated shapes and SVG symbols should be moved into marker symbology classes
 
  switch ( background.type() )
  {
    case QgsTextBackgroundSettings::ShapeSVG:
    case QgsTextBackgroundSettings::ShapeMarkerSymbol:
    {
      // all calculations done in shapeSizeUnits, which are then passed to symbology class for painting
 
      if ( background.type() == QgsTextBackgroundSettings::ShapeSVG && background.svgFile().isEmpty() )
        return;
 
      if ( background.type() == QgsTextBackgroundSettings::ShapeMarkerSymbol && !background.markerSymbol() )
        return;
 
      double sizeOut = 0.0;
      {
        QgsScopedRenderContextReferenceScaleOverride referenceScaleOverride( context, -1 );
 
        // only one size used for SVG/marker symbol sizing/scaling (no use of shapeSize.y() or Y field in gui)
        if ( background.sizeType() == QgsTextBackgroundSettings::SizeFixed )
        {
          sizeOut = context.convertToPainterUnits( background.size().width(), background.sizeUnit(), background.sizeMapUnitScale() );
        }
        else if ( background.sizeType() == QgsTextBackgroundSettings::SizeBuffer )
        {
          sizeOut = std::max( component.size.width(), component.size.height() );
          double bufferSize = context.convertToPainterUnits( background.size().width(), background.sizeUnit(), background.sizeMapUnitScale() );
 
          // add buffer
          sizeOut += bufferSize * 2;
        }
      }
 
      // don't bother rendering symbols smaller than 1x1 pixels in size
      // TODO: add option to not show any svgs under/over a certain size
      if ( sizeOut < 1.0 )
        return;
 
      std::unique_ptr< QgsMarkerSymbol > renderedSymbol;
      if ( background.type() == QgsTextBackgroundSettings::ShapeSVG )
      {
        QVariantMap map; // for SVG symbology marker
        map[u"name"_s] = background.svgFile().trimmed();
        map[u"size"_s] = QString::number( sizeOut );
        map[u"size_unit"_s] = QgsUnitTypes::encodeUnit( Qgis::RenderUnit::Pixels );
        map[u"angle"_s] = QString::number( 0.0 ); // angle is handled by this local painter
 
        // offset is handled by this local painter
        // TODO: see why the marker renderer doesn't seem to translate offset *after* applying rotation
        //map["offset"] = QgsSymbolLayerUtils::encodePoint( tmpLyr.shapeOffset );
        //map["offset_unit"] = QgsUnitTypes::encodeUnit(
        //                       tmpLyr.shapeOffsetUnits == QgsPalLayerSettings::MapUnits ? QgsUnitTypes::MapUnit : QgsUnitTypes::MM );
 
        map[u"fill"_s] = background.fillColor().name();
        map[u"outline"_s] = background.strokeColor().name();
        map[u"outline-width"_s] = QString::number( background.strokeWidth() );
        map[u"outline_width_unit"_s] = QgsUnitTypes::encodeUnit( background.strokeWidthUnit() );
 
        if ( format.shadow().enabled() && format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowShape )
        {
          QgsTextShadowSettings shadow = format.shadow();
          // configure SVG shadow specs
          QVariantMap shdwmap( map );
          shdwmap[u"fill"_s] = shadow.color().name();
          shdwmap[u"outline"_s] = shadow.color().name();
          shdwmap[u"size"_s] = QString::number( sizeOut );
 
          // store SVG's drawing in QPicture for drop shadow call
          QPicture svgPict;
          QPainter svgp;
          svgp.begin( &svgPict );
 
          // draw shadow symbol
 
          // clone current render context map unit/mm conversion factors, but not
          // other map canvas parameters, then substitute this painter for use in symbology painting
          // NOTE: this is because the shadow needs to be scaled correctly for output to map canvas,
          //       but will be created relative to the SVG's computed size, not the current map canvas
          QgsRenderContext shdwContext;
          shdwContext.setMapToPixel( context.mapToPixel() );
          shdwContext.setScaleFactor( context.scaleFactor() );
          shdwContext.setPainter( &svgp );
 
          std::unique_ptr< QgsSymbolLayer > symShdwL( QgsSvgMarkerSymbolLayer::create( shdwmap ) );
          QgsSvgMarkerSymbolLayer *svgShdwM = static_cast<QgsSvgMarkerSymbolLayer *>( symShdwL.get() );
          QgsSymbolRenderContext svgShdwContext( shdwContext, Qgis::RenderUnit::Unknown, background.opacity() );
 
          svgShdwM->renderPoint( QPointF( sizeOut / 2, -sizeOut / 2 ), svgShdwContext );
          svgp.end();
 
          component.picture = svgPict;
          // TODO: when SVG symbol's stroke width/units is fixed in QgsSvgCache, adjust for it here
          component.pictureBuffer = 0.0;
 
          component.size = QSizeF( sizeOut, sizeOut );
          component.offset = QPointF( 0.0, 0.0 );
 
          // rotate about origin center of SVG
          QgsScopedQPainterState painterState( p );
          context.setPainterFlagsUsingContext( p );
 
          p->translate( component.center.x(), component.center.y() );
          p->rotate( component.rotation );
          double xoff = context.convertToPainterUnits( background.offset().x(), background.offsetUnit(), background.offsetMapUnitScale() );
          double yoff = context.convertToPainterUnits( background.offset().y(), background.offsetUnit(), background.offsetMapUnitScale() );
          p->translate( QPointF( xoff, yoff ) );
          p->rotate( component.rotationOffset );
          p->translate( -sizeOut / 2, sizeOut / 2 );
 
          drawShadow( context, component, format );
        }
        renderedSymbol.reset();
 
        QgsSymbolLayer *symL = QgsSvgMarkerSymbolLayer::create( map );
        renderedSymbol = std::make_unique<QgsMarkerSymbol>( QgsSymbolLayerList() << symL );
      }
      else
      {
        renderedSymbol.reset( background.markerSymbol()->clone() );
        renderedSymbol->setSize( sizeOut );
        renderedSymbol->setSizeUnit( Qgis::RenderUnit::Pixels );
      }
 
      renderedSymbol->setOpacity( renderedSymbol->opacity() * background.opacity() );
 
      // draw the actual symbol
      QgsScopedQPainterState painterState( p );
      context.setPainterFlagsUsingContext( p );
 
      if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
      {
        p->setCompositionMode( background.blendMode() );
      }
      p->translate( component.center.x(), component.center.y() );
      p->rotate( component.rotation );
      double xoff = context.convertToPainterUnits( background.offset().x(), background.offsetUnit(), background.offsetMapUnitScale() );
      double yoff = context.convertToPainterUnits( background.offset().y(), background.offsetUnit(), background.offsetMapUnitScale() );
      p->translate( QPointF( xoff, yoff ) );
      p->rotate( component.rotationOffset );
 
      const QgsFeature f = context.expressionContext().feature();
      renderedSymbol->startRender( context, context.expressionContext().fields() );
      renderedSymbol->renderPoint( QPointF( 0, 0 ), &f, context );
      renderedSymbol->stopRender( context );
      p->setCompositionMode( QPainter::CompositionMode_SourceOver ); // just to be sure
 
      break;
    }
 
    case QgsTextBackgroundSettings::ShapeRectangle:
    case QgsTextBackgroundSettings::ShapeCircle:
    case QgsTextBackgroundSettings::ShapeSquare:
    case QgsTextBackgroundSettings::ShapeEllipse:
    {
      double w = component.size.width();
      double h = component.size.height();
 
      if ( background.sizeType() == QgsTextBackgroundSettings::SizeFixed )
      {
        w = context.convertToPainterUnits( background.size().width(), background.sizeUnit(), background.sizeMapUnitScale() );
        h = context.convertToPainterUnits( background.size().height(), background.sizeUnit(), background.sizeMapUnitScale() );
      }
      else if ( background.sizeType() == QgsTextBackgroundSettings::SizeBuffer )
      {
        if ( background.type() == QgsTextBackgroundSettings::ShapeSquare )
        {
          if ( w > h )
            h = w;
          else if ( h > w )
            w = h;
        }
        else if ( background.type() == QgsTextBackgroundSettings::ShapeCircle )
        {
          // start with label bound by circle
          h = std::sqrt( std::pow( w, 2 ) + std::pow( h, 2 ) );
          w = h;
        }
        else if ( background.type() == QgsTextBackgroundSettings::ShapeEllipse )
        {
          // start with label bound by ellipse
          h = h * M_SQRT1_2 * 2;
          w = w * M_SQRT1_2 * 2;
        }
 
        double bufferWidth = context.convertToPainterUnits( background.size().width(), background.sizeUnit(), background.sizeMapUnitScale() );
        double bufferHeight = context.convertToPainterUnits( background.size().height(), background.sizeUnit(), background.sizeMapUnitScale() );
 
        w += bufferWidth * 2;
        h += bufferHeight * 2;
      }
 
      // offsets match those of symbology: -x = left, -y = up
      QRectF rect( -w / 2.0, -h / 2.0, w, h );
 
      if ( rect.isNull() )
        return;
 
      QgsScopedQPainterState painterState( p );
      context.setPainterFlagsUsingContext( p );
 
      p->translate( QPointF( component.center.x(), component.center.y() ) );
      p->rotate( component.rotation );
      double xoff = context.convertToPainterUnits( background.offset().x(), background.offsetUnit(), background.offsetMapUnitScale() );
      double yoff = context.convertToPainterUnits( background.offset().y(), background.offsetUnit(), background.offsetMapUnitScale() );
      p->translate( QPointF( xoff, yoff ) );
      p->rotate( component.rotationOffset );
 
      QPainterPath path;
 
      // Paths with curves must be enlarged before conversion to QPolygonF, or
      // the curves are approximated too much and appear jaggy
      QTransform t = QTransform::fromScale( 10, 10 );
      // inverse transform used to scale created polygons back to expected size
      QTransform ti = t.inverted();
 
      if ( background.type() == QgsTextBackgroundSettings::ShapeRectangle || background.type() == QgsTextBackgroundSettings::ShapeSquare )
      {
        if ( background.radiiUnit() == Qgis::RenderUnit::Percentage )
        {
          path.addRoundedRect( rect, background.radii().width(), background.radii().height(), Qt::RelativeSize );
        }
        else
        {
          const double xRadius = context.convertToPainterUnits( background.radii().width(), background.radiiUnit(), background.radiiMapUnitScale() );
          const double yRadius = context.convertToPainterUnits( background.radii().height(), background.radiiUnit(), background.radiiMapUnitScale() );
          path.addRoundedRect( rect, xRadius, yRadius );
        }
      }
      else if ( background.type() == QgsTextBackgroundSettings::ShapeEllipse || background.type() == QgsTextBackgroundSettings::ShapeCircle )
      {
        path.addEllipse( rect );
      }
      QPolygonF tempPolygon = path.toFillPolygon( t );
      QPolygonF polygon = ti.map( tempPolygon );
      QPicture shapePict;
      QPainter *oldp = context.painter();
      QPainter shapep;
 
      shapep.begin( &shapePict );
      context.setPainter( &shapep );
 
      std::unique_ptr< QgsFillSymbol > renderedSymbol;
      renderedSymbol.reset( background.fillSymbol()->clone() );
      renderedSymbol->setOpacity( renderedSymbol->opacity() * background.opacity() );
 
      const QgsFeature f = context.expressionContext().feature();
      renderedSymbol->startRender( context, context.expressionContext().fields() );
      renderedSymbol->renderPolygon( polygon, nullptr, &f, context );
      renderedSymbol->stopRender( context );
 
      shapep.end();
      context.setPainter( oldp );
 
      if ( format.shadow().enabled() && format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowShape )
      {
        component.picture = shapePict;
        component.pictureBuffer = QgsSymbolLayerUtils::estimateMaxSymbolBleed( renderedSymbol.get(), context ) * 2;
 
        component.size = rect.size();
        component.offset = QPointF( rect.width() / 2, -rect.height() / 2 );
        drawShadow( context, component, format );
      }
 
      if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
      {
        p->setCompositionMode( background.blendMode() );
      }
 
      // scale for any print output or image saving @ specific dpi
      p->scale( component.dpiRatio, component.dpiRatio );
      QgsPainting::applyScaleFixForQPictureDpi( p );
      p->drawPicture( 0, 0, shapePict );
      p->setCompositionMode( QPainter::CompositionMode_SourceOver ); // just to be sure
      break;
    }
  }
 
  if ( tmpEffect )
  {
    tmpEffect->end( context );
    context.setPainter( prevP );
  }
}
 
void QgsTextRenderer::drawShadow( QgsRenderContext &context, const QgsTextRenderer::Component &component, const QgsTextFormat &format )
{
  QgsTextShadowSettings shadow = format.shadow();
 
  QPainter *p = context.painter();
  const double componentWidth = component.size.width();
  const double componentHeight = component.size.height();
  const double xOffset = component.offset.x();
  const double yOffset = component.offset.y();
  double pictbuffer = component.pictureBuffer;
 
  // generate pixmap representation of label component drawing
  bool mapUnits = shadow.blurRadiusUnit() == Qgis::RenderUnit::MapUnits;
 
  const double fontSize = context.convertToPainterUnits( format.size(), format.sizeUnit(), format.sizeMapUnitScale() );
  double radius = shadow.blurRadiusUnit() == Qgis::RenderUnit::Percentage ? fontSize * shadow.blurRadius() / 100
                                                                          : context.convertToPainterUnits( shadow.blurRadius(), shadow.blurRadiusUnit(), shadow.blurRadiusMapUnitScale() );
  radius /= ( mapUnits ? context.scaleFactor() / component.dpiRatio : 1 );
  radius = static_cast< int >( radius + 0.5 ); //NOLINT
 
  // TODO: add labeling gui option to adjust blurBufferClippingScale to minimize pixels, or
  //       to ensure shadow isn't clipped too tight. (Or, find a better method of buffering)
  double blurBufferClippingScale = 3.75;
  int blurbuffer = ( radius > 17 ? 16 : radius ) * blurBufferClippingScale;
 
  QImage blurImg( componentWidth + ( pictbuffer * 2.0 ) + ( blurbuffer * 2.0 ), componentHeight + ( pictbuffer * 2.0 ) + ( blurbuffer * 2.0 ), QImage::Format_ARGB32_Premultiplied );
 
  // TODO: add labeling gui option to not show any shadows under/over a certain size
  // keep very small QImages from causing paint device issues, i.e. must be at least > 1
  int minBlurImgSize = 1;
  // max limitation on QgsSvgCache is 10,000 for screen, which will probably be reasonable for future caching here, too
  // 4 x QgsSvgCache limit for output to print/image at higher dpi
  // TODO: should it be higher, scale with dpi, or have no limit? Needs testing with very large labels rendered at high dpi output
  int maxBlurImgSize = 40000;
  if ( blurImg.isNull() || ( blurImg.width() < minBlurImgSize || blurImg.height() < minBlurImgSize ) || ( blurImg.width() > maxBlurImgSize || blurImg.height() > maxBlurImgSize ) )
    return;
 
  blurImg.fill( QColor( Qt::transparent ).rgba() );
  QPainter pictp;
  if ( !pictp.begin( &blurImg ) )
    return;
  pictp.setRenderHints( QPainter::Antialiasing | QPainter::SmoothPixmapTransform );
  QPointF imgOffset( blurbuffer + pictbuffer + xOffset, blurbuffer + pictbuffer + componentHeight + yOffset );
 
  pictp.drawPicture( imgOffset, component.picture );
 
  // overlay shadow color
  pictp.setCompositionMode( QPainter::CompositionMode_SourceIn );
  pictp.fillRect( blurImg.rect(), shadow.color() );
  pictp.end();
 
  // blur the QImage in-place
  if ( shadow.blurRadius() > 0.0 && radius > 0 )
  {
    QgsSymbolLayerUtils::blurImageInPlace( blurImg, blurImg.rect(), radius, shadow.blurAlphaOnly() );
  }
 
#if 0
  // debug rect for QImage shadow registration and clipping visualization
  QPainter picti;
  picti.begin( &blurImg );
  picti.setBrush( Qt::Dense7Pattern );
  QPen imgPen( QColor( 0, 0, 255, 255 ) );
  imgPen.setWidth( 1 );
  picti.setPen( imgPen );
  picti.setOpacity( 0.1 );
  picti.drawRect( 0, 0, blurImg.width(), blurImg.height() );
  picti.end();
#endif
 
  const double offsetDist = shadow.offsetUnit() == Qgis::RenderUnit::Percentage ? fontSize * shadow.offsetDistance() / 100
                                                                                : context.convertToPainterUnits( shadow.offsetDistance(), shadow.offsetUnit(), shadow.offsetMapUnitScale() );
  double angleRad = shadow.offsetAngle() * M_PI / 180; // to radians
  if ( shadow.offsetGlobal() )
  {
    // TODO: check for differences in rotation origin and cw/ccw direction,
    //       when this shadow function is used for something other than labels
 
    // it's 0-->cw-->360 for labels
    //QgsDebugMsgLevel( u"Shadow aggregated label rotation (degrees): %1"_s.arg( component.rotation() + component.rotationOffset() ), 4 );
    angleRad -= ( component.rotation * M_PI / 180 + component.rotationOffset * M_PI / 180 );
  }
 
  QPointF transPt( -offsetDist * std::cos( angleRad + M_PI_2 ), -offsetDist * std::sin( angleRad + M_PI_2 ) );
 
  p->save();
  context.setPainterFlagsUsingContext( p );
  // this was historically ALWAYS set for text renderer. We may want to consider getting it to respect the
  // corresponding flag in the render context instead...
  p->setRenderHint( QPainter::SmoothPixmapTransform );
  if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
  {
    p->setCompositionMode( shadow.blendMode() );
  }
  p->setOpacity( shadow.opacity() );
 
  double scale = shadow.scale() / 100.0;
  // TODO: scale from center/center, left/center or left/top, instead of default left/bottom?
  p->scale( scale, scale );
  if ( component.useOrigin )
  {
    p->translate( component.origin.x(), component.origin.y() );
  }
  p->translate( transPt );
  p->translate( -imgOffset.x(), -imgOffset.y() );
  p->drawImage( 0, 0, blurImg );
  p->restore();
 
  // debug rects
#if 0
  // draw debug rect for QImage painting registration
  p->save();
  p->setBrush( Qt::NoBrush );
  QPen imgPen( QColor( 255, 0, 0, 10 ) );
  imgPen.setWidth( 2 );
  imgPen.setStyle( Qt::DashLine );
  p->setPen( imgPen );
  p->scale( scale, scale );
  if ( component.useOrigin() )
  {
    p->translate( component.origin().x(), component.origin().y() );
  }
  p->translate( transPt );
  p->translate( -imgOffset.x(),
                -imgOffset.y() );
  p->drawRect( 0, 0, blurImg.width(), blurImg.height() );
  p->restore();
 
  // draw debug rect for passed in component dimensions
  p->save();
  p->setBrush( Qt::NoBrush );
  QPen componentRectPen( QColor( 0, 255, 0, 70 ) );
  componentRectPen.setWidth( 1 );
  if ( component.useOrigin() )
  {
    p->translate( component.origin().x(), component.origin().y() );
  }
  p->setPen( componentRectPen );
  p->drawRect( QRect( -xOffset, -componentHeight - yOffset, componentWidth, componentHeight ) );
  p->restore();
#endif
}
 
 
void QgsTextRenderer::drawTextInternal(
  Qgis::TextComponents components,
  QgsRenderContext &context,
  const QgsTextFormat &format,
  const Component &component,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  Qgis::TextHorizontalAlignment alignment,
  Qgis::TextVerticalAlignment vAlignment,
  Qgis::TextLayoutMode mode
)
{
  if ( !context.painter() )
  {
    return;
  }
 
  const double fontScale = calculateScaleFactorForFormat( context, format );
 
  std::optional< QgsScopedRenderContextReferenceScaleOverride > referenceScaleOverride;
  if ( mode == Qgis::TextLayoutMode::Labeling )
  {
    // label size has already been calculated using any symbology reference scale factor -- we need
    // to temporarily remove the reference scale here or we'll be applying the scaling twice
    referenceScaleOverride.emplace( QgsScopedRenderContextReferenceScaleOverride( context, -1.0 ) );
  }
 
  if ( metrics.isNullFontSize() )
    return;
 
  referenceScaleOverride.reset();
 
  double rotation = 0;
  const Qgis::TextOrientation orientation = calculateRotationAndOrientationForComponent( format, component, rotation );
  switch ( orientation )
  {
    case Qgis::TextOrientation::Horizontal:
    {
      drawTextInternalHorizontal( context, format, components, mode, component, document, metrics, fontScale, alignment, vAlignment, rotation );
      break;
    }
 
    case Qgis::TextOrientation::Vertical:
    case Qgis::TextOrientation::RotationBased:
    {
      // TODO: vertical text renderer currently doesn't handle one-pass buffer + text drawing
      if ( components & Qgis::TextComponent::Buffer )
        drawTextInternalVertical( context, format, Qgis::TextComponent::Buffer, mode, component, document, metrics, fontScale, alignment, vAlignment, rotation );
      if ( components & Qgis::TextComponent::Text )
        drawTextInternalVertical( context, format, Qgis::TextComponent::Text, mode, component, document, metrics, fontScale, alignment, vAlignment, rotation );
      break;
    }
  }
}
 
Qgis::TextOrientation QgsTextRenderer::calculateRotationAndOrientationForComponent( const QgsTextFormat &format, const QgsTextRenderer::Component &component, double &rotation )
{
  rotation = -component.rotation * 180 / M_PI;
 
  switch ( format.orientation() )
  {
    case Qgis::TextOrientation::RotationBased:
    {
      // Between 45 to 135 and 235 to 315 degrees, rely on vertical orientation
      if ( rotation >= -315 && rotation < -90 )
      {
        rotation -= 90;
        return Qgis::TextOrientation::Vertical;
      }
      else if ( rotation >= -90 && rotation < -45 )
      {
        rotation += 90;
        return Qgis::TextOrientation::Vertical;
      }
 
      return Qgis::TextOrientation::Horizontal;
    }
 
    case Qgis::TextOrientation::Horizontal:
    case Qgis::TextOrientation::Vertical:
      return format.orientation();
  }
  return Qgis::TextOrientation::Horizontal;
}
 
void QgsTextRenderer::calculateExtraSpacingForLineJustification( const double spaceToDistribute, const QgsTextBlock &block, double &extraWordSpace, double &extraLetterSpace )
{
  const QString blockText = block.toPlainText();
  QTextBoundaryFinder finder( QTextBoundaryFinder::Word, blockText );
  finder.toStart();
  int wordBoundaries = 0;
  while ( finder.toNextBoundary() != -1 )
  {
    if ( finder.boundaryReasons() & QTextBoundaryFinder::StartOfItem )
      wordBoundaries++;
  }
 
  if ( wordBoundaries > 0 )
  {
    // word boundaries found => justify by padding word spacing
    extraWordSpace = spaceToDistribute / wordBoundaries;
  }
  else
  {
    // no word boundaries found => justify by letter spacing
    QTextBoundaryFinder finder( QTextBoundaryFinder::Grapheme, blockText );
    finder.toStart();
 
    int graphemeBoundaries = 0;
    while ( finder.toNextBoundary() != -1 )
    {
      if ( finder.boundaryReasons() & QTextBoundaryFinder::StartOfItem )
        graphemeBoundaries++;
    }
 
    if ( graphemeBoundaries > 0 )
    {
      extraLetterSpace = spaceToDistribute / graphemeBoundaries;
    }
  }
}
 
void QgsTextRenderer::applyExtraSpacingForLineJustification( QFont &font, double extraWordSpace, double extraLetterSpace )
{
  const double prevWordSpace = font.wordSpacing();
  font.setWordSpacing( prevWordSpace + extraWordSpace );
  const double prevLetterSpace = font.letterSpacing();
  font.setLetterSpacing( QFont::AbsoluteSpacing, prevLetterSpace + extraLetterSpace );
}
 
 
void QgsTextRenderer::renderBlockHorizontal(
  const QgsTextBlock &block,
  int blockIndex,
  const QgsTextDocumentMetrics &metrics,
  QgsRenderContext &context,
  const QgsTextFormat &format,
  QPainter *painter,
  bool forceRenderAsPaths,
  double fontScale,
  double extraWordSpace,
  double extraLetterSpace,
  Qgis::TextLayoutMode mode,
  DeferredRenderBlock *deferredRenderBlock
)
{
  if ( !metrics.isNullFontSize() )
  {
    double xOffset = 0;
    int fragmentIndex = 0;
    for ( const QgsTextFragment &fragment : block )
    {
      // draw text, QPainterPath method
      if ( !fragment.isWhitespace() && !fragment.isImage() )
      {
        QFont fragmentFont = metrics.fragmentFont( blockIndex, fragmentIndex );
 
        if ( !qgsDoubleNear( extraWordSpace, 0 ) || !qgsDoubleNear( extraLetterSpace, 0 ) )
          applyExtraSpacingForLineJustification( fragmentFont, extraWordSpace * fontScale, extraLetterSpace * fontScale );
 
        const double yOffset = metrics.fragmentVerticalOffset( blockIndex, fragmentIndex, mode );
 
        QColor textColor = fragment.characterFormat().textColor().isValid() ? fragment.characterFormat().textColor() : format.color();
        textColor.setAlphaF( fragment.characterFormat().textColor().isValid() ? textColor.alphaF() * format.opacity() : format.opacity() );
 
        if ( deferredRenderBlock )
        {
          DeferredRenderFragment renderFragment;
          renderFragment.color = textColor;
          if ( forceRenderAsPaths )
          {
            renderFragment.path.setFillRule( Qt::WindingFill );
            renderFragment.path.addText( xOffset, yOffset, fragmentFont, fragment.text() );
          }
          renderFragment.font = fragmentFont;
          renderFragment.point = QPointF( xOffset, yOffset );
          renderFragment.text = fragment.text();
          deferredRenderBlock->fragments.append( renderFragment );
        }
        else if ( forceRenderAsPaths )
        {
          painter->setBrush( textColor );
          QPainterPath path;
          path.setFillRule( Qt::WindingFill );
          path.addText( xOffset, yOffset, fragmentFont, fragment.text() );
          painter->drawPath( path );
        }
        else
        {
          painter->setPen( textColor );
          painter->setFont( fragmentFont );
          painter->drawText( QPointF( xOffset, yOffset ), fragment.text() );
        }
      }
      else if ( fragment.isImage() )
      {
        bool fitsInCache = false;
        const double imageWidth = metrics.fragmentHorizontalAdvance( blockIndex, fragmentIndex, mode ) * fontScale;
        const double imageHeight = metrics.fragmentFixedHeight( blockIndex, fragmentIndex, mode ) * fontScale;
 
        const QImage image = QgsApplication::imageCache()->pathAsImage(
          fragment.characterFormat().imagePath(),
          QSize( static_cast< int >( std::round( imageWidth ) ), static_cast< int >( std::round( imageHeight ) ) ),
          false,
          1,
          fitsInCache,
          context.flags() & Qgis::RenderContextFlag::RenderBlocking
        );
        const double imageBaseline = metrics.fragmentVerticalOffset( blockIndex, fragmentIndex, mode );
        const double yOffset = imageBaseline - image.height();
        if ( !image.isNull() )
          painter->drawImage( QPointF( xOffset, yOffset ), image );
      }
 
      xOffset += metrics.fragmentHorizontalAdvance( blockIndex, fragmentIndex, mode ) * fontScale;
      fragmentIndex++;
    }
  }
};
 
bool QgsTextRenderer::usePathsToRender( const QgsRenderContext &context, const QgsTextFormat &format, const QgsTextDocument &document )
{
  switch ( context.textRenderFormat() )
  {
    case Qgis::TextRenderFormat::AlwaysOutlines:
      return true;
    case Qgis::TextRenderFormat::AlwaysText:
      return false;
    case Qgis::TextRenderFormat::PreferText:
    {
      // Prefer not to use paths -- but certain conditions will require us to use them
      if ( format.buffer().enabled() )
      {
        // text buffer requires use of paths
        // TODO: this was the original cause of use switching from text to paths by default,
        // but that was way back in the 2.0 days and maybe the Qt issues have now been fixed?
        return true;
      }
 
      // underline/overline/strikethrough looks different between path/non-path renders.
      // TODO: validate which is correct. For now, maintain default appearance from before this code
      // was introduced
      if ( format.font().underline() || format.font().overline() || format.font().strikeOut() || std::any_of( document.begin(), document.end(), []( const QgsTextBlock &block ) {
             return std::any_of( block.begin(), block.end(), []( const QgsTextFragment &fragment ) {
               return fragment.characterFormat().underline() == QgsTextCharacterFormat::BooleanValue::SetTrue
                      || fragment.characterFormat().overline() == QgsTextCharacterFormat::BooleanValue::SetTrue
                      || fragment.characterFormat().strikeOut() == QgsTextCharacterFormat::BooleanValue::SetTrue;
             } );
           } ) )
        return true;
 
      return false;
    }
  }
  BUILTIN_UNREACHABLE
}
 
bool QgsTextRenderer::usePictureToRender( const QgsRenderContext &, const QgsTextFormat &, const QgsTextDocument &document )
{
  return std::any_of( document.begin(), document.end(), []( const QgsTextBlock &block ) {
    return std::any_of( block.begin(), block.end(), []( const QgsTextFragment &fragment ) { return fragment.isImage(); } );
  } );
}
 
QVector< QgsTextRenderer::BlockMetrics > QgsTextRenderer::calculateBlockMetrics(
  const QgsTextDocument &document, const QgsTextDocumentMetrics &metrics, Qgis::TextLayoutMode mode, double targetWidth, const Qgis::TextHorizontalAlignment hAlignment
)
{
  QVector< BlockMetrics > blockMetrics;
  blockMetrics.reserve( document.size() );
 
  int blockIndex = 0;
  for ( const QgsTextBlock &block : document )
  {
    Qgis::TextHorizontalAlignment blockAlignment = hAlignment;
    if ( block.blockFormat().hasHorizontalAlignmentSet() )
      blockAlignment = block.blockFormat().horizontalAlignment();
    const bool adjustForAlignment = blockAlignment != Qgis::TextHorizontalAlignment::Left && ( mode != Qgis::TextLayoutMode::Labeling || document.size() > 1 );
 
    const bool isFinalLineInParagraph = ( blockIndex == document.size() - 1 ) || document.at( blockIndex + 1 ).toPlainText().trimmed().isEmpty();
 
    BlockMetrics thisBlockMetrics;
    // figure x offset for horizontal alignment of multiple lines
    thisBlockMetrics.width = metrics.blockWidth( blockIndex );
 
    if ( adjustForAlignment )
    {
      double blockWidthDiff = 0;
      switch ( blockAlignment )
      {
        case Qgis::TextHorizontalAlignment::Center:
          blockWidthDiff = ( targetWidth - thisBlockMetrics.width - metrics.blockLeftMargin( blockIndex ) - metrics.blockRightMargin( blockIndex ) ) * 0.5 + metrics.blockLeftMargin( blockIndex );
          break;
 
        case Qgis::TextHorizontalAlignment::Right:
          blockWidthDiff = targetWidth - thisBlockMetrics.width - metrics.blockRightMargin( blockIndex );
          break;
 
        case Qgis::TextHorizontalAlignment::Justify:
          if ( !isFinalLineInParagraph && targetWidth > thisBlockMetrics.width )
          {
            calculateExtraSpacingForLineJustification( targetWidth - thisBlockMetrics.width, block, thisBlockMetrics.extraWordSpace, thisBlockMetrics.extraLetterSpace );
            thisBlockMetrics.width = targetWidth;
          }
          blockWidthDiff = metrics.blockLeftMargin( blockIndex );
          break;
 
        case Qgis::TextHorizontalAlignment::Left:
          blockWidthDiff = metrics.blockLeftMargin( blockIndex );
          break;
      }
 
      switch ( mode )
      {
        case Qgis::TextLayoutMode::Labeling:
        case Qgis::TextLayoutMode::Rectangle:
        case Qgis::TextLayoutMode::RectangleCapHeightBased:
        case Qgis::TextLayoutMode::RectangleAscentBased:
          thisBlockMetrics.xOffset = blockWidthDiff;
          break;
 
        case Qgis::TextLayoutMode::Point:
        {
          switch ( blockAlignment )
          {
            case Qgis::TextHorizontalAlignment::Right:
              thisBlockMetrics.xOffset = blockWidthDiff - targetWidth;
              break;
 
            case Qgis::TextHorizontalAlignment::Center:
              thisBlockMetrics.xOffset = blockWidthDiff - targetWidth / 2.0;
              break;
 
            case Qgis::TextHorizontalAlignment::Left:
            case Qgis::TextHorizontalAlignment::Justify:
              thisBlockMetrics.xOffset = metrics.blockLeftMargin( blockIndex );
              break;
          }
        }
        break;
      }
    }
    else if ( blockAlignment == Qgis::TextHorizontalAlignment::Left || blockAlignment == Qgis::TextHorizontalAlignment::Justify )
    {
      thisBlockMetrics.xOffset = metrics.blockLeftMargin( blockIndex );
    }
 
    switch ( mode )
    {
      case Qgis::TextLayoutMode::Rectangle:
      case Qgis::TextLayoutMode::RectangleCapHeightBased:
      case Qgis::TextLayoutMode::RectangleAscentBased:
        thisBlockMetrics.backgroundWidth = targetWidth;
        thisBlockMetrics.backgroundXOffset = 0;
        break;
      case Qgis::TextLayoutMode::Point:
      case Qgis::TextLayoutMode::Labeling:
        thisBlockMetrics.backgroundWidth = thisBlockMetrics.width;
        thisBlockMetrics.backgroundXOffset = thisBlockMetrics.xOffset;
        break;
    }
 
    blockMetrics << thisBlockMetrics;
    blockIndex++;
  }
  return blockMetrics;
}
 
QBrush QgsTextRenderer::createBrushForPath( QgsRenderContext &context, const QString &path )
{
  bool fitsInCache = false;
  // use original image size
  const QSize imageSize = QgsApplication::imageCache()->originalSize( path, context.flags() & Qgis::RenderContextFlag::RenderBlocking );
  // TODO: maybe there's more optimal logic we could use here, but for now we assume 96dpi image resolution...
  const QSizeF originalSizeMmAt96Dpi = imageSize / 3.7795275590551185;
  const double pixelsPerMm = context.scaleFactor();
  const double imageWidth = originalSizeMmAt96Dpi.width() * pixelsPerMm;
  const double imageHeight = originalSizeMmAt96Dpi.height() * pixelsPerMm;
  QBrush res;
  if ( imageWidth == 0 || imageHeight == 0 )
    return res;
  const QImage image
    = QgsApplication::imageCache()
        ->pathAsImage( path, QSize( static_cast< int >( std::round( imageWidth ) ), static_cast< int >( std::round( imageHeight ) ) ), false, 1, fitsInCache, context.flags() & Qgis::RenderContextFlag::RenderBlocking );
 
  if ( !image.isNull() )
  {
    res.setTextureImage( image );
  }
  return res;
}
 
void QgsTextRenderer::renderDocumentBackgrounds(
  QgsRenderContext &context,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  const Component &component,
  const QVector< QgsTextRenderer::BlockMetrics > &blockMetrics,
  Qgis::TextLayoutMode mode,
  double verticalAlignOffset,
  double rotation
)
{
  int blockIndex = 0;
  context.painter()->translate( component.origin );
  if ( !qgsDoubleNear( rotation, 0.0 ) )
    context.painter()->rotate( rotation );
 
  context.painter()->setPen( Qt::NoPen );
  context.painter()->setBrush( Qt::NoBrush );
  for ( const QgsTextBlock &block : document )
  {
    const double baseLineOffset = metrics.baselineOffset( blockIndex, mode );
    const double blockMaximumDescent = metrics.blockMaximumDescent( blockIndex );
    const double blockMaximumAscent = metrics.blockMaximumAscent( blockIndex );
 
    if ( block.blockFormat().hasBackground() )
    {
      QBrush backgroundBrush = block.blockFormat().backgroundBrush();
      if ( !block.blockFormat().backgroundImagePath().isEmpty() )
      {
        const QBrush backgroundImageBrush = createBrushForPath( context, block.blockFormat().backgroundImagePath() );
        if ( backgroundImageBrush.style() == Qt::BrushStyle::TexturePattern )
          backgroundBrush = backgroundImageBrush;
      }
 
      context.painter()->setBrush( backgroundBrush );
      context.painter()->drawRect(
        QRectF( blockMetrics[blockIndex].backgroundXOffset, baseLineOffset - blockMaximumAscent, blockMetrics[blockIndex].backgroundWidth, blockMaximumDescent + blockMaximumAscent )
      );
    }
 
    double xOffset = 0;
    int fragmentIndex = 0;
 
    for ( const QgsTextFragment &fragment : block )
    {
      const double horizontalAdvance = metrics.fragmentHorizontalAdvance( blockIndex, fragmentIndex, mode );
      const double ascent = metrics.fragmentAscent( blockIndex, fragmentIndex, mode );
      const double descent = metrics.fragmentDescent( blockIndex, fragmentIndex, mode );
 
      if ( fragment.characterFormat().hasBackground() )
      {
        const double yOffset = metrics.fragmentVerticalOffset( blockIndex, fragmentIndex, mode );
 
        QBrush backgroundBrush = fragment.characterFormat().backgroundBrush();
        if ( !fragment.characterFormat().backgroundImagePath().isEmpty() )
        {
          const QBrush backgroundImageBrush = createBrushForPath( context, fragment.characterFormat().backgroundImagePath() );
          if ( backgroundImageBrush.style() == Qt::BrushStyle::TexturePattern )
            backgroundBrush = backgroundImageBrush;
        }
 
        context.painter()->setBrush( backgroundBrush );
        context.painter()->drawRect( QRectF( blockMetrics[blockIndex].xOffset + xOffset, baseLineOffset + verticalAlignOffset + yOffset - ascent, horizontalAdvance, ascent + descent ) );
      }
 
      xOffset += horizontalAdvance;
      fragmentIndex++;
    }
 
    blockIndex++;
  }
 
  context.painter()->setBrush( Qt::NoBrush );
 
  if ( !qgsDoubleNear( rotation, 0.0 ) )
    context.painter()->rotate( -rotation );
  context.painter()->translate( -component.origin );
}
 
void QgsTextRenderer::drawTextInternalHorizontal(
  QgsRenderContext &context,
  const QgsTextFormat &format,
  Qgis::TextComponents components,
  Qgis::TextLayoutMode mode,
  const Component &component,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  double fontScale,
  const Qgis::TextHorizontalAlignment hAlignment,
  Qgis::TextVerticalAlignment vAlignment,
  double rotation
)
{
  QPainter *maskPainter = context.maskPainter( context.currentMaskId() );
 
  const QSizeF documentSize = metrics.documentSize( mode, Qgis::TextOrientation::Horizontal );
 
  double targetWidth = 0.0;
  switch ( mode )
  {
    case Qgis::TextLayoutMode::Labeling:
    case Qgis::TextLayoutMode::Point:
      targetWidth = documentSize.width();
      break;
 
    case Qgis::TextLayoutMode::Rectangle:
    case Qgis::TextLayoutMode::RectangleCapHeightBased:
    case Qgis::TextLayoutMode::RectangleAscentBased:
      targetWidth = component.size.width();
      break;
  }
 
  double verticalAlignOffset = 0;
 
  if ( mode == Qgis::TextLayoutMode::Rectangle )
  {
    const double overallHeight = documentSize.height();
    switch ( vAlignment )
    {
      case Qgis::TextVerticalAlignment::Top:
        verticalAlignOffset = metrics.blockVerticalMargin( -1 );
        break;
 
      case Qgis::TextVerticalAlignment::VerticalCenter:
        verticalAlignOffset = ( component.size.height() - overallHeight ) * 0.5 + metrics.blockVerticalMargin( -1 );
        break;
 
      case Qgis::TextVerticalAlignment::Bottom:
        verticalAlignOffset = ( component.size.height() - overallHeight ) + metrics.blockVerticalMargin( -1 );
        break;
    }
  }
  else if ( mode == Qgis::TextLayoutMode::Point )
  {
    verticalAlignOffset = -metrics.blockVerticalMargin( document.size() - 1 );
  }
 
  // should we use text or paths for this render?
  const bool usePathsForText = usePathsToRender( context, format, document );
 
  // TODO -- maybe we can avoid the nested vector? Need to confirm whether painter rotation & translation can be
  // done ONCE only, upfront
  std::unique_ptr< std::vector< DeferredRenderBlock > > deferredBlocks;
 
  // Depending on format settings, we may need to render in multiple passes. Eg buffer than text, or shadow than text.
  // We try to avoid this if possible as it requires more work, and just do a single pass, rendering text directly as we go.
  // If we need to do multi-pass rendering then we'll calculate paths ONCE upfront and defer actually rendering these.
  const bool requiresMultiPassRendering
    = ( components & Qgis::TextComponent::Buffer && format.buffer().enabled() )
      || ( components & Qgis::TextComponent::Shadow && format.shadow().enabled() && ( format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowText || format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowBuffer ) );
  if ( requiresMultiPassRendering )
  {
    deferredBlocks = std::make_unique< std::vector< DeferredRenderBlock > >();
    deferredBlocks->reserve( document.size() );
  }
 
  if ( ( components & Qgis::TextComponent::Buffer ) || ( components & Qgis::TextComponent::Text ) || ( components & Qgis::TextComponent::Shadow ) )
  {
    const QVector< BlockMetrics > blockMetrics = calculateBlockMetrics( document, metrics, mode, targetWidth, hAlignment );
 
    if ( document.hasBackgrounds() )
    {
      renderDocumentBackgrounds( context, document, metrics, component, blockMetrics, mode, verticalAlignOffset, rotation );
    }
 
    int blockIndex = 0;
    for ( const QgsTextBlock &block : document )
    {
      const double blockHeight = metrics.blockHeight( blockIndex );
 
      DeferredRenderBlock *deferredBlock = nullptr;
      if ( requiresMultiPassRendering && deferredBlocks )
      {
        deferredBlocks->emplace_back( DeferredRenderBlock() );
        deferredBlock = &deferredBlocks->back();
        deferredBlock->fragments.reserve( block.size() );
      }
 
      QgsScopedQPainterState painterState( context.painter() );
      context.setPainterFlagsUsingContext();
      context.painter()->translate( component.origin );
      if ( !qgsDoubleNear( rotation, 0.0 ) )
        context.painter()->rotate( rotation );
 
      // apply to the mask painter the same transformations
      if ( maskPainter )
      {
        maskPainter->save();
        maskPainter->translate( component.origin );
        if ( !qgsDoubleNear( rotation, 0.0 ) )
          maskPainter->rotate( rotation );
      }
 
      const BlockMetrics thisBlockMetrics = blockMetrics[blockIndex];
      const double baseLineOffset = metrics.baselineOffset( blockIndex, mode );
 
      const QPointF blockOrigin( thisBlockMetrics.xOffset, baseLineOffset + verticalAlignOffset );
      if ( deferredBlock )
        deferredBlock->origin = blockOrigin;
      else
        context.painter()->translate( blockOrigin );
      if ( maskPainter )
        maskPainter->translate( blockOrigin );
 
      Component subComponent;
      subComponent.block = block;
      subComponent.blockIndex = blockIndex;
      subComponent.size = QSizeF( thisBlockMetrics.width, blockHeight );
      subComponent.offset = QPointF( 0.0, -metrics.ascentOffset() );
      subComponent.rotation = -component.rotation * 180 / M_PI;
      subComponent.rotationOffset = 0.0;
      subComponent.extraWordSpacing = thisBlockMetrics.extraWordSpace * fontScale;
      subComponent.extraLetterSpacing = thisBlockMetrics.extraLetterSpace * fontScale;
      if ( deferredBlock )
        deferredBlock->component = subComponent;
 
      // draw the mask below the text (for preview)
      if ( format.mask().enabled() )
      {
        QgsTextRenderer::drawMask( context, subComponent, format, metrics, mode );
      }
 
      // if we are drawing both text + buffer, we'll need a path, as we HAVE to render buffers using paths
      const bool needsPaths = usePathsForText
                              || ( ( components & Qgis::TextComponent::Buffer ) && format.buffer().enabled() )
                              || ( ( components & Qgis::TextComponent::Shadow ) && format.shadow().enabled() );
 
      std::optional< QgsScopedRenderContextReferenceScaleOverride > referenceScaleOverride;
      if ( mode == Qgis::TextLayoutMode::Labeling )
      {
        // label size has already been calculated using any symbology reference scale factor -- we need
        // to temporarily remove the reference scale here or we'll be applying the scaling twice
        referenceScaleOverride.emplace( QgsScopedRenderContextReferenceScaleOverride( context, -1.0 ) );
      }
 
      referenceScaleOverride.reset();
 
      // now render the actual text
      if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
      {
        context.painter()->setCompositionMode( format.blendMode() );
      }
 
      // scale for any print output or image saving @ specific dpi
      context.painter()->scale( subComponent.dpiRatio, subComponent.dpiRatio );
 
      context.painter()->scale( 1 / fontScale, 1 / fontScale );
      context.painter()->setPen( Qt::NoPen );
      context.painter()->setBrush( Qt::NoBrush );
 
      renderBlockHorizontal( block, blockIndex, metrics, context, format, context.painter(), needsPaths, fontScale, thisBlockMetrics.extraWordSpace, thisBlockMetrics.extraLetterSpace, mode, deferredBlock );
 
      if ( maskPainter )
        maskPainter->restore();
 
      blockIndex++;
    }
  }
 
  if ( deferredBlocks )
  {
    renderDeferredBlocks( context, format, components, *deferredBlocks, usePathsForText, fontScale, component, rotation );
  }
}
 
void QgsTextRenderer::renderDeferredBlocks(
  QgsRenderContext &context,
  const QgsTextFormat &format,
  Qgis::TextComponents components,
  const std::vector< DeferredRenderBlock > &deferredBlocks,
  bool usePathsForText,
  double fontScale,
  const Component &component,
  double rotation
)
{
  if ( format.buffer().enabled() && ( components & Qgis::TextComponent::Buffer ) )
  {
    renderDeferredBuffer( context, format, components, deferredBlocks, fontScale, component, rotation );
  }
 
  if ( ( components & Qgis::TextComponent::Shadow ) && format.shadow().enabled() && format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowText )
  {
    renderDeferredShadowForText( context, format, deferredBlocks, fontScale, component, rotation );
    // TODO: there's an optimisation opportunity here -- if we are ALSO rendering the text component,
    // we could move the actual text rendering into renderDeferredShadowForText and use the same
    // QPicture as we used for the shadow. But we'd need to ensure that all the settings
    // which control whether text is rendered as text or paths also also considered.
  }
 
  if ( components & Qgis::TextComponent::Text )
  {
    renderDeferredText( context, deferredBlocks, usePathsForText, fontScale, component, rotation );
  }
}
 
void QgsTextRenderer::renderDeferredShadowForText(
  QgsRenderContext &context, const QgsTextFormat &format, const std::vector< DeferredRenderBlock > &deferredBlocks, double fontScale, const Component &component, double rotation
)
{
  QgsScopedQPainterState painterState( context.painter() );
  context.setPainterFlagsUsingContext();
  context.painter()->translate( component.origin );
  if ( !qgsDoubleNear( rotation, 0.0 ) )
    context.painter()->rotate( rotation );
 
  context.painter()->setPen( Qt::NoPen );
  context.painter()->setBrush( Qt::NoBrush );
 
  for ( const DeferredRenderBlock &block : deferredBlocks )
  {
    Component subComponent = block.component;
 
    QPainter painter( &subComponent.picture );
    painter.setPen( Qt::NoPen );
    painter.setBrush( Qt::NoBrush );
    painter.scale( 1 / fontScale, 1 / fontScale );
 
    for ( const DeferredRenderFragment &fragment : std::as_const( block.fragments ) )
    {
      if ( !fragment.path.isEmpty() )
      {
        painter.setBrush( fragment.color );
        painter.drawPath( fragment.path );
      }
      else
      {
        painter.setPen( fragment.color );
        painter.setFont( fragment.font );
        painter.drawText( fragment.point, fragment.text );
      }
    }
    painter.end();
 
    subComponent.pictureBuffer = 1.0; // no pen width to deal with, but we'll add 1 px for antialiasing
    subComponent.origin = QPointF( 0.0, 0.0 );
    const QRectF pictureBoundingRect = subComponent.picture.boundingRect();
    subComponent.size = pictureBoundingRect.size();
    subComponent.offset = QPointF( -pictureBoundingRect.left(), -pictureBoundingRect.height() - pictureBoundingRect.top() );
 
    context.painter()->translate( block.origin );
    drawShadow( context, subComponent, format );
    context.painter()->translate( -block.origin );
  }
}
 
void QgsTextRenderer::renderDeferredBuffer(
  QgsRenderContext &context, const QgsTextFormat &format, Qgis::TextComponents components, const std::vector< DeferredRenderBlock > &deferredBlocks, double fontScale, const Component &component, double rotation
)
{
  QgsScopedQPainterState painterState( context.painter() );
  context.setPainterFlagsUsingContext();
 
  // do we need a drop shadow effect on the buffer component? If so, we'll render the buffer to a QPicture first and then use this
  // to generate the shadow, and then render the QPicture as the buffer on top. If not, avoid the unwanted expense of the temporary QPicture
  // and render directly.
  const bool needsShadowOnBuffer = ( ( components & Qgis::TextComponent::Shadow ) && format.shadow().enabled() && format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowBuffer );
  std::unique_ptr< QPicture > bufferPicture;
  std::unique_ptr< QPainter > bufferPainter;
  QPainter *prevPainter = context.painter();
  if ( needsShadowOnBuffer )
  {
    bufferPicture = std::make_unique< QPicture >();
    bufferPainter = std::make_unique< QPainter >( bufferPicture.get() );
    context.setPainter( bufferPainter.get() );
  }
 
  std::unique_ptr< QgsPaintEffect > tmpEffect;
  if ( format.buffer().paintEffect() && format.buffer().paintEffect()->enabled() )
  {
    tmpEffect.reset( format.buffer().paintEffect()->clone() );
    tmpEffect->begin( context );
  }
 
  QColor bufferColor = format.buffer().color();
  bufferColor.setAlphaF( format.buffer().opacity() );
  QPen pen( bufferColor );
  const QgsTextBufferSettings &buffer = format.buffer();
  const double penSize = buffer.sizeUnit() == Qgis::RenderUnit::Percentage ? context.convertToPainterUnits( format.size(), format.sizeUnit(), format.sizeMapUnitScale() ) * buffer.size() / 100
                                                                           : context.convertToPainterUnits( buffer.size(), buffer.sizeUnit(), buffer.sizeMapUnitScale() );
  pen.setWidthF( penSize * fontScale );
  pen.setJoinStyle( buffer.joinStyle() );
  context.painter()->setPen( pen );
 
  // honor pref for whether to fill buffer interior
  if ( !buffer.fillBufferInterior() )
  {
    bufferColor.setAlpha( 0 );
  }
  context.painter()->setBrush( bufferColor );
 
  context.painter()->translate( component.origin );
  if ( !qgsDoubleNear( rotation, 0.0 ) )
    context.painter()->rotate( rotation );
 
  if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
  {
    context.painter()->setCompositionMode( format.buffer().blendMode() );
  }
 
  for ( const DeferredRenderBlock &block : deferredBlocks )
  {
    context.painter()->translate( block.origin );
    context.painter()->scale( 1 / fontScale, 1 / fontScale );
    for ( const DeferredRenderFragment &fragment : std::as_const( block.fragments ) )
    {
      context.painter()->drawPath( fragment.path );
    }
    context.painter()->scale( fontScale, fontScale );
    context.painter()->translate( -block.origin );
  }
 
  if ( tmpEffect )
  {
    tmpEffect->end( context );
  }
 
  if ( needsShadowOnBuffer && bufferPicture )
  {
    bufferPainter->end();
    bufferPainter.reset();
    context.setPainter( prevPainter );
 
    QgsTextRenderer::Component bufferComponent = component;
    bufferComponent.origin = QPointF( 0.0, 0.0 );
    bufferComponent.picture = *bufferPicture;
    bufferComponent.pictureBuffer = penSize / 2.0;
    const QRectF bufferBoundingBox = bufferPicture->boundingRect();
    bufferComponent.size = bufferBoundingBox.size();
    bufferComponent.offset = QPointF( -bufferBoundingBox.left(), -bufferBoundingBox.height() - bufferBoundingBox.top() );
 
    drawShadow( context, bufferComponent, format );
 
    // also draw buffer
    if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
    {
      context.painter()->setCompositionMode( buffer.blendMode() );
    }
 
    // scale for any print output or image saving @ specific dpi
    context.painter()->scale( component.dpiRatio, component.dpiRatio );
    QgsPainting::drawPicture( context.painter(), QPointF( 0, 0 ), *bufferPicture );
  }
}
 
void QgsTextRenderer::renderDeferredText(
  QgsRenderContext &context, const std::vector< DeferredRenderBlock > &deferredBlocks, bool usePathsForText, double fontScale, const Component &component, double rotation
)
{
  QgsScopedQPainterState painterState( context.painter() );
  context.setPainterFlagsUsingContext();
  context.painter()->translate( component.origin );
  if ( !qgsDoubleNear( rotation, 0.0 ) )
    context.painter()->rotate( rotation );
 
  context.painter()->setPen( Qt::NoPen );
  context.painter()->setBrush( Qt::NoBrush );
 
  // draw the text
  for ( const DeferredRenderBlock &block : deferredBlocks )
  {
    context.painter()->translate( block.origin );
    context.painter()->scale( 1 / fontScale, 1 / fontScale );
 
    for ( const DeferredRenderFragment &fragment : std::as_const( block.fragments ) )
    {
      if ( usePathsForText )
      {
        context.painter()->setBrush( fragment.color );
        context.painter()->drawPath( fragment.path );
      }
      else
      {
        context.painter()->setPen( fragment.color );
        context.painter()->setFont( fragment.font );
        context.painter()->drawText( fragment.point, fragment.text );
      }
    }
 
    context.painter()->scale( fontScale, fontScale );
    context.painter()->translate( -block.origin );
  }
}
 
void QgsTextRenderer::drawTextInternalVertical(
  QgsRenderContext &context,
  const QgsTextFormat &format,
  Qgis::TextComponents components,
  Qgis::TextLayoutMode mode,
  const QgsTextRenderer::Component &component,
  const QgsTextDocument &document,
  const QgsTextDocumentMetrics &metrics,
  double fontScale,
  Qgis::TextHorizontalAlignment hAlignment,
  Qgis::TextVerticalAlignment,
  double rotation
)
{
  QPainter *maskPainter = context.maskPainter( context.currentMaskId() );
  const QStringList textLines = document.toPlainText();
 
  std::optional< QgsScopedRenderContextReferenceScaleOverride > referenceScaleOverride;
  if ( mode == Qgis::TextLayoutMode::Labeling )
  {
    // label size has already been calculated using any symbology reference scale factor -- we need
    // to temporarily remove the reference scale here or we'll be applying the scaling twice
    referenceScaleOverride.emplace( QgsScopedRenderContextReferenceScaleOverride( context, -1.0 ) );
  }
 
  if ( metrics.isNullFontSize() )
    return;
 
  referenceScaleOverride.reset();
 
  const QSizeF documentSize = metrics.documentSize( mode, Qgis::TextOrientation::Vertical );
  const double actualTextWidth = documentSize.width();
  double textRectWidth = 0.0;
 
  switch ( mode )
  {
    case Qgis::TextLayoutMode::Labeling:
    case Qgis::TextLayoutMode::Point:
      textRectWidth = actualTextWidth;
      break;
 
    case Qgis::TextLayoutMode::Rectangle:
    case Qgis::TextLayoutMode::RectangleCapHeightBased:
    case Qgis::TextLayoutMode::RectangleAscentBased:
      textRectWidth = component.size.width();
      break;
  }
 
  int maxLineLength = 0;
  for ( const QString &line : std::as_const( textLines ) )
  {
    maxLineLength = std::max( maxLineLength, static_cast<int>( line.length() ) );
  }
 
  const double actualLabelHeight = documentSize.height();
  int blockIndex = 0;
 
  bool adjustForAlignment = hAlignment != Qgis::TextHorizontalAlignment::Left && ( mode != Qgis::TextLayoutMode::Labeling || textLines.size() > 1 );
 
  for ( const QgsTextBlock &block : document )
  {
    QgsScopedQPainterState painterState( context.painter() );
    context.setPainterFlagsUsingContext();
 
    context.painter()->translate( component.origin );
    if ( !qgsDoubleNear( rotation, 0.0 ) )
      context.painter()->rotate( rotation );
 
    // apply to the mask painter the same transformations
    if ( maskPainter )
    {
      maskPainter->save();
      maskPainter->translate( component.origin );
      if ( !qgsDoubleNear( rotation, 0.0 ) )
        maskPainter->rotate( rotation );
    }
 
    const double blockMaximumCharacterWidth = metrics.blockMaximumCharacterWidth( blockIndex );
 
    // figure x offset of multiple lines
    double xOffset = metrics.verticalOrientationXOffset( blockIndex );
    if ( adjustForAlignment )
    {
      double hAlignmentOffset = 0;
      switch ( hAlignment )
      {
        case Qgis::TextHorizontalAlignment::Center:
          hAlignmentOffset = ( textRectWidth - actualTextWidth ) * 0.5;
          break;
 
        case Qgis::TextHorizontalAlignment::Right:
          hAlignmentOffset = textRectWidth - actualTextWidth;
          break;
 
        case Qgis::TextHorizontalAlignment::Left:
        case Qgis::TextHorizontalAlignment::Justify:
          break;
      }
 
      switch ( mode )
      {
        case Qgis::TextLayoutMode::Labeling:
        case Qgis::TextLayoutMode::Rectangle:
        case Qgis::TextLayoutMode::RectangleCapHeightBased:
        case Qgis::TextLayoutMode::RectangleAscentBased:
          xOffset += hAlignmentOffset;
          break;
 
        case Qgis::TextLayoutMode::Point:
          break;
      }
    }
 
    double yOffset = 0.0;
    switch ( mode )
    {
      case Qgis::TextLayoutMode::Labeling:
        if ( format.orientation() == Qgis::TextOrientation::RotationBased )
        {
          if ( rotation >= -405 && rotation < -180 )
          {
            yOffset = 0;
          }
          else if ( rotation >= 0 && rotation < 45 )
          {
            xOffset -= actualTextWidth;
            yOffset = -actualLabelHeight + metrics.blockMaximumDescent( blockIndex );
          }
        }
        else
        {
          yOffset = -actualLabelHeight;
        }
        break;
 
      case Qgis::TextLayoutMode::Point:
        yOffset = -actualLabelHeight;
        break;
 
      case Qgis::TextLayoutMode::Rectangle:
      case Qgis::TextLayoutMode::RectangleCapHeightBased:
      case Qgis::TextLayoutMode::RectangleAscentBased:
        yOffset = 0;
        break;
    }
 
    context.painter()->translate( QPointF( xOffset, yOffset ) );
 
    double currentBlockYOffset = 0;
    int fragmentIndex = 0;
    for ( const QgsTextFragment &fragment : block )
    {
      QgsScopedQPainterState fragmentPainterState( context.painter() );
 
      // apply some character replacement to draw symbols in vertical presentation
      const QString line = QgsStringUtils::substituteVerticalCharacters( fragment.text() );
 
      const QFont fragmentFont = metrics.fragmentFont( blockIndex, fragmentIndex );
 
      QFontMetricsF fragmentMetrics( fragmentFont );
 
      const double letterSpacing = fragmentFont.letterSpacing() / fontScale;
      const double labelHeight = fragmentMetrics.ascent() / fontScale + ( fragmentMetrics.ascent() / fontScale + letterSpacing ) * ( line.length() - 1 );
 
      Component subComponent;
      subComponent.block = QgsTextBlock( fragment );
      subComponent.blockIndex = blockIndex;
      subComponent.firstFragmentIndex = fragmentIndex;
      subComponent.size = QSizeF( blockMaximumCharacterWidth, labelHeight + fragmentMetrics.descent() / fontScale );
      subComponent.offset = QPointF( 0.0, currentBlockYOffset );
      subComponent.rotation = -component.rotation * 180 / M_PI;
      subComponent.rotationOffset = 0.0;
 
      // draw the mask below the text (for preview)
      if ( format.mask().enabled() )
      {
        // WARNING: totally broken! (has been since mask was introduced)
#if 0
        QgsTextRenderer::drawMask( context, subComponent, format );
#endif
      }
 
      if ( components & Qgis::TextComponent::Buffer )
      {
        currentBlockYOffset += QgsTextRenderer::drawBuffer( context, subComponent, format, metrics, mode );
      }
      if ( ( components & Qgis::TextComponent::Text ) || ( components & Qgis::TextComponent::Shadow ) )
      {
        // draw text, QPainterPath method
        QPainterPath path;
        path.setFillRule( Qt::WindingFill );
        const QStringList parts = QgsPalLabeling::splitToGraphemes( fragment.text() );
        double partYOffset = 0.0;
        for ( const QString &part : parts )
        {
          double partXOffset = ( blockMaximumCharacterWidth - ( fragmentMetrics.horizontalAdvance( part ) / fontScale - letterSpacing ) ) / 2;
          partYOffset += fragmentMetrics.ascent() / fontScale;
          path.addText( partXOffset * fontScale, partYOffset * fontScale, fragmentFont, part );
          partYOffset += letterSpacing;
        }
 
        // store text's drawing in QPicture for drop shadow call
        QPicture textPict;
        QPainter textp;
        textp.begin( &textPict );
        textp.setPen( Qt::NoPen );
        QColor textColor = fragment.characterFormat().textColor().isValid() ? fragment.characterFormat().textColor() : format.color();
        textColor.setAlphaF( fragment.characterFormat().textColor().isValid() ? textColor.alphaF() * format.opacity() : format.opacity() );
        textp.setBrush( textColor );
        textp.scale( 1 / fontScale, 1 / fontScale );
        textp.drawPath( path );
 
        // TODO: why are some font settings lost on drawPicture() when using drawText() inside QPicture?
        //       e.g. some capitalization options, but not others
        //textp.setFont( tmpLyr.textFont );
        //textp.setPen( tmpLyr.textColor );
        //textp.drawText( 0, 0, component.text() );
        textp.end();
 
        if ( format.shadow().enabled() && format.shadow().shadowPlacement() == QgsTextShadowSettings::ShadowText )
        {
          subComponent.picture = textPict;
          subComponent.pictureBuffer = 0.0; // no pen width to deal with
          subComponent.origin = QPointF( 0.0, currentBlockYOffset );
          const double prevY = subComponent.offset.y();
          subComponent.offset = QPointF( 0, -subComponent.size.height() );
          subComponent.useOrigin = true;
          QgsTextRenderer::drawShadow( context, subComponent, format );
          subComponent.useOrigin = false;
          subComponent.offset = QPointF( 0, prevY );
        }
 
        // paint the text
        if ( context.rasterizedRenderingPolicy() != Qgis::RasterizedRenderingPolicy::ForceVector )
        {
          context.painter()->setCompositionMode( format.blendMode() );
        }
 
        // scale for any print output or image saving @ specific dpi
        context.painter()->scale( subComponent.dpiRatio, subComponent.dpiRatio );
 
        // TODO -- this should respect the context's TextRenderFormat
        // draw outlined text
        context.painter()->translate( 0, currentBlockYOffset );
        QgsPainting::applyScaleFixForQPictureDpi( context.painter() );
        context.painter()->drawPicture( 0, 0, textPict );
        currentBlockYOffset += partYOffset;
      }
      fragmentIndex++;
    }
 
    if ( maskPainter )
      maskPainter->restore();
    blockIndex++;
  }
}
 
double QgsTextRenderer::calculateScaleFactorForFormat( const QgsRenderContext &context, const QgsTextFormat &format )
{
  if ( !( context.flags() & Qgis::RenderContextFlag::ApplyScalingWorkaroundForTextRendering ) )
    return 1.0;
 
  const double pixelSize = context.convertToPainterUnits( format.size(), format.sizeUnit(), format.sizeMapUnitScale() );
 
  // THESE THRESHOLDS MAY NEED TWEAKING!
 
  // NOLINTBEGIN(bugprone-branch-clone)
 
  // for small font sizes we need to apply a growth scaling workaround designed to stablise the rendering of small font sizes
  // we scale the painter up so that we render small text at 200 pixel size and let the painter scaling handle making it the correct size
  if ( pixelSize < 50 )
    return 200 / pixelSize;
  //... but for large font sizes we might run into https://bugreports.qt.io/browse/QTBUG-98778, which messes up the spacing between words for large fonts!
  // so instead we scale down the painter so that we render the text at 200 pixel size and let painter scaling handle making it the correct size
  else if ( pixelSize > 200 )
    return 200 / pixelSize;
  else
    return 1.0;
 
  // NOLINTEND(bugprone-branch-clone)
}