C API: document sk_matrix_t

Change-Id: I8f35868de6ef7d541cc3c9bcaddad4871bf8d6eb
Reviewed-on: https://skia-review.googlesource.com/2590
Commit-Queue: Hal Canary <halcanary@google.com>
Reviewed-by: Mike Reed <reed@google.com>

diff --git a/include/c/sk_types.h b/include/c/sk_types.h
index 344259f..679e106 100644 (file)
--- a/include/c/sk_types.h
+++ b/include/c/sk_types.h
@@ -113,6 +113,59 @@ typedef struct {
     float   bottom;
 } sk_rect_t;
 
+/**
+    The sk_matrix_t struct holds a 3x3 perspective matrix for
+    transforming coordinates:
+
+        (X,Y) = T[M]((x,y))
+        X = (M[0] * x + M[1] * y + M[2]) / (M[6] * x + M[7] * y + M[8]);
+        Y = (M[3] * x + M[4] * y + M[5]) / (M[6] * x + M[7] * y + M[8]);
+
+    Therefore, the identity matrix is
+
+        sk_matrix_t identity = {{1, 0, 0,
+                                 0, 1, 0,
+                                 0, 0, 1}};
+
+    A matrix that scales by sx and sy is:
+
+        sk_matrix_t scale = {{sx, 0,  0,
+                              0,  sy, 0,
+                              0,  0,  1}};
+
+    A matrix that translates by tx and ty is:
+
+        sk_matrix_t translate = {{1, 0, tx,
+                                  0, 1, ty,
+                                  0, 0, 1}};
+
+    A matrix that rotates around the origin by A radians:
+
+        sk_matrix_t rotate = {{cos(A), -sin(A), 0,
+                               sin(A),  cos(A), 0,
+                               0,       0,      1}};
+
+    Two matrixes can be concatinated by:
+
+         void concat_matrices(sk_matrix_t* dst,
+                             const sk_matrix_t* matrixU,
+                             const sk_matrix_t* matrixV) {
+            const float* u = matrixU->mat;
+            const float* v = matrixV->mat;
+            sk_matrix_t result = {{
+                    u[0] * v[0] + u[1] * v[3] + u[2] * v[6],
+                    u[0] * v[1] + u[1] * v[4] + u[2] * v[7],
+                    u[0] * v[2] + u[1] * v[5] + u[2] * v[8],
+                    u[3] * v[0] + u[4] * v[3] + u[5] * v[6],
+                    u[3] * v[1] + u[4] * v[4] + u[5] * v[7],
+                    u[3] * v[2] + u[4] * v[5] + u[5] * v[8],
+                    u[6] * v[0] + u[7] * v[3] + u[8] * v[6],
+                    u[6] * v[1] + u[7] * v[4] + u[8] * v[7],
+                    u[6] * v[2] + u[7] * v[5] + u[8] * v[8]
+            }};
+            *dst = result;
+        }
+*/
 typedef struct {
     float   mat[9];
 } sk_matrix_t;