From 4f6d7c69a1bd7ef4b7af337152ca2bc7892c0136 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 29 May 2023 23:45:06 -0400 Subject: [PATCH] gltexturebuilder: Document format expectations Provide some details about storage and alpha handling. --- gdk/gdkgltexturebuilder.c | 9 +++++++++ 1 file changed, 9 insertions(+) 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.