From: Matthias Clasen <mclasen@redhat.com>
Date: Tue, 30 May 2023 03:45:06 +0000 (-0400)
Subject: gltexturebuilder: Document format expectations
X-Git-Tag: archive/raspbian/4.12.3+ds-1+rpi1~1^2^2^2~22^2~1^2~200^2
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=4f6d7c69a1bd7ef4b7af337152ca2bc7892c0136;p=gtk4.git

gltexturebuilder: Document format expectations

Provide some details about storage and alpha handling.
---

diff --git a/gdk/gdkgltexturebuilder.c b/gdk/gdkgltexturebuilder.c
index ec885fea72..4b58be475b 100644
--- 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.