rendernode, snapshot: Slightly expand color matrix docs

Based on reverse engineering the color node and contrary to my
expectations, the matrix/offset is expressed in, and applied to,
unpremultiplied colors. The colors are being explicitly
unpremultiplied, transformed according to the matrix/offset, and
premultiplied back (see color_matrix.glsl). The matrix is getting
transposed.

Also, copy the same blurb to the corresponding GtkSnapshot function.

Signed-off-by: Sergey Bugaev <bugaevc@gmail.com>

diff --git a/gsk/gskrendernodeimpl.c b/gsk/gskrendernodeimpl.c
index 54234992f99b8417982be1e40ca599c973224ffc..2758dff2a6a99c09626a60faa40e59d838ca33d1 100644 (file)
--- a/gsk/gskrendernodeimpl.c
+++ b/gsk/gskrendernodeimpl.c
@@ -3838,11 +3838,12 @@ gsk_color_matrix_node_class_init (gpointer g_class,
  * Creates a `GskRenderNode` that will drawn the @child with
  * @color_matrix.
  *
- * In particular, the node will transform the operation
+ * In particular, the node will transform colors by applying
  *
- *     pixel = color_matrix * pixel + color_offset
+ *     pixel = transpose(color_matrix) * pixel + color_offset
  *
- * for every pixel.
+ * for every pixel. The transformation operates on unpremultiplied
+ * colors, with color components ordered R, G, B, A.
  *
  * Returns: (transfer full) (type GskColorMatrixNode): A new `GskRenderNode`
  */

diff --git a/gtk/gtksnapshot.c b/gtk/gtksnapshot.c
index 23da5d621846bf71c03b8a9ae0a68ce1cbc918f4..4e16b6cb9548041aedd38859f6591c40b07555cb 100644 (file)
--- a/gtk/gtksnapshot.c
+++ b/gtk/gtksnapshot.c
@@ -647,6 +647,13 @@ gtk_snapshot_collect_color_matrix (GtkSnapshot      *snapshot,
  * Modifies the colors of an image by applying an affine transformation
  * in RGB space.
  *
+ * In particular, the colors will be transformed by applying
+ *
+ *     pixel = transpose(color_matrix) * pixel + color_offset
+ *
+ * for every pixel. The transformation operates on unpremultiplied
+ * colors, with color components ordered R, G, B, A.
+ *
  * The image is recorded until the next call to [method@Gtk.Snapshot.pop].
  */
 void