[FEATURE] Selective masking (#30747)

* [FEATURE] Selective masking

Advanced rendering feature that allows the definition of 'masks' areas around labels or with a new typ of symbol layer. These masks will "un-draw" symbol layers of other layers underneath.
It modifies the rendering process by adding an optional second pass.

doc/design/selective_masking/README.md

@@ -0,0 +1,13 @@
+# Selective masking
+
+Here are some detailed step-by-step examples of renderings with selective masking enabled.
+Examples are taken from the tests and some intermediary images have been added to illustrate how the rendering works.
+
+* [1 - Only labels mask other symbol layers](p1/README.md)
+* [1b - Only labels mask other symbol layers (with symbol levels)](p1b/README.md)
+* [2 - A symbol layer mask other symbol layers](p2/README.md)
+* [3 - Merged masks](p3/README.md)
+* [4 - Different masks on the same layer](p4/README.md)
+* [5 - Different masks on the same layer (2)](p5/README.md)
+* [6 - Label masks with effects](p6/README.md)
+

doc/design/selective_masking/p1/README.md

@@ -0,0 +1,68 @@
+# Selective masking case 1
+
+<table border=1>
+      <tr>
+        <td>Layers</td>
+        <td><b>Polys</b></td>
+        <td><b>Lines</b></td>
+        <td><b>Points</b></td>
+        <td><b>Labels</b></td>
+      </tr>
+      <tr>
+        <td>Symbol layers</td>
+        <td></td>
+        <td><b>0</b>: black roads<br/><b>1</b>: yellow roads</td>
+        <td><b>0</b>: black jets<br/><b>1</b>: orange jets<br/><b>2</b>: other black jets</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>Masks</td>
+        <td></td>
+        <td></td>
+        <td></td>
+        <td>A buffer that masks<br/><b>Lines/0</b><br/><b>Points/0</b><br/><b>Points/2</b></td>
+      </tr>
+      <tr>
+        <td>First pass</td>
+        <td><img src="first_pass_0.png"/></td>
+        <td><img src="first_pass_1.png"/></td>
+        <td><img src="first_pass_2.png"/></td>
+        <td><img src="labels.png"/></td>
+      </tr>
+      <tr>
+        <td>Mask image<br/>(still in first pass)</td>
+        <td></td>
+        <td></td>
+        <td></td>
+        <td><img src="labels_mask.png"/></td>
+      </tr>
+    </table>
+    <table border=1>
+      <tr>
+        <td>Second pass</td>
+        <td><b>Lines</b> without <b>0</b><br/><img src="second_1.png"/></td>
+        <td><b>Points</b> without <b>0, 2</b><br/><img src="second_2.png"/></td>
+      </tr>
+      <tr>
+        <td>Composition with mask</td>
+        <td><img src="labels_mask.png"/></td>
+        <td><img src="labels_mask.png"/></td>
+      </tr>
+      <tr>
+        <td>Second pass image <b>inside</b> mask</td>
+        <td><img src="second_1_a.png"/></td>
+        <td><img src="second_2_a.png"/></td>
+      </tr>
+      <tr>
+        <td>First pass image <b>oustide</b> mask</td>
+        <td><img src="second_1_first_pass_2.png"/></td>
+        <td><img src="second_2_first_pass_2.png"/></td>
+      </tr>
+      <tr>
+        <td>Updated first pass image</td>
+        <td><img src="second_1_first_pass_3.png"/></td>
+        <td><img src="second_2_first_pass_3.png"/></td>
+      </tr>
+</table>
+
+Final image <img src="final.png"/>

doc/design/selective_masking/p1b/README.md

@@ -0,0 +1,68 @@
+# Selective masking case 1
+
+<table border=1>
+      <tr>
+        <td>Layers</td>
+        <td><b>Polys</b></td>
+        <td><b>Lines</b></td>
+        <td><b>Points</b></td>
+        <td><b>Labels</b></td>
+      </tr>
+      <tr>
+        <td>Symbol layers</td>
+        <td></td>
+        <td><b>0</b>: black roads<br/><b>1</b>: yellow roads</td>
+        <td><b>0</b>: black jets<br/><b>1</b>: orange jets<br/><b>2</b>: other black jets</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>Masks</td>
+        <td></td>
+        <td></td>
+        <td></td>
+        <td>A buffer that masks<br/><b>Lines/0</b><br/><b>Points/0</b><br/><b>Points/2</b></td>
+      </tr>
+      <tr>
+        <td>First pass</td>
+        <td><img src="first_pass_0.png"/></td>
+        <td><img src="first_pass_1.png"/></td>
+        <td><img src="first_pass_2.png"/></td>
+        <td><img src="labels.png"/></td>
+      </tr>
+      <tr>
+        <td>Mask image<br/>(still in first pass)</td>
+        <td></td>
+        <td></td>
+        <td></td>
+        <td><img src="labels_mask.png"/></td>
+      </tr>
+    </table>
+    <table border=1>
+      <tr>
+        <td>Second pass</td>
+        <td><b>Lines</b> without <b>0</b><br/><img src="second_1.png"/></td>
+        <td><b>Points</b> without <b>0, 2</b><br/><img src="second_2.png"/></td>
+      </tr>
+      <tr>
+        <td>Composition with mask</td>
+        <td><img src="labels_mask.png"/></td>
+        <td><img src="labels_mask.png"/></td>
+      </tr>
+      <tr>
+        <td>Second pass image <b>inside</b> mask</td>
+        <td><img src="second_1_a.png"/></td>
+        <td><img src="second_2_a.png"/></td>
+      </tr>
+      <tr>
+        <td>First pass image <b>oustide</b> mask</td>
+        <td><img src="second_1_first_pass_2.png"/></td>
+        <td><img src="second_2_first_pass_2.png"/></td>
+      </tr>
+      <tr>
+        <td>Updated first pass image</td>
+        <td><img src="second_1_first_pass_3.png"/></td>
+        <td><img src="second_2_first_pass_3.png"/></td>
+      </tr>
+</table>
+
+Final image <img src="final.png"/>

doc/design/selective_masking/p2/README.md

@@ -0,0 +1,64 @@
+# Selective masking case 2
+
+<table border=1>
+      <tr>
+        <td>Layers</td>
+        <td><b>Polys</b></td>
+        <td><b>Lines</b></td>
+        <td><b>Points</b></td>
+        <td><b>Labels</b></td>
+      </tr>
+      <tr>
+        <td>Symbol layers</td>
+        <td></td>
+        <td><b>0</b>: black roads<br/><b>1</b>: yellow roads</td>
+        <td><b>0</b>: orange circles<br/><b>1</b>: marker mask, bigger circle<br/>(only visible in mask image)</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>Masks</td>
+        <td></td>
+        <td></td>
+        <td><b>Points/1</b> masks <b>Lines/0</b></td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>First pass</td>
+        <td><img src="first_pass_0.png"/></td>
+        <td><img src="first_pass_1.png"/></td>
+        <td><img src="first_pass_2.png"/></td>
+        <td><img src="labels.png"/></td>
+      </tr>
+      <tr>
+        <td>Mask image<br/>(still in first pass)</td>
+        <td></td>
+        <td></td>
+        <td><img src="first_pass_2_mask.png"/></td>
+        <td></td>
+      </tr>
+    </table>
+    <table border=1>
+      <tr>
+        <td>Second pass</td>
+        <td><b>Lines</b> without <b>0</b><br/><img src="second_1.png"/></td>
+      </tr>
+      <tr>
+        <td>Composition with mask</td>
+        <td><img src="first_pass_2_mask.png"/></td>
+      </tr>
+      <tr>
+        <td>Second pass image <b>inside</b> mask</td>
+        <td><img src="second_1_a.png"/></td>
+      </tr>
+      <tr>
+        <td>First pass image <b>oustide</b> mask</td>
+        <td><img src="second_1_first_pass_2.png"/></td>
+      </tr>
+      <tr>
+        <td>Updated first pass image</td>
+        <td><img src="second_1_first_pass_3.png"/></td>
+      </tr>
+</table>
+
+Final image <img src="final.png"/>
+

doc/design/selective_masking/p3/README.md

@@ -0,0 +1,63 @@
+# Selective masking case 3
+
+<table border=1>
+      <tr>
+        <td>Layers</td>
+        <td><b>Polys</b></td>
+        <td><b>Lines</b></td>
+        <td><b>Points</b></td>
+        <td><b>Labels</b></td>
+      </tr>
+      <tr>
+        <td>Symbol layers</td>
+        <td></td>
+        <td><b>0</b>: black roads<br/><b>1</b>: yellow roads</td>
+        <td><b>0</b>: orange circles<br/><b>1</b>: marker mask, bigger circle<br/>(only visible in mask image)</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>Masks</td>
+        <td></td>
+        <td></td>
+        <td><b>Points/1</b> masks <b>Lines/0</b></td>
+        <td>Buffer masks <b>Lines/0</b></td>
+      </tr>
+      <tr>
+        <td>First pass</td>
+        <td><img src="first_pass_0.png"/></td>
+        <td><img src="first_pass_1.png"/></td>
+        <td><img src="first_pass_2.png"/></td>
+        <td><img src="labels.png"/></td>
+      </tr>
+      <tr>
+        <td>Mask image<br/>(still in first pass)</td>
+        <td></td>
+        <td></td>
+        <td><img src="first_pass_2_mask.png"/></td>
+        <td><img src="labels_mask.png"/></td>
+      </tr>
+    </table>
+    <table border=1>
+      <tr>
+        <td>Second pass</td>
+        <td><b>Lines</b> without <b>0</b><br/><img src="second_1.png"/></td>
+      </tr>
+      <tr>
+        <td>Composition with merged mask</td>
+        <td><img src="mask_1.png"/></td>
+      </tr>
+      <tr>
+        <td>Second pass image <b>inside</b> mask</td>
+        <td><img src="second_1_a.png"/></td>
+      </tr>
+      <tr>
+        <td>First pass image <b>oustide</b> mask</td>
+        <td><img src="second_1_first_pass_2.png"/></td>
+      </tr>
+      <tr>
+        <td>Updates first pass image</td>
+        <td><img src="second_1_first_pass_3.png"/></td>
+      </tr>
+</table>
+
+Final image <img src="final.png"/>

doc/design/selective_masking/p4/README.md

@@ -0,0 +1,67 @@
+# Selective masking case 4
+
+<table border=1>
+      <tr>
+        <td>Layers</td>
+        <td><b>Polys</b></td>
+        <td><b>Lines</b></td>
+        <td><b>Points</b></td>
+        <td><b>Labels</b></td>
+      </tr>
+      <tr>
+        <td>Symbol layers</td>
+        <td></td>
+        <td><b>0</b>: black roads<br/><b>1</b>: yellow roads</td>
+        <td><b>0</b>: orange circles<br/><b>1</b>: marker mask, bigger circle<br/>(only visible in mask image)</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>Masks</td>
+        <td></td>
+        <td></td>
+        <td><b>Points/1</b> masks <b>Lines/1</b></td>
+        <td>Buffer masks <b>Lines/0</b></td>
+      </tr>
+      <tr>
+        <td>First pass</td>
+        <td><img src="first_pass_0.png"/></td>
+        <td><img src="first_pass_1.png"/></td>
+        <td><img src="first_pass_2.png"/></td>
+        <td><img src="labels.png"/></td>
+      </tr>
+      <tr>
+        <td>Mask image<br/>(still in first pass)</td>
+        <td></td>
+        <td></td>
+        <td><img src="first_pass_2_mask.png"/></td>
+        <td><img src="labels_mask.png"/></td>
+      </tr>
+    </table>
+Warning message:<br/>
+<b>Layer lines_ef106202_b4e1_49c4_a3d0_b65eb8bbb6d6 : Different sets of symbol layers are masked by different sources ! Only one (arbitrary) set will be retained !
+</b>
+<table border=1>
+      <tr>
+        <td>Second pass</td>
+        <td><b>Lines</b> without <b>1</b><br/><img src="second_1.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>Composition with merged mask</td>
+        <td><img src="mask_1.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>Second pass image <b>inside</b> mask</td>
+        <td><img src="second_1_a.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>First pass image <b>oustide</b> mask<br/></td>
+        <td><img src="second_1_first_pass_2.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>Updated first pass image</td>
+        <td><img src="second_1_first_pass_3.png" style="vertical-align:middle"/></td>
+      </tr>
+</table>
+
+Final image <img src="final.png"/>
+

doc/design/selective_masking/p5/README.md

@@ -0,0 +1,67 @@
+# Selective masking case 5
+
+<table border=1>
+      <tr>
+        <td>Layers</td>
+        <td><b>Polys</b></td>
+        <td><b>Lines</b></td>
+        <td><b>Points</b></td>
+        <td><b>Labels</b></td>
+      </tr>
+      <tr>
+        <td>Symbol layers</td>
+        <td></td>
+        <td><b>0</b>: black roads<br/><b>1</b>: yellow roads</td>
+        <td><b>0</b>: orange circles<br/><b>1</b>: marker mask, bigger circle<br/>(only visible in mask image)</td>
+        <td></td>
+      </tr>
+      <tr>
+        <td>Masks</td>
+        <td></td>
+        <td></td>
+        <td><b>Points/1</b> masks <b>Lines/0</b></td>
+        <td>Buffer masks <b>Lines/1</b></td>
+      </tr>
+      <tr>
+        <td>First pass</td>
+        <td><img src="first_pass_0.png"/></td>
+        <td><img src="first_pass_1.png"/></td>
+        <td><img src="first_pass_2.png"/></td>
+        <td><img src="labels.png"/></td>
+      </tr>
+      <tr>
+        <td>Mask image<br/>(still in first pass)</td>
+        <td></td>
+        <td></td>
+        <td><img src="first_pass_2_mask.png"/></td>
+        <td><img src="labels_mask.png"/></td>
+      </tr>
+    </table>
+Warning message:<br/>
+<b>Layer lines_ef106202_b4e1_49c4_a3d0_b65eb8bbb6d6 : Different sets of symbol layers are masked by different sources ! Only one (arbitrary) set will be retained !
+</b>
+<table border=1>
+      <tr>
+        <td>Second pass</td>
+        <td><b>Lines</b> without <b>1</b><br/><img src="second_1.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>Composition with merged mask</td>
+        <td><img src="mask_1.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>Second pass image <b>inside</b> mask</td>
+        <td><img src="second_1_a.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>First pass image <b>oustide</b> mask<br/></td>
+        <td><img src="second_1_first_pass_2.png" style="vertical-align:middle"/></td>
+      </tr>
+      <tr>
+        <td>Updated first pass image</td>
+        <td><img src="second_1_first_pass_3.png" style="vertical-align:middle"/></td>
+      </tr>
+</table>
+
+Final image <img src="final.png"/>
+