Recompute :map when image :scale, :rotation, or :flip changes

Now, when transforming an image, its :map is recomputed to fit.
Image map coordinates are integers, so when computing :map,
coordinates are rounded.  To prevent an image from drifting from
its map after repeated transformations, 'create-image' now adds
a new image property :original-map, which is combined with the
image's transformation parameters to recompute :map.

* lisp/image.el (image-recompute-map-p): Add user option to
control whether :map is recomputed when an image is transformed.
(create-image): Create :map from :original-map and vice versa.
(image--delayed-change-size): Fix comment.
(image--change-size, image-rotate, image-flip-horizontally,
image-flip-vertically): Recompute image map after transformation
and mention 'image-recompute-map-p' in docstring.
(image--compute-map): Add function to compute a map from original
map.
(image--compute-original-map): Add function to compute an
original map from map.
(image--scale-map): Add function to scale a map based on :scale.
(image--rotate-map): Add function to rotate a map based on
:rotation.
(image--rotate-coord): Add function to rotate a map coordinate
pair.
(image--flip-map): Add function to flip a map based on :flip.
(image-increase-size, image-decrease-size, image-mouse-increase-size)
(image-mouse-decrease-size): Mention 'image-recompute-map-p' in
docstrings.
* etc/NEWS: Add NEWS entry.
* doc/lispref/display.texi (Image Descriptors): Document :original-map
and new user option 'image-recompute-map-p'.
* test/lisp/image-tests.el (image--compute-map-and-original-map):
Test 'image--compute-map' and 'image--compute-original-map'.
(image-tests--map-equal): Add equality predicate to compare image maps.
(image-create-image-with-map): Test that 'create-image' adds :map
and/or :original-map as appropriate.
(image-transform-map): Test functions related to transforming maps.
(Bug#69602)

1 files changed, 24 insertions, 0 deletions

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index beca470d68a..b497967c445 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -6056,6 +6056,30 @@ to make things match up, you should either specify @code{:scale 1.0}
 when creating the image, or use the result of
 @code{image-compute-scaling-factor} to compute the elements of the
 map.
+
+When an image's @code{:scale}, @code{:rotation}, or @code{:flip} is
+changed, @code{:map} will be recomputed based on the value of
+@code{:original-map} and the values of those transformation.
+
+@item :original-map @var{original-map}
+@cindex original image map
+This specifies the untransformed image map which will be used to
+recompute @code{:map} after the image's @code{:scale}, @code{:rotation},
+or @code{:flip} is changed.
+
+If @code{:original-map} is not specified when creating an image with
+@code{create-image}, it will be computed based on the supplied
+@code{:map}, as well as any of @code{:scale}, @code{:rotation}, or
+@code{:flip} which are non-nil.
+
+Conversely, if @code{:original-map} is specified but @code{:map} is not,
+@code{:map} will be computed based on @code{:original-map},
+@code{:scale}, @code{:rotation}, and @code{:flip}.
+
+@defopt image-recompute-map-p
+Set this user option to nil to prevent Emacs from automatically
+recomputing an image @code{:map} based on its @code{:original-map}.
+@end defopt
 @end table
 
 @defun image-mask-p spec &optional frame