gltexturebuilder: Document format expectations

Provide some details about storage and alpha handling.

diff --git a/gdk/gdkgltexturebuilder.c b/gdk/gdkgltexturebuilder.c
index ec885fea728d7f8c3d7256f80b4aaf81320b9d0d..4b58be475b35f25ac0e7ce910ae509d40b9dffb1 100644 (file)
--- a/gdk/gdkgltexturebuilder.c
+++ b/gdk/gdkgltexturebuilder.c
@@ -644,6 +644,15 @@ gdk_gl_texture_builder_get_format (GdkGLTextureBuilder *self)
  * The format is the preferred format the texture data should be downloaded to. The
  * format must be supported by the GL version of [property@Gdk.GLTextureBuilder:context].
  *
+ * GDK's texture download code assumes that the format corresponds to the storage
+ * parameters of the GL texture in an obvious way. For example, a format of
+ * `GDK_MEMORY_R16G16B16A16_PREMULTIPLIED` is expected to be stored as `GL_RGBA16`
+ * texture, and `GDK_MEMORY_G8A8` is expected to be stored as `GL_RG8` texture.
+ *
+ * GDK allows GL textures to have unpremultiplied alpha, but GSK's GL renderer can't
+ * currently handle such textures. Non-RGBA textures need to have swizzling parameters
+ * set up properly to be usable in GSK's shaders.
+ *
  * Setting the right format is particularly useful when using high bit depth textures
  * to preserve the bit depth, to set the correct value for unpremultiplied textures
  * and to make sure opaque textures are treated as such.