[cairo] Adding cairo_shear and family

[Behdad Esfahbod]

M Joonas Pihlaja wrote:
> 
> On Sun, 11 Jan 2009, Behdad Esfahbod wrote:
> 
>> I think the API is mainly designed to be used with either nonzero sx
>> or sy,
>> not both.
> 
> Sure.  Still, the docs shouldn't say it's doing an x-shear and a y-shear
> at the same time because the operation can't be represented as any kind
> of shearing at all (it doesn't preserve area unless one of sx, sy is zero.)

The docs should say "for a shear in the X direction, use sy=0, for a shear in
the Y direction, use sx=0".

>>  I like having the exact matrix in there.  We don't do that for
>> rotate, scale, and translate because they are obvious.
> 
> During a discussion on #cairo a while back I was told that we don't use
> matrices in the docs because that would nail down a specific
> interpretation for the action of the CTM:  Is it from the left on column
> vectors vs. from the right on row vectors? Right now there's no place in
> the docs that suggests either interpretation, so even just saying that
> cairo_shear() multiplies the CTM by some other matrix is ambiguous.

Can't buy that.  We already have cairo_transform(), and the matrix is a public
type.  I'm not advertising use of matrix notation, just document what the xx,
xy, yx, yy, x0, and y0 values of the transform matrix for a shear are.

>> I don't like the idea of separate calls.
> 
> Me neither, but it's no fun having an operation that does something else
> that what it says in the name either. ;)
> 
> How about something like
> 
>   cairo_shear(cr, angle, scale);
> 
> This would shear by the given amount along the axis given as an angle
> from the x-axis.

Nah.  Why not have cairo_scale take an angle too?  Really.  The proposal as
was made originally is just fine.  It doesn't preserve area.  So what?
Neither does cairo_scale!

behdad

> Cheers,
> 
> Joonas
>