From cfa2d1abf780d3013574a3ec675c7e726c2034d1 Mon Sep 17 00:00:00 2001
From: Niels De Graef <nielsdegraef@gmail.com>
Date: Wed, 22 Apr 2020 16:02:08 +0200
Subject: [PATCH] shaped-texture: Add a few explanatory comments

One of the important classes in Mutter's handling of client textures is
the `MetaShapedTexture`. This commit adds a few gtk-doc comments which
explain its purpose, with special attention to the viewport methods.

https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1210
---
 src/compositor/meta-shaped-texture.c | 61 +++++++++++++++++++++++++++-
 1 file changed, 60 insertions(+), 1 deletion(-)

diff --git a/src/compositor/meta-shaped-texture.c b/src/compositor/meta-shaped-texture.c
index 8e86693fc..2646ac2a2 100644
--- a/src/compositor/meta-shaped-texture.c
+++ b/src/compositor/meta-shaped-texture.c
@@ -22,7 +22,12 @@
 /**
  * SECTION:meta-shaped-texture
  * @title: MetaShapedTexture
- * @short_description: An actor to draw a masked texture.
+ * @short_description: A ClutterContent which draws a shaped texture
+ *
+ * A MetaShapedTexture draws a #CoglTexture (often provided from a client
+ * surface) in such a way that it matches any required transformations that
+ * give its final shape, such as a #MetaMonitorTransform, y-invertedness, or a
+ * crop-and-scale operation.
  */
 
 #include "config.h"
@@ -1122,6 +1127,24 @@ meta_shaped_texture_set_transform (MetaShapedTexture    *stex,
   invalidate_size (stex);
 }
 
+/**
+ * meta_shaped_texture_set_viewport_src_rect:
+ * @stex: A #MetaShapedTexture
+ * @src_rect: The viewport source rectangle
+ *
+ * Sets the viewport area that can be used to crop the original texture. The
+ * cropped result can then be optionally scaled afterwards using
+ * meta_shaped_texture_set_viewport_dst_size() as part of a crop-and-scale
+ * operation.
+ *
+ * Note that the viewport's geometry should be provided in the coordinate space
+ * of the texture received by the client, which might've been scaled as noted by
+ * meta_shaped_texture_set_buffer_scale().
+ *
+ * %NULL is an invalid value for @src_rect. Use
+ * meta_shaped_texture_reset_viewport_src_rect() if you want to remove the
+ * cropping source rectangle.
+ */
 void
 meta_shaped_texture_set_viewport_src_rect (MetaShapedTexture *stex,
                                            graphene_rect_t   *src_rect)
@@ -1150,6 +1173,21 @@ meta_shaped_texture_reset_viewport_src_rect (MetaShapedTexture *stex)
   invalidate_size (stex);
 }
 
+/**
+ * meta_shaped_texture_set_viewport_dst_size:
+ * @stex: #MetaShapedTexture
+ * @dst_width: The final viewport width (> 0)
+ * @dst_width: The final viewport height (> 0)
+ *
+ * Sets a viewport size on @stex of the given @width and @height, which may
+ * lead to scaling the texture. If you need to have cropping, use
+ * meta_shaped_texture_set_viewport_src_rect() first, after which the scaling
+ * stemming from this method will be applied.
+ *
+ * If you no longer want to have any scaling, use
+ * meta_shaped_texture_reset_viewport_dst_size() to clear the current
+ * parameters.
+ */
 void
 meta_shaped_texture_set_viewport_dst_size (MetaShapedTexture *stex,
                                            int                dst_width,
@@ -1445,6 +1483,15 @@ meta_shaped_texture_new (void)
   return g_object_new (META_TYPE_SHAPED_TEXTURE, NULL);
 }
 
+/**
+ * meta_shaped_texture_set_buffer_scale:
+ * @stex: A #MetaShapedTexture
+ * @buffer_scale: The scale that should be applied to coorsinate space
+ *
+ * Instructs @stex to intepret the geometry of the input texture by scaling it
+ * with @buffer_scale. This means that the #CoglTexture that is provided by a
+ * client is alreay scaled by that factor.
+ */
 void
 meta_shaped_texture_set_buffer_scale (MetaShapedTexture *stex,
                                       int                buffer_scale)
@@ -1467,6 +1514,12 @@ meta_shaped_texture_get_buffer_scale (MetaShapedTexture *stex)
   return stex->buffer_scale;
 }
 
+/**
+ * meta_shaped_texture_get_width:
+ * @stex: A #MetaShapedTexture
+ *
+ * Returns: The final width of @stex after its shaping operations are applied.
+ */
 int
 meta_shaped_texture_get_width (MetaShapedTexture *stex)
 {
@@ -1477,6 +1530,12 @@ meta_shaped_texture_get_width (MetaShapedTexture *stex)
   return stex->dst_width;
 }
 
+/**
+ * meta_shaped_texture_get_height:
+ * @stex: A #MetaShapedTexture
+ *
+ * Returns: The final height of @stex after its shaping operations are applied.
+ */
 int
 meta_shaped_texture_get_height (MetaShapedTexture *stex)
 {