On Tue, Jun 11, 2019 at 08:10:41AM +0300, Eli Zaretskii wrote:
>   . The :crop parameter of image specs doesn't seem to be documented anywhere.  We previously supported it without documenting only for ImageMagick, which was already a problem; now it's a much bigger problem.
>   . The ELisp manual doesn't mention that :rotation is generally supported only for multiples of 90 deg, except if ImageMagick is available.
>   . The transformation matrix used by the implementation is not described; one needs to guess what its components mean, or search the Internet for docs of XRender and/or Cairo, which are generally not helpful enough, especially the XRender one.

I hope the attached patch goes some way to solving these issues.

>   . There are no tests, AFAICT.  We should have a simple manual test
>   which could be used to exercise all of the transformations,
>   separately and in combinations.  I wonder how did the people who
>   worked on the implementations for different platforns verify that
>   the results are consistent, especially given the lack of
>   documentation (e.g., is rotation of 90 deg clockwise or
>   counter-clockwise?).

Is there some example of how to write a manual test like this?

>  . I question the wisdom of the current definition of
>  image-transforms-p. First, it returns a simple yes/no value, under
>  the assumption that either all of the transformations are supported
>  or none of them; IMO, it is better to return a list of supported
>  capabilities instead. Second, it doesn't distinguish between
>  capability to rotate by arbitrary angles and by 90 deg multiples
>  only, which will require Lisp programs to test for ImageMagick,
>  something that undermines the very raison d'etre of this function

My hope was that MS Windows support for affine transform matrices
would be forthcoming quite quickly in which case there would be no
need to differentiate between the different types of transform (if one
is supported, they all are), but perhaps that’s hoping for too much. :)

I’ve been thinking a bit about the idea of returning some sort of
capabilities list and it seems quite neat. We could perhaps roll some
of the imagemagick-types stuff into it.

I’ll look into it further.

-- 
Alan Third