Overhaul of the newly-wrapped Matrix API (+documentation)

	* cairomm/matrix.cc:
	* cairomm/matrix.h: Add documentation for newly-wrapped matrix functions.
	Also, changed how the cairo_matrix_init_XXX() functions are wrapped.
	Initially I had basically wrapped them directly (as Matrix::init_XXX()),
	however, on the advice of Chong Kai Xiong (descender) on IRC, I have moved
	these into standalone 'generator' functions:
		- scaled_matrix()
		- translation_matrix()
		- rotation_matrix()
		- identity_matrix()
	* tests/test-font-face.cc:
	* tests/test-matrix.cc: modify the tests for the change in API.  The new API
	does make things much more comfortable to use.

2 files changed, 53 insertions, 51 deletions

diff --git a/tests/test-font-face.cc b/tests/test-font-face.cc
index d18fd31..57a4a99 100644
--- a/tests/test-font-face.cc
+++ b/tests/test-font-face.cc
@@ -23,8 +23,6 @@ using namespace boost::unit_test;
 #include <cairomm/win32_font.h>
 #endif // CAIRO_HAS_WIN32_FONT
 
-static Cairo::Matrix identity_matrix;
-
 void
 test_create_toy ()
 {
@@ -103,10 +101,8 @@ void test_user_font_callbacks_ptr()
   font->set_init_func(sigc::ptr_fun(my_init));
   font->set_unicode_to_glyph_func(sigc::ptr_fun(my_unicode_to_glyph));
   font->set_render_glyph_func(sigc::ptr_fun(my_render_glyph));
-  Cairo::Matrix font_matrix;
-  font_matrix.init_scale(10, 10);
   Cairo::RefPtr<Cairo::ScaledFont> scaled_font =
-    Cairo::ScaledFont::create(font, font_matrix, identity_matrix,
+    Cairo::ScaledFont::create(font, Cairo::scaled_matrix(10, 10), Cairo::identity_matrix(),
                               Cairo::FontOptions());
   BOOST_CHECK (init_call_count > 0);
   Cairo::RefPtr<Cairo::ImageSurface> surface =
@@ -130,10 +126,8 @@ void test_user_font_callbacks_ptr_text()
   font->set_init_func(sigc::ptr_fun(my_init));
   font->set_render_glyph_func(sigc::ptr_fun(my_render_glyph));
   font->set_text_to_glyphs_func(sigc::ptr_fun(my_text_to_glyphs));
-  Cairo::Matrix font_matrix;
-  font_matrix.init_scale(10, 10);
   Cairo::RefPtr<Cairo::ScaledFont> scaled_font =
-    Cairo::ScaledFont::create(font, font_matrix, identity_matrix,
+    Cairo::ScaledFont::create(font, Cairo::scaled_matrix(10, 10), Cairo::identity_matrix(),
                               Cairo::FontOptions());
   BOOST_CHECK (init_call_count > 0);
   Cairo::RefPtr<Cairo::ImageSurface> surface =
@@ -184,10 +178,8 @@ void test_user_font_callbacks_mem()
                                                 &UserFontCallbacks::unicode_to_glyph));
   font->set_render_glyph_func(sigc::mem_fun(&callbacks,
                                             &UserFontCallbacks::render_glyph));
-  Cairo::Matrix font_matrix;
-  font_matrix.init_scale(10, 10);
   Cairo::RefPtr<Cairo::ScaledFont> scaled_font =
-    Cairo::ScaledFont::create(font, font_matrix, identity_matrix,
+    Cairo::ScaledFont::create(font, Cairo::scaled_matrix(10, 10), Cairo::identity_matrix(),
                               Cairo::FontOptions());
   BOOST_CHECK (UserFontCallbacks::init_call_count > 0);
   Cairo::RefPtr<Cairo::ImageSurface> surface =
@@ -232,12 +224,10 @@ void test_user_font_callbacks_exception()
   // through C code.  However, due to the exception being thrown, the create()
   // function will fail and throw a new exception.  So if the executable doesn't
   // abort, we should get an exception here.
-  Cairo::Matrix font_matrix;
-  font_matrix.init_scale(10, 10);
   Cairo::RefPtr<Cairo::ScaledFont> scaled_font;
   BOOST_CHECK_THROW (scaled_font = Cairo::ScaledFont::create(font,
-                                                             font_matrix,
-                                                             identity_matrix,
+                                                             Cairo::scaled_matrix(10, 10),
+                                                             Cairo::identity_matrix(),
                                                              Cairo::FontOptions()),
                      Cairo::logic_error);
   BOOST_CHECK (init_exception_call_count > 0);
@@ -248,8 +238,8 @@ void test_user_font_callbacks_exception()
   font->set_render_glyph_func(sigc::ptr_fun(my_render_glyph_exception));
   font->set_unicode_to_glyph_func(sigc::ptr_fun(my_unicode_to_glyph_exception));
   BOOST_CHECK_NO_THROW (scaled_font = Cairo::ScaledFont::create(font,
-                                                                font_matrix,
-                                                                identity_matrix,
+                                                                Cairo::scaled_matrix(10, 10),
+                                                                Cairo::identity_matrix(),
                                                                 Cairo::FontOptions()))
   Cairo::RefPtr<Cairo::ImageSurface> surface =
     Cairo::ImageSurface::create(Cairo::FORMAT_ARGB32, 100, 100);
@@ -282,12 +272,10 @@ void test_user_font_replace_callback()
   // now replace the init function with my_init2 and make sure that the 2nd
   // function is called, not the first
   font->set_init_func(sigc::ptr_fun(my_init2));
-  Cairo::Matrix font_matrix;
-  font_matrix.init_scale(10, 10);
   Cairo::RefPtr<Cairo::ScaledFont> scaled_font;
   BOOST_CHECK_NO_THROW (scaled_font = Cairo::ScaledFont::create(font,
-                                                                font_matrix,
-                                                                identity_matrix,
+                                                                Cairo::scaled_matrix(10, 10),
+                                                                Cairo::identity_matrix(),
                                                                 Cairo::FontOptions()))
   BOOST_CHECK (init2_call_count > 0);
   BOOST_CHECK_EQUAL (init_call_count, 0);
diff --git a/tests/test-matrix.cc b/tests/test-matrix.cc
index 6452bd8..acc9708 100644
--- a/tests/test-matrix.cc
+++ b/tests/test-matrix.cc
@@ -5,18 +5,37 @@ using namespace boost::unit_test;
 
 #include <cairomm/matrix.h>
 
+// this is necessary for BOOST_CHECK_EQUAL, but there's no equivalent in the C
+// API, so I'm reluctant to include it in cairomm right now
+bool operator==(const Cairo::Matrix& A, const Cairo::Matrix& B)
+{
+  return
+    A.xx == B.xx &&
+    A.yx == B.yx &&
+    A.xy == B.xy &&
+    A.yy == B.yy &&
+    A.x0 == B.x0 &&
+    A.y0 == B.y0;
+}
+
+// this is necessary for BOOST_CHECK_EQUAL to work but doesn't seem useful
+// enough to put in the actual implementation
+std::ostream& operator<<(std::ostream& out, const Cairo::Matrix& matrix)
+{
+  return out << "[ "
+    << matrix.xx << ", "
+    << matrix.yx << ", "
+    << matrix.xy << ", "
+    << matrix.yy << ", "
+    << matrix.x0 << ", "
+    << matrix.y0 << " ]";
+}
+
 void test_constructors()
 {
   cairo_matrix_t c_identity;
   cairo_matrix_init_identity(&c_identity);
-  Cairo::Matrix cpp_identity;
-
-  BOOST_CHECK_EQUAL(c_identity.xx,  cpp_identity.xx);
-  BOOST_CHECK_EQUAL(c_identity.yx,  cpp_identity.yx);
-  BOOST_CHECK_EQUAL(c_identity.xy,  cpp_identity.xy);
-  BOOST_CHECK_EQUAL(c_identity.yy,  cpp_identity.yy);
-  BOOST_CHECK_EQUAL(c_identity.x0,  cpp_identity.x0);
-  BOOST_CHECK_EQUAL(c_identity.y0,  cpp_identity.y0);
+  BOOST_CHECK_EQUAL(c_identity, Cairo::identity_matrix());
 
   // nonsense values, just for testing
   const double xx=1, yx=2, xy=3, yy=5, x0=6, y0=7;
@@ -24,19 +43,13 @@ void test_constructors()
   cairo_matrix_init(&c_matrix, xx, yx, xy, yy, x0, y0);
   Cairo::Matrix cpp_matrix(xx, yx, xy, yy, x0, y0);
 
-  BOOST_CHECK_EQUAL(c_matrix.xx, cpp_matrix.xx);
-  BOOST_CHECK_EQUAL(c_matrix.yx, cpp_matrix.yx);
-  BOOST_CHECK_EQUAL(c_matrix.xy, cpp_matrix.xy);
-  BOOST_CHECK_EQUAL(c_matrix.yy, cpp_matrix.yy);
-  BOOST_CHECK_EQUAL(c_matrix.x0, cpp_matrix.x0);
-  BOOST_CHECK_EQUAL(c_matrix.y0, cpp_matrix.y0);
+  BOOST_CHECK_EQUAL(c_matrix, cpp_matrix);
 }
 
 void test_invert()
 {
   // test a valid matrix
-  Cairo::Matrix identity;
-  BOOST_CHECK_NO_THROW(identity.invert());
+  BOOST_CHECK_NO_THROW(Cairo::identity_matrix().invert());
   // check a degenerate matrix
   Cairo::Matrix degenerate(0,0,0,0,0,0);
   BOOST_CHECK_THROW(degenerate.invert(), std::logic_error);
@@ -51,27 +64,27 @@ static void foo(cairo_matrix_t* matrix)
 void test_cast()
 {
   // make sure that we can cast between C++ and C types without ill effect
-  Cairo::Matrix matrix;
-  cairo_matrix_t casted = (cairo_matrix_t) matrix;
+  Cairo::Matrix matrix = Cairo::identity_matrix();
+  cairo_matrix_t casted = (cairo_matrix_t) Cairo::identity_matrix();
   // check that it's equal to the identity matrix
   cairo_matrix_t identity;
   cairo_matrix_init_identity(&identity);
 
-  BOOST_CHECK_EQUAL(casted.xx, identity.xx);
-  BOOST_CHECK_EQUAL(casted.yx, identity.yx);
-  BOOST_CHECK_EQUAL(casted.xy, identity.xy);
-  BOOST_CHECK_EQUAL(casted.yy, identity.yy);
-  BOOST_CHECK_EQUAL(casted.x0, identity.x0);
-  BOOST_CHECK_EQUAL(casted.y0, identity.y0);
+  BOOST_CHECK_EQUAL(casted, identity);
 
   // pass C++ type as an argument to C
   foo(&matrix);
-  BOOST_CHECK_EQUAL(matrix.xx, test_matrix->xx);
-  BOOST_CHECK_EQUAL(matrix.yx, test_matrix->yx);
-  BOOST_CHECK_EQUAL(matrix.xy, test_matrix->xy);
-  BOOST_CHECK_EQUAL(matrix.yy, test_matrix->yy);
-  BOOST_CHECK_EQUAL(matrix.x0, test_matrix->x0);
-  BOOST_CHECK_EQUAL(matrix.y0, test_matrix->y0);
+  BOOST_CHECK_EQUAL(matrix, *test_matrix);
+}
+
+void test_multiply()
+{
+  Cairo::Matrix A = Cairo::scaled_matrix(2, 4);
+  Cairo::Matrix B = Cairo::translation_matrix(5.3, 1.2);
+  Cairo::Matrix C = A * B;
+  Cairo::Matrix D;
+  D.multiply(A, B);
+  BOOST_CHECK_EQUAL(C, D);
 }
 
 test_suite*
@@ -82,6 +95,7 @@ init_unit_test_suite(int /*argc*/, char** /*argv*/)
   test->add (BOOST_TEST_CASE (&test_constructors));
   test->add (BOOST_TEST_CASE (&test_invert));
   test->add (BOOST_TEST_CASE (&test_cast));
+  test->add (BOOST_TEST_CASE (&test_multiply));
 
   return test;
 }