>From bb51fbf18d8e9fcb7f65afef49d802b9fc768149 Mon Sep 17 00:00:00 2001
From: Alan Third <address@hidden>
Date: Tue, 11 Jun 2019 20:31:24 +0100
Subject: [PATCH] Document image transforms

* doc/lispref/display.texi (Image Descriptors): Document :crop and
update :rotation.
* src/image.c: Describe the image transform matrix layout.
---
 doc/lispref/display.texi | 23 ++++++++++++++++++++++-
 src/image.c              | 16 ++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 93c5217c36..d29e98a8fd 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5181,8 +5181,29 @@ Image Descriptors
 specified, the height/width will be adjusted by the specified scaling
 factor.
 
+@item :crop @var{geometry}
+This should be a list of the form @code{(@var{width} @var{height}
+@var{x} @var{y})}.  If @var{width} and @var{height} are positive
+numbers they specify the width and height of the cropped image.  If
+@var{x} is a positive number it specifies the offset of the cropped
+area from the left of the original image, and if negative the offset
+from the right. If @var{y} is a positive number it specifies the
+offset from the top of the original image, and if negative from the
+bottom. If @var{x} or @var{y} are @code{nil} or unspecified the crop
+area will be centred on the original image.
+
+If the crop area is outside or overlaps the edge of the image it will
+be reduced to exclude any areas outside of the image.  This means it
+is not possible to use @code{:crop} to increase the size of the image
+by entering large @var{width} or @var{height} values.
+
+Cropping is performed after scaling but before rotation.
+
 @item :rotation @var{angle}
-Specifies a rotation angle in degrees.
+Specifies a rotation angle in degrees.  Only multiples of 90 degrees
+are supported, unless the image type is @code{imagemagick}.  Positive
+values rotate clockwise, negative values anti-clockwise.  Rotation is
+performed after scaling and cropping.
 
 @item :index @var{frame}
 @xref{Multi-Frame Images}.
diff --git a/src/image.c b/src/image.c
index 86f8e8f4bb..12e35e4527 100644
--- a/src/image.c
+++ b/src/image.c
@@ -1967,6 +1967,22 @@ compute_image_size (size_t width, size_t height,
 }
 #endif /* HAVE_IMAGEMAGICK || HAVE_NATIVE_TRANSFORMS */
 
+/* image_set_rotation, image_set_crop, image_set_size and
+   image_set_transform use affine transformation matrices to perform
+   various transforms on the image.  The matrix is a 2D array of
+   doubles.  It is laid out like this:
+
+   m[0][0] = m11 | m[0][1] = m12 | m[0][2] = tx
+   --------------+---------------+-------------
+   m[1][0] = m21 | m[1][1] = m22 | m[1][2] = ty
+   --------------+---------------+-------------
+   m[2][0] = 0   | m[2][1] = 0   | m[2][2] = 1
+
+   tx and ty represent translations, m11 and m22 represent scaling
+   transforms and m21 and m12 represent shear transforms. Some
+   graphics toolkits don't require the third row, however it is
+   necessary for multiplication.  */
+
 typedef double matrix3x3[3][3];
 
 static void
-- 
2.21.0