matrix: Update code docs for projective transform

Signed-off-by: Bryce Harrington <bryce@osg.samsung.com>

2 files changed, 17 insertions, 7 deletions

diff --git a/src/cairo-matrix.c b/src/cairo-matrix.c
index 2f0e439eb..21c717e04 100644
--- a/src/cairo-matrix.c
+++ b/src/cairo-matrix.c
@@ -54,13 +54,14 @@
  *
  * #cairo_matrix_t is used throughout cairo to convert between different
  * coordinate spaces.  A #cairo_matrix_t holds an affine transformation,
- * such as a scale, rotation, shear, or a combination of these.
+ * such as a scale, rotation, shear, or a combination of these, and can
+ * also hold a projective transformation.
  * The transformation of a point (<literal>x</literal>,<literal>y</literal>)
  * is given by:
  *
  * <programlisting>
- * x_new = xx * x + xy * y + x0;
- * y_new = yx * x + yy * y + y0;
+ * x_new = (xx * x + xy * y + x0) / (px * x + py * y + 1);
+ * y_new = (yx * x + yy * y + y0) / (px * x + py * y + 1);
  * </programlisting>
  *
  * The current transformation matrix of a #cairo_t, represented as a
@@ -108,6 +109,12 @@ slim_hidden_def(cairo_matrix_init_identity);
  *  y_new = yx * x + yy * y + y0;
  * </programlisting>
  *
+ * Note if any projective transformation had been applied to the
+ * matrix it is removed (i.e. px and py are set to 0).
+ *
+ * <programlisting>
+ * </programlisting>
+ *
  * Since: 1.0
  **/
 void
diff --git a/src/cairo.h b/src/cairo.h
index 7e73e1102..c6aa2670b 100644
--- a/src/cairo.h
+++ b/src/cairo.h
@@ -178,13 +178,16 @@ typedef struct _cairo_device cairo_device_t;
  * @yy: yy component of the affine transformation
  * @x0: X translation component of the affine transformation
  * @y0: Y translation component of the affine transformation
+ * @px: X component of the projective transformation
+ * @py: Y component of the projective transformation
  *
  * A #cairo_matrix_t holds an affine transformation, such as a scale,
- * rotation, shear, or a combination of those. The transformation of
- * a point (x, y) is given by:
+ * rotation, shear, or a combination of those, and a projective
+ * transformation. The transformation of a point (x, y) is given by:
+ *
  * <programlisting>
- *     x_new = xx * x + xy * y + x0;
- *     y_new = yx * x + yy * y + y0;
+ *     x_new = (xx * x + xy * y + x0) / (px * x + py * y + 1);
+ *     y_new = (yx * x + yy * y + y0) / (px * x + py * y + 1);
  * </programlisting>
  *
  * Since: 1.0