Changes for Merge consecutive rasterizations

samtygier · samtygier · commit 8e9c89a53be3 · 2020-05-03T17:33:52.000+01:00
Document user and api changes.
diff --git a/doc/api/api_changes/2020-04-26-merged-rasterizations.rst b/doc/api/api_changes/2020-04-26-merged-rasterizations.rst
@@ -0,0 +1,15 @@
+Consecutive rasterized draws now merged
+---------------------------------------
+
+Tracking of depth of raster draws has moved from
+`.backend_mixed.MixedModeRenderer.start_rasterizing` and
+`.backend_mixed.MixedModeRenderer.stop_rasterizing` into
+`.artist.allow_rasterization`. This means the start and stop functions are
+only called when the rasterization actually needs to be started and stopped.
+
+The output of vector backends will change in the case that rasterized
+elements are merged. This should not change the appearance of outputs.
+
+The renders in 3rd party backends are now expected to have
+``self._raster_depth`` and ``self._rasterizing`` initialized to ``0`` and
+``False`` respectively.
diff --git a/doc/users/next_whats_new/2020-04-26-merged-rasterizations.rst b/doc/users/next_whats_new/2020-04-26-merged-rasterizations.rst
@@ -0,0 +1,13 @@
+Consecutive rasterized draws now merged
+---------------------------------------
+
+Elements of a vector output can be individually set to rasterized, using
+the ``rasterized`` keyword, or `~.artist.Artist.set_rasterized()`. This can
+be useful to reduce file sizes. For figures with multiple raster elements
+they are now automatically merged into a smaller number of bitmaps where
+this will not effect the visual output. For cases with many elements this
+can result in significantly smaller file sizes.
+
+To ensure this happens do not place vector elements between raster ones.
+
+To inhibit this merging set ``Figure.suppressComposite`` to True.
