[cairo] [PATCH] add functional matrix-returning methods to Pycairo

[Steve]

On Wed, 2010-05-05 at 09:35 -0700, Stuart Axon <stuaxo2 at yahoo.com>
wrote:
> 
> This isn't my patch, but I found it while googling for cairo Matrix
> stuff.
> It looks like a good idea, just sent to the wrong list AFAICT:
> 
> I've dropped him an email suggesting to send it here, but haven't
> heard anything back yet.
> 
> http://www.gossamer-threads.com/lists/python/python/826029
> ---- And theres the message, in case you don't want to click on the
>      above link to the message ----
> from: ldo at geek-central.gen.nz <Lawrence D?Oliveiro>
> 
> 
> I find the matrix methods in Pycairo to be an annoying hodge-podge of 
> ones that 
> overwrite the Matrix object in-place (init_rotate, invert) 
> versus ones 
> that concatenate additional transformations (rotate, scale, 
> translate) versus ones that return new matrices without modifying 
> the 
> originals (multiply). 

The 2 types "overwrite Matrix in-place" and "concatenate additional
transformations" look like similar operations to me - in-place
operations. So you have 2 not 3 basic operations - mutable (in-place)
operations and immutable (functional) operations.

init_rotate does not overwrite the Matrix object in-place, it constructs
a new Matrix.

The matrix operations can be grouped like this.
Constructors:
cairo.Matrix()
cairo.Matrix.init_rotate()

Mutable operations:
cairo.Matrix.invert()
cairo.Matrix.rotate()
cairo.Matrix.scale()
cairo.Matrix.translate()

Immutable operations:
cairo.Matrix.multiply()

So the Matrix object is mutable, it has 2 constructors and 4 mutable
operations. The only exception is Matrix.multiply which returns a new
Matrix.


> Myself, I prefer methods that always 
> return new matrices. This allows 
> for a more functional style of 
> programming, e.g. given 
> 
> m = cairo.Matrix() 
> 
> then 
> 
> m2 = m.translation(-10, -10) * m.rotation(math.pi / 4) * 
> m.translation(10, 10) 
> 
> concisely expresses rotation by 90?? 
> about the centre (10, 10). 

I agree that a functional interface would have been much nicer.


> Herewith a patch to add such methods to 
> the cairo.Matrix class. Note 
> that the names (inverse, rotation, scaling, translation) are nouns, 
> to reflect the fact that they don't perform the actions, but they 
> return Matrix objects that do. 

Pycairo is a binding to the C cairo library. It is not an independent
graphics library which is free to redefine all of its functions to fix
API design mistakes. It needs to remain consistent to the underlying
cairo C functions to make it possible to port cairo code from C (and
other languages) to Python. So redefining all the matrix operations in
one cairo language binding would cause a lot of confusion and problems
for people porting cairo code from other languages, so is not a good
idea.

Steve