Add custom layer property to render a layer over labels in the map canvas

Usage:

layer.setCustomProperty('rendering/renderAboveLabels', True)

This is exposed only as a layer custom property since it's really just
exposing some private internals of the rendering map composition. It's
not supported outside of canvas, and only works when parallel rendering
with render cache is enabled.

It's not exposed anywhere in GUI for this same reason. Consider it a
hidden API call until someone implements proper handling of mixed
layer/label stacking order.

Author: nyalldawson

src/core/qgsmaprendererjob.cpp

@@ -457,10 +457,14 @@ QImage QgsMapRendererJob::composeImage( const QgsMapSettings& settings, const La
 
   QPainter painter( &image );
 
+
   for ( LayerRenderJobs::const_iterator it = jobs.constBegin(); it != jobs.constEnd(); ++it )
   {
     const LayerRenderJob& job = *it;
 
+    if ( job.layer && job.layer->customProperty( QStringLiteral( "rendering/renderAboveLabels" ) ).toBool() )
+      continue; // skip layer for now, it will be rendered after labels
+
     painter.setCompositionMode( job.blendMode );
     painter.setOpacity( job.opacity );
 
@@ -479,6 +483,22 @@ QImage QgsMapRendererJob::composeImage( const QgsMapSettings& settings, const La
     painter.drawImage( 0, 0, *labelJob.img );
   }
 
+  // render any layers with the renderAboveLabels flag now
+  for ( LayerRenderJobs::const_iterator it = jobs.constBegin(); it != jobs.constEnd(); ++it )
+  {
+    const LayerRenderJob& job = *it;
+
+    if ( !job.layer || !job.layer->customProperty( QStringLiteral( "rendering/renderAboveLabels" ) ).toBool() )
+      continue;
+
+    painter.setCompositionMode( job.blendMode );
+    painter.setOpacity( job.opacity );
+
+    Q_ASSERT( job.img );
+
+    painter.drawImage( 0, 0, *job.img );
+  }
+
   painter.end();
   return image;
 }