Add a color state node

When the compositing color state is linear, apply the freetype
stem darkening hack.

.gitlab-ci.yml

@@ -445,9 +445,8 @@ reference:
             --force-fallback-for=gdk-pixbuf,pango
             -Dintrospection=enabled
             -Ddocumentation=true
-            -Dgtk_doc=true
             -Dgdk-pixbuf:gtk_doc=true
-            -Dpango:gtk_doc=true
+            -Dpango:documentation=true
             -Dbuild-demos=false
             -Dbuild-examples=false
             -Dbuild-tests=false
@@ -460,6 +459,7 @@ reference:
     - mv _build/docs/reference/gdk/gdk4-wayland/ _reference/gdk4-wayland/
     - mv _build/docs/reference/gsk/gsk4/ _reference/gsk4/
     - mv _build/docs/reference/gtk/gtk4/ _reference/gtk4/
+    - mv _build/docs/reference/gtk/*.html _reference/gtk4/
     - mv _build/subprojects/pango/docs/Pango/ _reference/Pango/
     - mv _build/subprojects/pango/docs/PangoCairo/ _reference/PangoCairo/
     - mv _build/subprojects/pango/docs/PangoFc/ _reference/PangoFc/

.gitlab-ci/flatpak-build.sh

@@ -24,7 +24,7 @@ flatpak build ${builddir} meson \
                 -Dbuild-examples=false \
                 -Dintrospection=disabled \
                 -Dbuild-demos=true \
-                -Ddemo-profile=devel \
+                -Dprofile=devel \
                 _flatpak_build
 
 flatpak build --env=CI_COMMIT_SHORT_SHA=$CI_COMMIT_SHORT_SHA ${builddir} ninja -C _flatpak_build install

.gitlab-ci/test-msys2.sh

@@ -35,7 +35,11 @@ pacman --noconfirm -S --needed \
     mingw-w64-$MSYS2_ARCH-python-gobject \
     mingw-w64-$MSYS2_ARCH-shaderc \
     mingw-w64-$MSYS2_ARCH-vulkan \
-    mingw-w64-$MSYS2_ARCH-vulkan-headers
+    mingw-w64-$MSYS2_ARCH-vulkan-headers \
+    mingw-w64-$MSYS2_ARCH-libpng \
+    mingw-w64-$MSYS2_ARCH-libjpeg-turbo \
+    mingw-w64-$MSYS2_ARCH-libtiff \
+    mingw-w64-$MSYS2_ARCH-lcms2
 
 mkdir -p _ccache
 export CCACHE_BASEDIR="$(pwd)"

CONTRIBUTING.md

@@ -35,7 +35,7 @@ The issue tracker is meant to be used for actionable issues only.
 
 You should not open a new issue for security related questions.
 
-When in doubt, follow [security](https://security.gnome.org/).
+When in doubt, follow the process for [GNOME security issues](https://security.gnome.org/).
 
 ### Bug reports
 
@@ -144,33 +144,28 @@ $ git clone https://gitlab.gnome.org/yourusername/gtk.git
 $ cd gtk
 ```
 
-**Note**: if you plan to push changes to back to the main repository and
-have a GNOME account, you can skip the fork, and use the following instead:
-
-```sh
-$ git clone git@gitlab.gnome.org:GNOME/gtk.git
-$ cd gtk
-```
-
 To compile the Git version of GTK on your system, you will need to
 configure your build using Meson:
 
 ```sh
-$ meson _builddir .
-$ cd _builddir
-$ ninja
+$ meson setup _builddir .
+$ meson compile -C _builddir
 ```
 
 Typically, you should work on your own branch:
 
 ```sh
-$ git checkout -b your-branch
+$ git switch -C your-branch
 ```
 
 Once you've finished working on the bug fix or feature, push the branch
 to the Git repository and open a new merge request, to let the GTK
 maintainers review your contribution.
 
+**Important**: Do **not** attach a diff or a patch file to a GitLab issue.
+Patches cannot be reviewed, and do not not go through the CI pipeline. If
+you wish to submit your changes to GTK, always use a merge request.
+
 ### Code reviews
 
 Each contribution is reviewed by the core developers of the GTK project.
@@ -262,4 +257,4 @@ people committing to GTK to follow a few rules:
 
 If you have been contributing to GTK for a while and you don't have commit
 access to the repository, you may ask to obtain it following the [GNOME account
-process](https://wiki.gnome.org/AccountsTeam/NewAccounts).
+process](https://handbook.gnome.org/infrastructure/developer-access.html).

NEWS

@@ -1,6 +1,214 @@
-Overview of Changes in 4.15.0, xx-xx-xxxx
+Overview of Changes in 4.15.2, xx-xx-xxxx
 =========================================
 
+* GtkFileChooserWidget:
+ - Plug some memory leaks
+ - Make Ctrl-Shift-N create a new folder
+
+* CSS:
+ - Support color(), oklab(), etc (https://www.w3.org/TR/css-color-4/)
+ - Support color-mix() (https://www.w3.org/TR/css-color-5/)
+ - Support relative colors (https://www.w3.org/TR/css-color-5/)
+
+* Accessibility:
+ - Avoid markup when reading labels
+
+* GSK:
+ - Subset fonts when serializing node trees
+
+* Wayland:
+ - Use xdg-dialog protocol for attached dialogs
+
+* Windows:
+ - Build with UNICODE
+
+* Debugging:
+ - Add GTK_DEBUG=css for warning about deprecated css syntax
+
+* Tools:
+ - nodeparser: Add an extract command for data urls
+
+* Deprecations:
+ - CSS Color functions shade(), lighter(), darker(), alpha(), mix()
+
+* Translation updates:
+ Hebrew
+
+
+Overview of Changes in 4.15.1, 21-05-2024
+=========================================
+
+* GtkGraphicsOffload:
+ - Don't crash without a child
+
+* GtkSpinner:
+ - Don't animate when unmapped
+
+* CSS:
+ - Support the :root selector
+ - Support variables and custom properties (https://www.w3.org/TR/css-variables-1/)
+ - Implement math functions (https://www.w3.org/TR/css-values-4/)
+ - Support modern syntax and calc in rgb() and hsl()
+
+* Icontheme:
+ - Make symbolic svg loading more efficient
+ - Handle color-free symbolics more efficiently
+
+* Accessibility:
+ - Make the gtk-demo sidebar search more accessible
+ - Stop emitting focus events
+ - Realize child contexts when necessary
+
+* GDK:
+ - Support XDG_ACTIVATION_TOKEN
+ - dmabuf: Be more defensive when importing unknown formats to GL
+ - dmabuf: Use narrow range for YUV
+ - vulkan: Recreate swapchains when necessary or beneficial
+
+* GSK:
+ - Improve logging for GDK_DEBUG=offload
+ - Improve logging for GSK_DEBUG=renderer
+ - gpu: Warn about inefficient texture import
+ - gpu: Handle tiny offscreens correctly
+ - vulkan: Add profiler marks in various places
+ - vulkan: Fix a problem with imported dmabufs showing up black
+ - cairo: Speed up mask nodes, since we use them for symbolic icons
+
+* Wayland:
+ - Use wl_compositor version 6
+
+* X11:
+ - Implement a missing method
+
+* Build:
+ - Fix many ubsan warnings
+
+* Debugging:
+ - Show more texture details in the recorder
+ - Use GTK_DEBUG=css to see CSS deprecations
+
+* macOS:
+ - Fix problems with events handed back to the OS
+ - Respect GDK_DEBUG=default-settings
+ - Allow applictions to handle Dock > Quit
+
+* Deprecations:
+ - Use of @name colors in CSS
+
+* Translation updates:
+ Catalan
+ Georgian
+ Hungarian
+ Korean
+ Portuguese
+ Turkish
+
+
+Overview of Changes in 4.15.0, 21-04-2024
+=========================================
+
+This release changes the default GSK renderer to be Vulkan, on
+Wayland. Other platforms still use ngl.
+
+The intent of this change is to get wider testing and verify that
+Vulkan drivers are good enough for us to rely on. If significant
+problems show up, we will revert this change for 4.16.
+
+You can still override the renderer choice using the GSK_RENDERER
+environment variable.
+
+---
+
+This release also changes font rendering settings by introducing
+a new high-level gtk-font-rendering settings which gives GTK more
+freedom to decide on font rendering.
+
+You can still use the low-level font-related settings by changing
+the new property to 'manual'.
+
+---
+
+* GtkColumnView:
+ - Fix infinite loops in dispose
+ - Fix problems with weak ref cycles in GtkExpression
+
+* GtkListView:
+* GtkShortcutManager:
+ - Track the propagation phase of added controllers
+
+* GtkGLArea:
+ - Produce dmabuf textures, so graphics offload is possible
+
+* GtkTextView:
+ - Support text shadows
+
+* GtkGraphicsOffload:
+ - Add a black-background property
+
+* Settings:
+ - Add a new gtk-font-rendering setting
+
+* Accessibility:
+ - Add support for GetRangeExtents to GtkAccessibleText
+ - Add support for GetOffsetAtPoint to GtkAccessibleText
+ - Implement GtkAccessibleRange for scrollbars
+
+* GDK:
+ - Add a callback-based cursor API
+
+* GSK:
+-  Use the Vulkan renderer by default
+ - Avoid an infinite recursion with offscreens in some cases
+ - Optimize graphics offload to make it more likely that compositors
+   can use direct scanout
+
+* X11:
+ - Fix some confusing debug messages
+ - Drop a no-longer-relevant optimization that was interfering with
+   getting the current window manager capabilities
+
+* macOS:
+ - Implement the color picker for macOS 10.15+
+
+* Debugging:
+ - Snow monitor resolution in the inspector
+
+* Demos:
+ - Use graphics offload in the shadertoy demo
+ - Show more reliable fps numbers in the fishbowl demo
+
+* Tools:
+ - Support generating pdf in gtk4-rendernode-tool
+
+* Build:
+ - Require pango 1.52
+ - Require cairo 1.18
+ - Add a missing dependency that was causing build failures
+ - Drop deprecated build options:
+   gtk_doc -> documentation
+   update_screenshots -> screenshots
+   demo-profile -> profile
+   demos -> build-demos
+
+* Deprecations:
+ - gdk_widget_set/get_font_options
+ - gdk_wayland/x11_display_set_cursor_theme
+
+* Translation updates:
+ Basque
+ Brazilian Portuguese
+ British English
+ Chinese (China)
+ Hebrew
+ Kabyle
+ Persian
+ Polish
+ Russian
+ Slovenian
+ Swedish
+ Turkish
+
+
 Overview of Changes in 4.14.2, 03-04-2024
 =========================================
 

build-aux/flatpak/org.gtk.Demo4.json

@@ -186,7 +186,7 @@
             "config-opts" : [
                 "--libdir=/app/lib",
                 "-Dbuildtype=debugoptimized",
-                "-Ddemo-profile=devel"
+                "-Dprofile=devel"
             ],
             "sources" : [
                 {

build-aux/flatpak/org.gtk.IconBrowser4.json

@@ -115,7 +115,7 @@
             "config-opts" : [
                 "--libdir=/app/lib",
                 "-Dbuildtype=debugoptimized",
-                "-Ddemo-profile=devel"
+                "-Dprofile=devel"
             ],
             "sources" : [
                 {

build-aux/flatpak/org.gtk.WidgetFactory4.json

@@ -115,7 +115,7 @@
             "config-opts" : [
                 "--libdir=/app/lib",
                 "-Dbuildtype=debugoptimized",
-                "-Ddemo-profile=devel"
+                "-Dprofile=devel"
             ],
             "sources" : [
                 {

build-aux/flatpak/org.gtk.gtk4.NodeEditor.json

@@ -115,7 +115,7 @@
             "config-opts" : [
                 "--libdir=/app/lib",
                 "-Dbuildtype=debugoptimized",
-                "-Ddemo-profile=devel"
+                "-Dprofile=devel"
             ],
             "sources" : [
                 {

demos/gtk-demo/colorspaces.c

@@ -0,0 +1,86 @@
+/* Color Spaces
+ *
+ * Demonstrates support for color spaces.
+ *
+ * The test images used here are taken from http://displaycal.net/icc-color-management-test/
+ * and are licensed under the Creative Commons BY-SA 4.0 International License
+ */
+
+#include <gtk/gtk.h>
+
+static GtkWidget *jpeg;
+static GtkWidget *png;
+static GtkWidget *tiff;
+static GtkWidget *noprofile;
+static GtkWidget *test1;
+static GtkWidget *test2;
+
+static void
+on_changed (GtkCheckButton *button,
+            gpointer        user_data)
+{
+  GdkTexture *texture;
+  const char *extension = NULL;
+  char *path;
+
+  if (!gtk_check_button_get_active (GTK_CHECK_BUTTON (button)))
+    return;
+
+  if (gtk_check_button_get_active (GTK_CHECK_BUTTON (jpeg)))
+    extension = ".jpg";
+  else if (gtk_check_button_get_active (GTK_CHECK_BUTTON (png)))
+    extension = ".png";
+  else if (gtk_check_button_get_active (GTK_CHECK_BUTTON (tiff)))
+    extension = ".tif";
+  else if (gtk_check_button_get_active (GTK_CHECK_BUTTON (noprofile)))
+    extension = "-expected-result-no-cm.png";
+
+  path = g_strconcat ("/colorspaces/sRGB_Gray", extension, NULL);
+  texture = gdk_texture_new_from_resource (path);
+  gtk_picture_set_paintable (GTK_PICTURE (test1), GDK_PAINTABLE (texture));
+  g_object_unref (texture);
+
+  path = g_strconcat ("/colorspaces/ICC-Rendering-Intent-Test", extension, NULL);
+  texture = gdk_texture_new_from_resource (path);
+  gtk_picture_set_paintable (GTK_PICTURE (test2), GDK_PAINTABLE (texture));
+  g_object_unref (texture);
+}
+
+GtkWidget*
+do_colorspaces (GtkWidget *do_widget)
+{
+  static GtkWidget *window;
+
+  if (!window)
+    {
+      GtkBuilder *builder;
+      GtkBuilderScope *scope;
+
+      scope = gtk_builder_cscope_new ();
+      gtk_builder_cscope_add_callback_symbol (GTK_BUILDER_CSCOPE (scope),
+                                              "on_changed", G_CALLBACK (on_changed));
+
+      builder = gtk_builder_new ();
+      gtk_builder_set_scope (builder, scope);
+      gtk_builder_add_from_resource (builder, "/colorspaces/colorspaces.ui", NULL);
+      window = GTK_WIDGET (gtk_builder_get_object (builder, "window"));
+      jpeg = GTK_WIDGET (gtk_builder_get_object (builder, "jpeg"));
+      png = GTK_WIDGET (gtk_builder_get_object (builder, "png"));
+      tiff = GTK_WIDGET (gtk_builder_get_object (builder, "tiff"));
+      noprofile = GTK_WIDGET (gtk_builder_get_object (builder, "noprofile"));
+      test1 = GTK_WIDGET (gtk_builder_get_object (builder, "test1"));
+      test2 = GTK_WIDGET (gtk_builder_get_object (builder, "test2"));
+      gtk_window_set_display (GTK_WINDOW (window),
+                              gtk_widget_get_display (do_widget));
+      g_object_add_weak_pointer (G_OBJECT (window), (gpointer *)&window);
+      g_object_unref (builder);
+      g_object_unref (scope);
+    }
+
+  if (!gtk_widget_get_visible (window))
+    gtk_window_present (GTK_WINDOW (window));
+  else
+    gtk_window_destroy (GTK_WINDOW (window));
+
+  return window;
+}

demos/gtk-demo/colorspaces.ui

@@ -0,0 +1,94 @@
+<interface>
+  <object class="GtkWindow" id="window">
+    <property name="default-width">660</property>
+    <property name="default-height">660</property>
+    <property name="resizable">false</property>
+    <property name="title">Color Profiles</property>
+    <child>
+      <object class="GtkScrolledWindow">
+        <child>
+          <object class="GtkBox">
+            <property name="orientation">vertical</property>
+            <property name="spacing">10</property>
+            <property name="margin-top">10</property>
+            <property name="margin-bottom">10</property>
+            <property name="margin-start">10</property>
+            <property name="margin-end">10</property>
+            <child>
+              <object class="GtkBox">
+                <property name="spacing">10</property>
+                <child>
+                  <object class="GtkLabel">
+                    <property name="label">File format:</property>
+                  </object>
+                </child>
+                <child>
+                  <object class="GtkCheckButton" id="jpeg">
+                    <property name="label">JPEG</property>
+                    <property name="active">1</property>
+                    <signal name="notify::active" handler="on_changed"/>
+                  </object>
+                </child>
+                <child>
+                  <object class="GtkCheckButton" id="png">
+                    <property name="label">PNG</property>
+                    <property name="group">jpeg</property>
+                    <signal name="notify::active" handler="on_changed"/>
+                  </object>
+                </child>
+                <child>
+                  <object class="GtkCheckButton" id="tiff">
+                    <property name="label">TIFF</property>
+                    <property name="group">png</property>
+                    <signal name="notify::active" handler="on_changed"/>
+                  </object>
+                </child>
+                <child>
+                  <object class="GtkCheckButton" id="noprofile">
+                    <property name="label">No profile</property>
+                    <property name="group">tiff</property>
+                    <signal name="notify::active" handler="on_changed"/>
+                  </object>
+                </child>
+              </object>
+            </child>
+            <child>
+              <object class="GtkLabel">
+                <property name="label">Test 1: Matrix-based profile</property>
+                <style>
+                  <class name="title-3"/>
+                </style>
+              </object>
+            </child>
+            <child>
+              <object class="GtkPicture" id="test1">
+                <property name="hexpand">1</property>
+                <property name="vexpand">1</property>
+                <property name="can-shrink">1</property>
+                <property name="keep-aspect-ratio">1</property>
+                <property name="file">resource:///colorprofiles/sRGB_Gray.jpg</property>
+              </object>
+            </child>
+            <child>
+              <object class="GtkLabel">
+                <property name="label">Test 2: Lookup table-based profile</property>
+                <style>
+                  <class name="title-3"/>
+                </style>
+              </object>
+            </child>
+            <child>
+              <object class="GtkPicture" id="test2">
+                <property name="hexpand">1</property>
+                <property name="vexpand">1</property>
+                <property name="can-shrink">1</property>
+                <property name="keep-aspect-ratio">1</property>
+                <property name="file">resource:///colorprofiles/ICC-Rendering-Intent-Test.jpg</property>
+              </object>
+            </child>
+          </object>
+        </child>
+      </object>
+    </child>
+  </object>
+</interface>

demos/gtk-demo/demo.gresource.xml

@@ -19,6 +19,17 @@
     <file>demoimage.c</file>
     <file>demoimage.h</file>
   </gresource>
+  <gresource prefix="/colorspaces">
+    <file>colorspaces.ui</file>
+    <file>sRGB_Gray.jpg</file>
+    <file>sRGB_Gray.png</file>
+    <file>sRGB_Gray.tif</file>
+    <file>sRGB_Gray-expected-result-no-cm.png</file>
+    <file>ICC-Rendering-Intent-Test.png</file>
+    <file>ICC-Rendering-Intent-Test.jpg</file>
+    <file>ICC-Rendering-Intent-Test.tif</file>
+    <file>ICC-Rendering-Intent-Test-expected-result-no-cm.png</file>
+  </gresource>
   <gresource prefix="/constraints_builder">
     <file>constraints_builder.ui</file>
   </gresource>
@@ -265,6 +276,7 @@
     <file>assistant.c</file>
     <file>builder.c</file>
     <file>clipboard.c</file>
+    <file>colorspaces.c</file>
     <file>combobox.c</file>
     <file>constraints.c</file>
     <file>constraints_interactive.c</file>

demos/gtk-demo/fontify.c

@@ -363,7 +363,9 @@ insert_markup_idle (gpointer data)
 
       if (g_get_monotonic_time () - begin > G_TIME_SPAN_MILLISECOND)
         {
-          g_idle_add (insert_markup_idle, data);
+          guint id;
+          id = g_idle_add (insert_markup_idle, data);
+          g_source_set_name_by_id (id, "[gtk-demo] insert_markup_idle");
           return G_SOURCE_REMOVE;
         }
 
@@ -398,7 +400,9 @@ parse_markup_idle (gpointer data)
   do {
     if (g_get_monotonic_time () - begin > G_TIME_SPAN_MILLISECOND)
       {
-        g_idle_add (parse_markup_idle, data);
+        guint id;
+        id = g_idle_add (parse_markup_idle, data);
+        g_source_set_name_by_id (id, "[gtk-demo] parse_markup_idle");
         return G_SOURCE_REMOVE;
       }
 

demos/gtk-demo/language-names.c

@@ -40,7 +40,7 @@ get_win32_all_locales_scripts (LPWSTR locale_w, DWORD flags, LPARAM param)
 {
   wchar_t *langname_w = NULL;
   wchar_t locale_abbrev_w[9];
-  gchar *langname, *locale_abbrev, *locale, *p;
+  gchar *langname, *locale_abbrev, *locale;
   gint i;
   const LCTYPE iso639_lctypes[] = { LOCALE_SISO639LANGNAME, LOCALE_SISO639LANGNAME2 };
   GHashTable *ht_scripts_langs = (GHashTable *) param;
@@ -59,7 +59,6 @@ get_win32_all_locales_scripts (LPWSTR locale_w, DWORD flags, LPARAM param)
   GetLocaleInfoEx (locale_w, LOCALE_SLOCALIZEDDISPLAYNAME, langname_w, langname_size);
   langname = g_utf16_to_utf8 (langname_w, -1, NULL, NULL, NULL);
   locale = g_utf16_to_utf8 (locale_w, -1, NULL, NULL, NULL);
-  p = strchr (locale, '-');
   lang = pango_language_from_string (locale);
   if (g_hash_table_lookup (ht_scripts_langs, lang) == NULL)
     g_hash_table_insert (ht_scripts_langs, lang, langname);

demos/gtk-demo/main.c

@@ -20,6 +20,7 @@
 #include "config.h"
 #include <gtk/gtk.h>
 #include <glib/gstdio.h>
+#include <glib/gi18n.h>
 
 #include "demos.h"
 #include "fontify.h"
@@ -923,6 +924,34 @@ clear_search (GtkSearchBar *bar)
     }
 }
 
+static void
+search_results_update (GObject    *filter_model,
+                       GParamSpec *pspec,
+                       GtkEntry   *entry)
+{
+  gsize n_items = g_list_model_get_n_items (G_LIST_MODEL (filter_model));
+
+  if (strlen (gtk_editable_get_text (GTK_EDITABLE (entry))) > 0)
+    {
+      char *text;
+
+      if (n_items > 0)
+        text = g_strdup_printf (ngettext ("%ld search result", "%ld search results", n_items), n_items);
+      else
+        text = g_strdup (_("No search results"));
+
+      gtk_accessible_update_property (GTK_ACCESSIBLE (entry),
+                                      GTK_ACCESSIBLE_PROPERTY_DESCRIPTION, text,
+                                      -1);
+
+      g_free (text);
+    }
+  else
+    {
+      gtk_accessible_reset_property (GTK_ACCESSIBLE (entry), GTK_ACCESSIBLE_PROPERTY_DESCRIPTION);
+    }
+}
+
 static void
 activate (GApplication *app)
 {
@@ -970,6 +999,7 @@ activate (GApplication *app)
 
   search_entry = GTK_WIDGET (gtk_builder_get_object (builder, "search-entry"));
   g_signal_connect (search_entry, "search-changed", G_CALLBACK (demo_search_changed_cb), filter);
+  g_signal_connect (filter_model, "notify::n-items", G_CALLBACK (search_results_update), search_entry);
 
   selection = gtk_single_selection_new (G_LIST_MODEL (filter_model));
   g_signal_connect (selection, "notify::selected-item", G_CALLBACK (selection_cb), NULL);

demos/gtk-demo/meson.build

@@ -5,6 +5,7 @@ demos = files([
   'assistant.c',
   'builder.c',
   'clipboard.c',
+  'colorspaces.c',
   'combobox.c',
   'constraints.c',
   'constraints_interactive.c',

demos/node-editor/node-format.md

@@ -117,6 +117,15 @@ should be aware that the allowed values are meant to be used on 3D transformatio
 so their naming might appear awkward. However, it is always possible to use the
 matrix3d() production to specify all 16 values individually.
 
+### color-state
+
+| property    | syntax           | default                | printed     |
+| ----------- | ---------------- | ---------------------- | ----------- |
+| bounds      | `<rect>`         | 50                     | always      |
+| color-state | `<ident>|<url>`  | srgb                   | always      |
+
+Creates a node like `gsk_color_state_node_new()` with the given properties.
+
 ### conic-gradient
 
 | property | syntax           | default                | printed     |
@@ -330,6 +339,7 @@ stroke bounds of the path.
 | offset       | `<point>`           | 0 0                 | non-default |
 | hint-style   | `<hint style>`      | slight              | non-default |
 | antialias    | `<antialias>`       | gray                | non-default |
+| hint-metrics | `<hint metrics>`    | off                 | non-default |
 
 Creates a node like `gsk_text_node_new()` with the given properties.
 
@@ -346,6 +356,7 @@ font, an error node will be returned.
 
 Possible values for hint-style are none, slight or full.
 Possible value for antialias are none or gray.
+Possible value for hint-metrics are on or off.
 
 ### texture
 

demos/widget-factory/widget-factory.css

@@ -6,3 +6,10 @@
 .toolbar {
   -gtk-icon-style: symbolic;
 }
+
+.gtk-gradient-color {
+  background: linear-gradient(to right, lime, red);
+}
+.gtk-gradient-monochrome {
+  background: linear-gradient(to right, black, white);
+}

demos/widget-factory/widget-factory.gresource.xml

@@ -117,5 +117,9 @@
     <file>portland-rose.jpg</file>
     <file>nyc.jpg</file>
     <file>beach.jpg</file>
+    <file>linear-gradient-color.png</file>
+    <file>linear-gradient-monochrome.png</file>
+    <file>srgb-gradient-color.png</file>
+    <file>srgb-gradient-monochrome.png</file>
   </gresource>
 </gresources>

demos/widget-factory/widget-factory.ui

@@ -1344,13 +1344,173 @@ Suspendisse feugiat quam quis dolor accumsan cursus.</property>
                             <child>
                               <object class="GtkNotebookPage">
                                 <property name="child">
-                                  <object class="GtkBox" id="box8">
-                                    <property name="orientation">1</property>
+                                  <object class="GtkGrid">
+                                    <property name="hexpand">0</property>
+                                    <property name="row-spacing">6</property>
+                                    <property name="column-spacing">6</property>
+                                    <property name="margin-start">6</property>
+                                    <property name="margin-end">6</property>
+                                    <property name="margin-top">6</property>
+                                    <property name="margin-bottom">6</property>
+                                    <property name="row-homogeneous">1</property>
+                                    <property name="valign">start</property>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label" translatable="yes">color</property>
+                                        <style>
+                                          <class name="caption-heading"/>
+                                        </style>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">0</property>
+                                          <property name="column-span">2</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label">sRGB</property>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">1</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkPicture">
+                                        <property name="file">resource:///org/gtk/WidgetFactory4/srgb-gradient-color.png</property>
+                                        <property name="can-shrink">0</property>
+                                        <property name="keep-aspect-ratio">0</property>
+                                        <property name="hexpand">1</property>
+                                        <layout>
+                                          <property name="column">1</property>
+                                          <property name="row">1</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label">GTK</property>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">2</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkPicture">
+                                        <property name="width-request">128</property>
+                                        <property name="keep-aspect-ratio">0</property>
+                                        <style>
+                                          <class name="gtk-gradient-color"/>
+                                        </style>
+                                        <layout>
+                                          <property name="column">1</property>
+                                          <property name="row">2</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label">linear</property>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">3</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkPicture">
+                                        <property name="file">resource:///org/gtk/WidgetFactory4/linear-gradient-color.png</property>
+                                        <property name="can-shrink">0</property>
+                                        <property name="keep-aspect-ratio">0</property>
+                                        <layout>
+                                          <property name="column">1</property>
+                                          <property name="row">3</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label" translatable="yes">monochrome</property>
+                                        <style>
+                                          <class name="caption-heading"/>
+                                        </style>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">4</property>
+                                          <property name="column-span">2</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label">sRGB</property>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">5</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkPicture">
+                                        <property name="file">resource:///org/gtk/WidgetFactory4/srgb-gradient-monochrome.png</property>
+                                        <property name="can-shrink">0</property>
+                                        <property name="keep-aspect-ratio">0</property>
+                                        <property name="hexpand">1</property>
+                                        <layout>
+                                          <property name="column">1</property>
+                                          <property name="row">5</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label">GTK</property>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">6</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkPicture">
+                                        <property name="width-request">128</property>
+                                        <property name="keep-aspect-ratio">0</property>
+                                        <style>
+                                          <class name="gtk-gradient-monochrome"/>
+                                        </style>
+                                        <layout>
+                                          <property name="column">1</property>
+                                          <property name="row">6</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkLabel">
+                                        <property name="label">linear</property>
+                                        <layout>
+                                          <property name="column">0</property>
+                                          <property name="row">7</property>
+                                        </layout>
+                                      </object>
+                                    </child>
+                                    <child>
+                                      <object class="GtkPicture">
+                                        <property name="file">resource:///org/gtk/WidgetFactory4/linear-gradient-monochrome.png</property>
+                                        <property name="can-shrink">0</property>
+                                        <property name="keep-aspect-ratio">0</property>
+                                        <layout>
+                                          <property name="column">1</property>
+                                          <property name="row">7</property>
+                                        </layout>
+                                      </object>
+                                    </child>
                                   </object>
                                 </property>
                                 <property name="tab">
                                   <object class="GtkLabel" id="label8">
-                                    <property name="label" translatable="1">page 1</property>
+                                    <property name="label" translatable="1">Gradients</property>
                                   </object>
                                 </property>
                               </object>

docs/reference/gdk/cairo.md

@@ -5,8 +5,11 @@ Title: Cairo interaction
 [Cairo](http://cairographics.org) is a graphics library that supports vector
 graphics and image compositing that can be used with GTK.
 
-GDK does not wrap the Cairo API; instead it allows to create Cairo
-drawing contexts which can be used to draw on [class@Gdk.Surface]s.
+GDK does not wrap the Cairo API and it is not possible to use cairo directly
+to draw on a [class@Gdk.Surface]. You can either use a
+[GtkDrawingArea](../gtk4/class.DrawingArea.html) widget or
+[gtk_snapshot_append_cairo](../gtk4/func.Snapshot.append_cairo.html)
+for drawing with cairo in a GTK4 application.
 
 Additional functions allow use [struct@Gdk.Rectangle]s with Cairo
 and to use [struct@Gdk.RGBA], `GdkPixbuf`, and [class@Gdk.Surface]

docs/reference/gtk/css-overview.md

@@ -74,6 +74,7 @@ in a selector, widget names must be prefixed with a # character.
 | E:not(selector) | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#negation) | |
 | E:dir(ltr), E:dir(rtl) | [CSS Selector Level 4](https://drafts.csswg.org/selectors/#the-dir-pseudo) | |
 | E:drop(active) | [CSS Selector Level 4](https://drafts.csswg.org/selectors/#drag-pseudos) | |
+| E:root | [CSS Selector Level 3](https://www.w3.org/TR/selectors-3/#root-pseudo) | |
 | E F | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#descendent-combinators) | |
 | E > F | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#child-combinators) | |
 | E ~ F | [CSS Selector Level 3](https://www.w3.org/TR/css3-selectors/#general-sibling-combinators) | |

docs/reference/gtk/css-properties.md

@@ -15,16 +15,16 @@ spec.
 The following units are supported for basic datatypes:
 
 Length
-: px, pt, em, ex, rem, pc, in, cm, mm, calc()
+: px, pt, em, ex, rem, pc, in, cm, mm
 
 Percentage
-: %, calc()
+: %
 
 Angle
-: deg, grad, turn, calc()
+: deg, rad, grad, turn
 
 Time
-: s, ms, calc()
+: s, ms
 
 Length values with the em or ex units are resolved using the font
 size value, unless they occur in setting the font-size itself, in
@@ -33,11 +33,15 @@ which case they are resolved using the inherited font size value.
 The rem unit is resolved using the initial font size value, which is
 not quite the same as the CSS definition of rem.
 
-The calc() notation adds considerable expressive power. There are limits
-on what types can be combined in such an expression (e.g. it does not make
-sense to add a number and a time). For the full details, see the
-[CSS3 Values and Units](https://www.w3.org/TR/css3-values/#calc-notation)
-spec.
+Length values using physical units (pt, pc, in, cm, mm) are translated
+to px using the dpi value specified by the -gtk-dpi property, which is
+different from the CSS definition, which uses a fixed dpi of 96.
+
+The calc() notation adds considerable expressive power to all of these
+datatypes. There are limits on what types can be combined in such an
+expression (e.g. it does not make sense to add a number and a time).
+For the full details, see the
+[CSS Values and Units](https://www.w3.org/TR/css-values-4/) spec.
 
 A common pattern among shorthand properties (called 'four sides') is one
 where one to four values can be specified, to determine a value for each
@@ -56,38 +60,80 @@ follows:
 1 value:
 : all
 
+## Custom Properties
+
+GTK supports custom properties as defined in the
+[CSS Custom Properties for Cascading Variables](https://www.w3.org/TR/css-variables-1)
+spec.
+
+Custom properties are defined as follows:
+
+```css
+--prop: red;
+```
+
+and used via the `var` keyword:
+
+```css
+color: var(--prop);
+```
+
+Custom properties can have a fallback for when the referred property is invalid:
+
+```css
+color: var(--prop, green);
+```
+
 ## Colors
 
-GTK extends the CSS syntax with several additional ways to specify colors.
+### CSS Colors
+
+Colors can be expressed in numerous ways in CSS (see the
+[Color Module](https://www.w3.org/TR/css-color-5/). GTK supports
+many (but not all) of these.
+
+You can use rgb(), rgba(), hsl() with both the legacy or the modern CSS
+syntax, and calc() can be used as well in color expressions. hwb(), oklab(),
+oklch(), color(), color-mix() and relative colors are supported as well.
+
+### Non-CSS Colors
+
+GTK  extends the CSS syntax with several additional ways to specify colors.
+
+These extensions are deprecated and should be replaced by the equivalent
+standard CSS notions.
 
 The first is a reference to a color defined via a @define-color rule in CSS.
 The syntax for @define-color rules is as follows:
 
 ```
-@define-color Name Color
+@define-color name color
 ```
 
 To refer to the color defined by a @define-color rule, prefix the name with @.
 
+The standard CSS mechanisms that should be used instead of @define-color are
+custom properties, :root and var().
+
 GTK also supports color expressions, which allow colors to be transformed to
 new ones. Color expressions can be nested, providing a rich language to
 define colors. Color expressions resemble functions, taking 1 or more colors
 and in some cases a number as arguments.
 
-`lighter(Color)`
- : produces a brighter variant of Color
+`lighter(color)`
+ : produces a brighter variant of `color`.
 
-`darker(Color)`
- : produces a darker variant of Color
+`darker(color)`
+ : produces a darker variant of `color`.
 
-`shade(Color, Number)`
- : changes the lightness of Color. The number ranges from 0 for black to 2 for white.
+`shade(color, number)`
+ : changes the lightness of `color`. The `number` ranges from 0 for black to 2 for white.
 
-`alpha(Color, Number)`
- : replaces the alpha value of color with number (between 0 and 1)
+`alpha(color, number)`
+ : multiplies the alpha value of `color` by `number` (between 0 and 1).
 
-`mix(Color1, Color2, Number)`
- : interpolates between the two colors
+`mix(color1, color2, number)`
+ : interpolates between the two colors.
 
 ## Images
 
@@ -95,7 +141,7 @@ GTK extends the CSS syntax for images and also uses it for specifying icons.
 To load a themed icon, use
 
 ```
--gtk-icontheme(Name)
+-gtk-icontheme(name)
 ```
 
 The specified icon name is used to look up a themed icon, while taking into
@@ -124,14 +170,14 @@ and the
 syntax makes this available. -gtk-recolor requires a url as first argument.
 The remaining arguments specify the color palette to use. If the palette is
 not explicitly specified, the current value of the -gtk-icon-palette property
-is used. 
+is used.
 
 GTK supports scaled rendering on hi-resolution displays. This works best if
 images can specify normal and hi-resolution variants. From CSS, this can be
 done with
 
 ```
--gtk-scaled(Image1, Image2)
+-gtk-scaled(image1, image2)
 ```
 
 ## GTK CSS Properties

docs/reference/gtk/gtk4-broadwayd.rst

@@ -8,6 +8,10 @@ gtk4-broadwayd
 The Broadway display server
 ---------------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 |   **gtk4-broadwayd** [OPTIONS...] <DISPLAY>

docs/reference/gtk/gtk4-builder-tool.rst

@@ -8,6 +8,10 @@ gtk4-builder-tool
 GtkBuilder File Utility
 -----------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 |   **gtk4-builder-tool** <COMMAND> [OPTIONS...] <FILE>

docs/reference/gtk/gtk4-demo-application.rst

@@ -8,6 +8,9 @@ gtk4-demo-application
 Demonstrate GtkApplication
 --------------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
 
 SYNOPSIS
 --------

docs/reference/gtk/gtk4-demo.rst

@@ -8,6 +8,10 @@ gtk4-demo
 Demonstrate GTK widgets
 -----------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4-encode-symbolic-svg.rst

@@ -8,6 +8,10 @@ gtk4-encode-symbolic-svg
 Symbolic icon conversion utility
 --------------------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4-icon-browser.rst

@@ -8,6 +8,10 @@ gtk4-icon-browser
 List themed icons
 -----------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4-launch.rst

@@ -8,6 +8,10 @@ gtk4-launch
 Launch an application
 ---------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4-node-editor.rst

@@ -8,6 +8,10 @@ gtk4-node-editor
 Editor render nodes
 -----------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4-path-tool.rst

@@ -8,6 +8,10 @@ gtk4-path-tool
 GskPath Utility
 -----------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 |   **gtk4-path-tool** <COMMAND> [OPTIONS...] <PATH>

docs/reference/gtk/gtk4-query-settings.rst

@@ -8,6 +8,10 @@ gtk4-query-settings
 Print name and value of GTK settings
 ------------------------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4-rendernode-tool.rst

@@ -8,12 +8,17 @@ gtk4-rendernode-tool
 GskRenderNode Utility
 -----------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 |   **gtk4-rendernode-tool** <COMMAND> [OPTIONS...] <FILE>
 |
 |   **gtk4-rendernode-tool** benchmark [OPTIONS...] <FILE>
 |   **gtk4-rendernode-tool** compare [OPTIONS...] <FILE1> <FILE2>
+|   **gtk4-rendernode-tool** extract [OPTIONS...] <FILE>
 |   **gtk4-rendernode-tool** info [OPTIONS...] <FILE>
 |   **gtk4-rendernode-tool** render [OPTIONS...] <FILE> [<FILE>]
 |   **gtk4-rendernode-tool** show [OPTIONS...] <FILE>
@@ -45,13 +50,14 @@ without any titlebar.
 Rendering
 ^^^^^^^^^
 
-The ``render`` command saves a rendering of the rendernode as a png or tiff image.
-The name of the file to write can be specified as a second FILE argument.
+The ``render`` command saves a rendering of the rendernode as a png, tiff or svg
+image or as pdf document. The name of the file to write can be specified as a second
+FILE argument.
 
 ``--renderer=RENDERER``
 
   Use the given renderer. Use ``--renderer=help`` to get a information
-  about poassible values for the ``RENDERER``.
+  about possible values for the ``RENDERER``.
 
 Benchmark
 ^^^^^^^^^
@@ -93,4 +99,16 @@ exit code is 1. If the images are identical, it is 0.
 
 ``--quiet``
 
-  Don't write results to stdout.`
+  Don't write results to stdout.
+
+
+Extract
+^^^^^^^
+
+The ``extract`` command saves all the data urls found in a node file to a given
+directory. The file names for the extracted files are derived from the mimetype
+of the url.
+
+``--dir=DIRECTORY``
+
+  Save extracted files in ``DIRECTORY`` (defaults to the current directory).

docs/reference/gtk/gtk4-update-icon-cache.rst

@@ -8,6 +8,10 @@ gtk4-update-icon-cache
 Icon theme caching utility
 --------------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4-widget-factory.rst

@@ -8,6 +8,10 @@ gtk4-widget-factory
 Showcase GTK widgets and styles
 -------------------------------
 
+:Version: GTK
+:Manual section: 1
+:Manual group: GTK commands
+
 SYNOPSIS
 --------
 

docs/reference/gtk/gtk4.toml.in

@@ -77,11 +77,13 @@ content_files = [
   "section-tree-widget.md",
   "migrating-2to4.md",
   "migrating-3to4.md",
+  "migrating-4to5.md",
   "broadway.md",
   "osx.md",
   "wayland.md",
   "windows.md",
   "x11.md",
+  "tools.md",
   "visual_index.md",
 ]
 content_images = [

docs/reference/gtk/meson.build

@@ -14,6 +14,7 @@ expand_content_md_files = [
   'running.md',
   'migrating-2to4.md',
   'migrating-3to4.md',
+  'migrating-4to5.md',
   'actions.md',
   'input-handling.md',
   'drawing-model.md',
@@ -25,7 +26,8 @@ expand_content_md_files = [
   'section-tree-widget.md',
   'section-list-widget.md',
   'question_index.md',
-  'visual_index.md'
+  'visual_index.md',
+  'tools.md',
 ]
 
 gtk_images = []
@@ -60,39 +62,39 @@ if get_option('documentation')
     build_by_default: true,
     install: true,
     install_dir: docs_dir,
+    install_tag: 'doc',
   )
 endif
 
-rst2man = find_program('rst2man', 'rst2man.py', required: false)
-if get_option('man-pages') and not rst2man.found()
-  error('No rst2man found, but man pages were explicitly enabled')
+rst2man = find_program('rst2man', 'rst2man.py', required: get_option('man-pages'))
+rst2html5 = find_program('rst2html5', 'rst2html5.py', required: get_option('documentation'))
+
+rst_files = [
+  [ 'gtk4-broadwayd', '1' ],
+  [ 'gtk4-builder-tool', '1' ],
+  [ 'gtk4-encode-symbolic-svg', '1', ],
+  [ 'gtk4-launch', '1', ],
+  [ 'gtk4-query-settings', '1', ],
+  [ 'gtk4-rendernode-tool', '1' ],
+  [ 'gtk4-update-icon-cache', '1', ],
+  [ 'gtk4-path-tool', '1', ],
+]
+
+if get_option('build-demos')
+  rst_files += [
+    [ 'gtk4-demo', '1', ],
+    [ 'gtk4-demo-application', '1', ],
+    [ 'gtk4-widget-factory', '1', ],
+    [ 'gtk4-icon-browser', '1', ],
+    [ 'gtk4-node-editor', '1', ],
+  ]
 endif
 
-if get_option('man-pages') and rst2man.found()
-  rst_files = [
-    [ 'gtk4-broadwayd', '1' ],
-    [ 'gtk4-builder-tool', '1' ],
-    [ 'gtk4-encode-symbolic-svg', '1', ],
-    [ 'gtk4-launch', '1', ],
-    [ 'gtk4-query-settings', '1', ],
-    [ 'gtk4-rendernode-tool', '1' ],
-    [ 'gtk4-update-icon-cache', '1', ],
-    [ 'gtk4-path-tool', '1', ],
-  ]
+rst2x_flags = [
+  '--syntax-highlight=none',
+]
 
-  if get_option('demos')
-    rst_files += [
-      [ 'gtk4-demo', '1', ],
-      [ 'gtk4-demo-application', '1', ],
-      [ 'gtk4-widget-factory', '1', ],
-      [ 'gtk4-icon-browser', '1', ],
-      [ 'gtk4-node-editor', '1', ],
-    ]
-  endif
-
-  rst2man_flags = [
-    '--syntax-highlight=none',
-  ]
+if get_option('man-pages')
 
   foreach rst: rst_files
     man_name = rst[0]
@@ -103,12 +105,34 @@ if get_option('man-pages') and rst2man.found()
       output: '@0@.@1@'.format(man_name, man_section),
       command: [
         rst2man,
-        rst2man_flags,
+        rst2x_flags,
         '@INPUT@',
       ],
       capture: true,
       install: true,
       install_dir: get_option('mandir') / 'man@0@'.format(man_section),
+      install_tag: 'doc',
+    )
+  endforeach
+endif
+
+if get_option('documentation')
+
+  foreach rst: rst_files
+    man_name = rst[0]
+
+    custom_target(
+      input: '@0@.rst'.format(man_name),
+      output: '@0@.html'.format(man_name),
+      command: [
+        rst2html5,
+        rst2x_flags,
+        '@INPUT@',
+      ],
+      capture: true,
+      install: true,
+      install_dir: docs_dir / 'gtk4',
+      install_tag: 'doc',
     )
   endforeach
 endif

docs/reference/gtk/migrating-4to5.md

@@ -58,7 +58,7 @@ use a GtkLabel.
 If you have a need for custom drawing that fits into the current
 (dark or light) theme, e.g. for rendering a graph, you can still
 get the current style foreground color, using
-[method@Gtk.Widget.get_style_color].
+[method@Gtk.Widget.get_color].
 
 ## Local stylesheets are going away
 
@@ -73,6 +73,103 @@ GTK 5 will no longer provide this functionality. The recommendations
 is to use a global stylesheet (i.e. gtk_style_context_add_provider_for_display())
 and rely on style classes to make your CSS apply only where desired.
 
+## Non-standard CSS extensions are going away
+
+GTK's CSS machinery has a some non-standard extensions around colors:
+named colors with \@define-color and color functions: lighter(), darker(),
+shade(), alpha(), mix().
+
+GTK now implements equivalent functionality from the CSS specs.
+
+### \@define-color is going away
+
+\@define-color should be replaced by custom properties in the :root scope.
+
+Instead of
+
+```
+@define-color fg_color #2e3436
+
+...
+
+box {
+  color: @fg_color;
+}
+```
+
+use
+
+```
+:root {
+  --fg-color: #2e3436;
+}
+
+...
+
+box {
+  color: var(--fg-color);
+}
+```
+
+For more information about custom CSS properties and variables, see the
+[CSS Custom Properties for Cascading Variables](https://www.w3.org/TR/css-variables-1/)
+spec.
+
+### Color expressions are going away
+
+The color functions can all be replaced by combinations of calc() and color-mix().
+
+ligher(c) and darker(c) are just shade(c, 1.3) or shade(c, 0.7), respectively, and
+thus can be handled the same way as shade in the examples below.
+
+Replace
+
+```
+a {
+  color: mix(red, green, 0.8);
+}
+
+b {
+  color: alpha(green, 0.6);
+}
+
+c {
+  color: shade(red, 1.3);
+}
+
+d {
+  color: shade(red, 0.7);
+}
+```
+
+with
+
+```
+a {
+  color: color-mix(in srgb, red, green 80%);
+}
+
+b {
+  color: rgb(from green, r g b / calc(alpha * 0.6));
+}
+
+c {
+  color: hsl(from red, h calc(s * 1.3) calc(l * 1.3));
+}
+
+d {
+  color: hsl(from red, h calc(s * 0.7) calc(l * 0.7));
+}
+```
+
+Variations of these replacements are possible.
+
+Note that GTK has historically computed mix() and shade() values in the SRGB and HSL
+colorspaces, but using OKLAB instead might yield slightly better results.
+
+For more information about color-mix(), see the
+[CSS Color](https://drafts.csswg.org/css-color-5) spec.
+
 ## Chooser interfaces are going away
 
 The GtkColorChooser, GtkFontChooser, GtkFileChooser and GtkAppChooser

docs/reference/gtk/overview.md

@@ -64,6 +64,6 @@ GTK is divided into three parts:
 [cairo]: https://www.cairographics.org/manual/
 [opengl]: https://www.opengl.org/about/
 [vulkan]: https://www.vulkan.org/
-[pango]: https://docs.gtk.org/pango/
+[pango]: https://docs.gtk.org/Pango/
 [gdkpixbuf]: https://docs.gtk.org/gdk-pixbuf/
 [graphene]: https://ebassi.github.io/graphene/

docs/reference/gtk/running.md

@@ -217,6 +217,10 @@ A number of options affect behavior instead of logging:
 `no-portals`
 : Disable use of [portals](https://docs.flatpak.org/en/latest/portals.html)
 
+`force-offload`
+: Force graphics offload for all textures, even when slower. This allows
+  to debug offloading in the absence of dmabufs.
+
 `gl-disable`
 : Disable OpenGL support
 

docs/reference/gtk/section-accessibility.md

@@ -155,6 +155,7 @@ Each property name is part of the `GtkAccessibleProperty` enumeration.
 | %GTK_ACCESSIBLE_PROPERTY_VALUE_MIN | “aria-valuemin” | double |
 | %GTK_ACCESSIBLE_PROPERTY_VALUE_NOW | “aria-valuenow” | double |
 | %GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT | “aria-valuetext” | translatable string |
+| %GTK_ACCESSIBLE_PROPERTY_HELP_TEXT | N/A | translatable string |
 
 #### List of accessible relations
 
@@ -216,6 +217,10 @@ are accessible as part of the development process. The GTK Inspector shows
 the accessible attributes of each widget, and also provides an overlay that
 can highlight accessibility issues.
 
+If you support some non-standard keyboard interactions for a widget, you
+**should** set an appropriate `GTK_ACCESSIBLE_PROPERTY_HELP_TEXT` to help
+discoverability of the behavior.
+
 It is possible to set accessible attributes in UI files as well:
 ```xml
 <object class="GtkButton" id="button1">

docs/reference/gtk/tools.md

@@ -0,0 +1,18 @@
+Title: Tools and Demos
+
+GTK ships with a number of tools and demos that come with their own
+documentation in the form of man pages.
+
+ - [gtk4-broadwayd](gtk4-broadwayd.html)
+ - [gtk4-builder-tool](gtk4-builder-tool.html)
+ - [gtk4-demo](gtk4-demo.html)
+ - [gtk4-demo-application](gtk4-demo-application.html)
+ - [gtk4-encode-symbolic-svg](gtk4-encode-symbolic-svg.html)
+ - [gtk4-icon-browser](gtk4-icon-browser.html)
+ - [gtk4-launch](gtk4-launch.html)
+ - [gtk4-node-editor](gtk4-node-editor.html)
+ - [gtk4-path-tool](gtk4-path-tool.html)
+ - [gtk4-query-settings](gtk4-query-settings.html)
+ - [gtk4-rendernode-tool](gtk4-rendernode-tool.html)
+ - [gtk4-update-icon-cache](gtk4-update-icon-cache.html)
+ - [gtk4-widget-factory](gtk4-widget-factory.html)

gdk/broadway/gdkcairocontext-broadway.c

@@ -46,9 +46,10 @@ gdk_broadway_cairo_context_begin_frame (GdkDrawContext *draw_context,
   width = gdk_surface_get_width (surface);
   height = gdk_surface_get_height (surface);
   scale = gdk_surface_get_scale_factor (surface);
-  self->paint_surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
-                                                    width * scale, height * scale);
-  cairo_surface_set_device_scale (self->paint_surface, scale, scale);
+
+  self->paint_surface = gdk_surface_create_similar_surface (surface,
+                                                            CAIRO_CONTENT_COLOR_ALPHA,
+                                                            width * scale, height *scale);
 
   repaint_region = cairo_region_create_rectangle (&(cairo_rectangle_int_t) { 0, 0, width, height });
   cairo_region_union (region, repaint_region);

gdk/gdk.c

@@ -19,7 +19,7 @@
  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  * file for a list of people on the GTK+ Team.  See the ChangeLog
  * files for a list of changes.  These files are distributed with
- * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
+ * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  */
 
 #include "config.h"
@@ -122,6 +122,7 @@ static const GdkDebugKey gdk_debug_keys[] = {
 
   { "portals",         GDK_DEBUG_PORTALS, "Force use of portals" },
   { "no-portals",      GDK_DEBUG_NO_PORTALS, "Disable use of portals" },
+  { "force-offload",   GDK_DEBUG_FORCE_OFFLOAD, "Force graphics offload for all textures" },
   { "gl-disable",      GDK_DEBUG_GL_DISABLE, "Disable OpenGL support" },
   { "gl-no-fractional", GDK_DEBUG_GL_NO_FRACTIONAL, "Disable fractional scaling for OpenGL" },
   { "gl-debug",        GDK_DEBUG_GL_DEBUG, "Insert debugging information in OpenGL" },
@@ -137,36 +138,56 @@ static const GdkDebugKey gdk_debug_keys[] = {
   { "high-depth",      GDK_DEBUG_HIGH_DEPTH, "Use high bit depth rendering if possible" },
   { "no-vsync",        GDK_DEBUG_NO_VSYNC, "Repaint instantly (uses 100% CPU with animations)" },
   { "dmabuf-disable",  GDK_DEBUG_DMABUF_DISABLE, "Disable dmabuf support" },
+  { "srgb",            GDK_DEBUG_SRGB, "Force sRRGB rendering and turn off color profiles" },
 };
 
 
 #ifdef G_HAS_CONSTRUCTORS
 #ifdef G_DEFINE_CONSTRUCTOR_NEEDS_PRAGMA
-#pragma G_DEFINE_CONSTRUCTOR_PRAGMA_ARGS(stash_desktop_startup_notification_id)
+#pragma G_DEFINE_CONSTRUCTOR_PRAGMA_ARGS(stash_and_unset_environment)
 #endif
-G_DEFINE_CONSTRUCTOR(stash_desktop_startup_notification_id)
+G_DEFINE_CONSTRUCTOR(stash_and_unset_environment)
 #endif
 
 static char *startup_notification_id = NULL;
+static char *xdg_activation_token = NULL;
 
 static void
-stash_desktop_startup_notification_id (void)
+stash_and_unset_environment (void)
 {
-  const char *desktop_startup_id;
-
-  desktop_startup_id = g_getenv ("DESKTOP_STARTUP_ID");
-  if (desktop_startup_id && *desktop_startup_id != '\0')
-    {
-      if (!g_utf8_validate (desktop_startup_id, -1, NULL))
-        g_warning ("DESKTOP_STARTUP_ID contains invalid UTF-8");
-      else
-        startup_notification_id = g_strdup (desktop_startup_id);
-    }
-
-  /* Clear the environment variable so it won't be inherited by
+  /* Copies environment variables and unsets them so they won't be inherited by
    * child processes and confuse things.
+   *
+   * Changing environment variables can be racy so we try to do this as early as
+   * possible in the program flow and before any printing that might involve
+   * environment variables.
    */
-  g_unsetenv ("DESKTOP_STARTUP_ID");
+  struct {
+    const char *key;
+    char **dst;
+  } vars[] = {
+    { "DESKTOP_STARTUP_ID", &startup_notification_id },
+    { "XDG_ACTIVATION_TOKEN", &xdg_activation_token },
+  };
+  size_t i;
+
+  for (i = 0; i < G_N_ELEMENTS (vars); i++)
+    *vars[i].dst = g_strdup (g_getenv (vars[i].key));
+
+  for (i = 0; i < G_N_ELEMENTS (vars); i++)
+    g_unsetenv (vars[i].key);
+
+  for (i = 0; i < G_N_ELEMENTS (vars); i++)
+    {
+      if (*vars[i].dst == NULL)
+        continue;
+
+      if (!g_utf8_validate (*vars[i].dst, -1, NULL))
+        {
+          g_warning ("%s contains invalid UTF-8", vars[i].key);
+          g_clear_pointer (vars[i].dst, g_free);
+        }
+    }
 }
 
 static gpointer
@@ -291,7 +312,7 @@ gdk_pre_parse (void)
     gdk_gl_backend_use (GDK_GL_WGL);
 
 #ifndef G_HAS_CONSTRUCTORS
-  stash_desktop_startup_notification_id ();
+  stash_and_unset_environment ();
 #endif
 }
 
@@ -325,15 +346,20 @@ gdk_display_open_default (void)
 /*< private >
  * gdk_get_startup_notification_id:
  *
- * Returns the original value of the DESKTOP_STARTUP_ID environment
- * variable if it was defined and valid, or %NULL otherwise.
+ * Returns the original value of the XDG_ACTIVATION_TOKEN environment
+ * variable if it was defined and valid, otherwise it returns the original
+ * value of the DESKTOP_STARTUP_ID environment variable if it was defined
+ * and valid, or %NULL if neither of them were defined and valid.
  *
  * Returns: (nullable) (transfer none): the original value of the
- *   DESKTOP_STARTUP_ID environment variable
+ *   XDG_ACTIVATION_TOKEN or DESKTOP_STARTUP_ID environment variable
  */
 const char *
 gdk_get_startup_notification_id (void)
 {
+  if (xdg_activation_token)
+    return xdg_activation_token;
+
   return startup_notification_id;
 }
 

gdk/gdk.h

@@ -30,6 +30,7 @@
 #include <gdk/gdkcairo.h>
 #include <gdk/gdkcairocontext.h>
 #include <gdk/gdkclipboard.h>
+#include <gdk/gdkcolorstate.h>
 #include <gdk/gdkconfig.h>
 #include <gdk/gdkcontentdeserializer.h>
 #include <gdk/gdkcontentformats.h>

gdk/gdkarrayimpl.c

@@ -41,8 +41,10 @@ G_BEGIN_DECLS
 
 #ifdef GDK_ARRAY_NULL_TERMINATED
 #define GDK_ARRAY_REAL_SIZE(_size) ((_size) + 1)
+#define GDK_ARRAY_MAX_SIZE (G_MAXSIZE / sizeof (_T_) - 1)
 #else
 #define GDK_ARRAY_REAL_SIZE(_size) (_size)
+#define GDK_ARRAY_MAX_SIZE (G_MAXSIZE / sizeof (_T_))
 #endif
 
 /* make this readable */
@@ -177,18 +179,23 @@ G_GNUC_UNUSED static inline void
 gdk_array(reserve) (GdkArray *self,
                     gsize      n)
 {
-  gsize new_size, size;
+  gsize new_capacity, size, capacity;
 
-  if (n <= gdk_array(get_capacity) (self))
-    return;
+  if (G_UNLIKELY (n > GDK_ARRAY_MAX_SIZE))
+    g_error ("requesting array size of %zu, but maximum size is %zu", n, GDK_ARRAY_MAX_SIZE);
+
+  capacity = gdk_array(get_capacity) (self);
+  if (n <= capacity)
+     return;
 
   size = gdk_array(get_size) (self);
-  new_size = ((gsize) 1) << g_bit_storage (MAX (GDK_ARRAY_REAL_SIZE (n), 16) - 1);
+  /* capacity * 2 can overflow, that's why we MAX() */
+  new_capacity = MAX (GDK_ARRAY_REAL_SIZE (n), capacity * 2);
 
 #ifdef GDK_ARRAY_PREALLOC
   if (self->start == self->preallocated)
     {
-      self->start = g_new (_T_, new_size);
+      self->start = g_new (_T_, new_capacity);
       memcpy (self->start, self->preallocated, sizeof (_T_) * GDK_ARRAY_REAL_SIZE (size));
     }
   else
@@ -196,15 +203,15 @@ gdk_array(reserve) (GdkArray *self,
 #ifdef GDK_ARRAY_NULL_TERMINATED
   if (self->start == NULL)
     {
-      self->start = g_new (_T_, new_size);
+      self->start = g_new (_T_, new_capacity);
       *self->start = *(_T_[1]) { 0 };
     }
   else
 #endif
-    self->start = g_renew (_T_, self->start, new_size);
+    self->start = g_renew (_T_, self->start, new_capacity);
 
   self->end = self->start + size;
-  self->end_allocation = self->start + new_size;
+  self->end_allocation = self->start + new_capacity;
 #ifdef GDK_ARRAY_NULL_TERMINATED
   self->end_allocation--;
 #endif
@@ -312,6 +319,7 @@ gdk_array(get) (const GdkArray *self,
 #undef gdk_array_paste
 #undef gdk_array
 #undef GDK_ARRAY_REAL_SIZE
+#undef GDK_ARRAY_MAX_SIZE
 
 #undef GDK_ARRAY_BY_VALUE
 #undef GDK_ARRAY_ELEMENT_TYPE

gdk/gdkcairo.c

@@ -21,6 +21,9 @@
 
 #include "gdkrgba.h"
 #include "gdktexture.h"
+#include "gdkcolorstate.h"
+#include "gdkcolorprivate.h"
+#include "gdkmemoryformatprivate.h"
 
 #include <math.h>
 
@@ -35,14 +38,20 @@ void
 gdk_cairo_set_source_rgba (cairo_t       *cr,
                            const GdkRGBA *rgba)
 {
+  GdkColor color;
+  const float *components;
+
   g_return_if_fail (cr != NULL);
   g_return_if_fail (rgba != NULL);
 
+  gdk_color_convert_rgba (&color, gdk_cairo_get_color_state (cr), rgba);
+  components = gdk_color_get_components (&color);
   cairo_set_source_rgba (cr,
-                         rgba->red,
-                         rgba->green,
-                         rgba->blue,
-                         rgba->alpha);
+                         components[0],
+                         components[1],
+                         components[2],
+                         gdk_color_get_alpha (&color));
+  gdk_color_finish (&color);
 }
 
 /**
@@ -303,3 +312,98 @@ gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
 
   return region;
 }
+
+static cairo_user_data_key_t color_state_key;
+
+/**
+ * gdk_cairo_surface_set_color_state:
+ * @surface: a surface
+ * @color_state: the color state to attach to the surface
+ *
+ * Attaches a `GdkColorState` to the Cairo surface.
+ *
+ * This is just auxiliary data for use by GTK, no Cairo functions
+ * do interact with this information.
+ *
+ * Note that all Cairo compositing operations are assumed to happen
+ * in a linear RGB color state, so if you want to use the surface
+ * as a target for rendering in a color managed way, you should use
+ * such a color state.
+ *
+ * The default color state is assumed to be sRGB, which is not
+ * linear.
+ *
+ * Since: 4.16
+ */
+void
+gdk_cairo_surface_set_color_state (cairo_surface_t *surface,
+                                   GdkColorState   *color_state)
+{
+  g_return_if_fail (surface != NULL);
+  g_return_if_fail (GDK_IS_COLOR_STATE (color_state));
+
+  cairo_surface_set_user_data (surface,
+                               &color_state_key,
+                               g_object_ref (color_state),
+                               g_object_unref);
+}
+
+/**
+ * gdk_cairo_surface_get_color_state:
+ * @surface: a surface
+ *
+ * Gets the color state GTK assumes for the surface.
+ *
+ * See [method@Gdk.CairoSurface.set_color_state] for details.
+ *
+ * Returns: (transfer none): the color state
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_cairo_surface_get_color_state (cairo_surface_t *surface)
+{
+  GdkColorState *color_state;
+
+  g_return_val_if_fail (surface != NULL, gdk_color_state_get_srgb ());
+
+  color_state = cairo_surface_get_user_data (surface, &color_state_key);
+  if (color_state == NULL)
+    color_state = gdk_color_state_get_srgb ();
+
+  return color_state;
+}
+
+/**
+ * gdk_cairo_get_color_state:
+ * @cr: a cairo context
+ *
+ * Gets the color state GTK assumes for the cairo context.
+ *
+ * Returns: (transfer none): the color state
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_cairo_get_color_state (cairo_t *cr)
+{
+  GdkColorState *color_state;
+  cairo_surface_t *surface;
+
+  g_return_val_if_fail (cr != NULL, gdk_color_state_get_srgb ());
+
+  surface = cairo_get_group_target (cr);
+  color_state = cairo_surface_get_user_data (surface, &color_state_key);
+  if (color_state != NULL)
+    return color_state;
+
+  /* theoretically, we should walk the whole group stack, but I don't
+   * think Cairo lets us do that
+   */
+  surface = cairo_get_target (cr);
+  color_state = cairo_surface_get_user_data (surface, &color_state_key);
+  if (color_state != NULL)
+    return color_state;
+
+  return gdk_color_state_get_srgb ();
+}

gdk/gdkcairo.h

@@ -44,9 +44,15 @@ void       gdk_cairo_region             (cairo_t              *cr,
                                          const cairo_region_t *region);
 
 GDK_AVAILABLE_IN_ALL
-cairo_region_t *
-           gdk_cairo_region_create_from_surface
-                                        (cairo_surface_t      *surface);
+cairo_region_t *        gdk_cairo_region_create_from_surface    (cairo_surface_t        *surface);
+
+GDK_AVAILABLE_IN_4_16
+void                    gdk_cairo_surface_set_color_state       (cairo_surface_t        *surface,
+                                                                 GdkColorState          *color_state);
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_cairo_surface_get_color_state       (cairo_surface_t        *surface);
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_cairo_get_color_state               (cairo_t                *cr);
 
 GDK_DEPRECATED_IN_4_6_FOR(gdk_gl_texture_new)
 void       gdk_cairo_draw_from_gl (cairo_t              *cr,

gdk/gdkclipboard.c

@@ -522,8 +522,6 @@ gdk_clipboard_get_content (GdkClipboard *clipboard)
  *
  * If the clipboard is not local, this function does nothing but report success.
  *
- * The @callback must call [method@Gdk.Clipboard.store_finish].
- *
  * The purpose of this call is to preserve clipboard contents beyond the
  * lifetime of an application, so this function is typically called on
  * exit. Depending on the platform, the functionality may not be available
@@ -638,9 +636,6 @@ gdk_clipboard_read_internal (GdkClipboard        *clipboard,
  * Asynchronously requests an input stream to read the @clipboard's
  * contents from.
  *
- * When the operation is finished @callback will be called. You must then
- * call [method@Gdk.Clipboard.read_finish] to get the result of the operation.
- *
  * The clipboard will choose the most suitable mime type from the given list
  * to fulfill the request, preferring the ones listed first.
  */
@@ -834,9 +829,6 @@ gdk_clipboard_read_value_internal (GdkClipboard        *clipboard,
  * Asynchronously request the @clipboard contents converted to the given
  * @type.
  *
- * When the operation is finished @callback will be called. You must then call
- * [method@Gdk.Clipboard.read_value_finish] to get the resulting `GValue`.
- *
  * For local clipboard contents that are available in the given `GType`,
  * the value will be copied directly. Otherwise, GDK will try to use
  * [func@content_deserialize_async] to convert the clipboard's data.
@@ -895,9 +887,6 @@ gdk_clipboard_read_value_finish (GdkClipboard  *clipboard,
  *
  * Asynchronously request the @clipboard contents converted to a `GdkPixbuf`.
  *
- * When the operation is finished @callback will be called. You must then
- * call [method@Gdk.Clipboard.read_texture_finish] to get the result.
- *
  * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
  * Use that function or [method@Gdk.Clipboard.read_async] directly if you
  * need more control over the operation.
@@ -960,9 +949,6 @@ gdk_clipboard_read_texture_finish (GdkClipboard  *clipboard,
  *
  * Asynchronously request the @clipboard contents converted to a string.
  *
- * When the operation is finished @callback will be called. You must then
- * call [method@Gdk.Clipboard.read_text_finish] to get the result.
- *
  * This is a simple wrapper around [method@Gdk.Clipboard.read_value_async].
  * Use that function or [method@Gdk.Clipboard.read_async] directly if you
  * need more control over the operation.

gdk/gdkcolor.c

@@ -0,0 +1,104 @@
+/* GDK - The GIMP Drawing Kit
+ *
+ * Copyright (C) 2021 Benjamin Otte
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "config.h"
+
+#include "gdkcolorprivate.h"
+#include "gdkcolorstateprivate.h"
+
+#include <lcms2.h>
+
+void
+gdk_color_convert (GdkColor        *self,
+                   GdkColorState   *color_state,
+                   const GdkColor  *other)
+{
+  GdkColorStateTransform *tf;
+
+  gdk_color_init (self, color_state, other->alpha, NULL);
+
+  tf = gdk_color_state_get_transform (gdk_color_state_get_srgb (), color_state, FALSE);
+  gdk_color_state_transform (tf,
+                             (float *) gdk_color_get_components (other),
+                             (float *) gdk_color_get_components (self),
+                             1);
+}
+
+void
+gdk_color_convert_rgba (GdkColor        *self,
+                        GdkColorState   *color_state,
+                        const GdkRGBA   *rgba)
+{
+  GdkColorStateTransform *tf;
+
+  gdk_color_init (self, color_state, rgba->alpha, NULL);
+
+  tf = gdk_color_state_get_transform (gdk_color_state_get_srgb (), color_state, FALSE);
+  gdk_color_state_transform (tf,
+                            (float[3]) { rgba->red, rgba->green, rgba->blue },
+                            (float *) gdk_color_get_components (self),
+                            1);
+  gdk_color_state_transform_free (tf);
+}
+
+void
+gdk_color_mix (GdkColor        *self,
+               GdkColorState   *color_state,
+               const GdkColor  *src1,
+               const GdkColor  *src2,
+               double           progress)
+{
+  if (src1->color_state != color_state)
+    {
+      GdkColor tmp;
+      gdk_color_convert (&tmp, color_state, src1);
+      gdk_color_mix (self, color_state, &tmp, src2, progress);
+    }
+  else if (src2->color_state != color_state)
+    {
+      GdkColor tmp;
+      gdk_color_convert (&tmp, color_state, src2);
+      gdk_color_mix (self, color_state, src1, &tmp, progress);
+    }
+  else
+    {
+      gsize i;
+      const float *s1, *s2;
+      float *d;
+
+      gdk_color_init (self,
+                      color_state,
+                      src1->alpha * (1.0 - progress) + src2->alpha * progress,
+                      NULL);
+
+      d = (float *) gdk_color_get_components (self);
+      s1 = gdk_color_get_components (src1);
+      s2 = gdk_color_get_components (src2);
+
+      if (self->alpha == 0)
+        {
+          for (i = 0; i < 3; i++)
+            d[i] = s1[i] * (1.0 - progress) + s2[i] * progress;
+        }
+      else
+        {
+          for (i = 0; i < 3; i++)
+            d[i] = (s1[i] * src1->alpha * (1.0 - progress) + s2[i] * src2->alpha * progress) / self->alpha;
+        }
+    }
+}

gdk/gdkcolorprivate.h

@@ -0,0 +1,61 @@
+/* GDK - The GIMP Drawing Kit
+ *
+ * Copyright (C) 2021 Benjamin Otte
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <gdk/gdkcolorstate.h>
+#include <gdk/gdkrgba.h>
+
+typedef struct _GdkColor GdkColor;
+
+struct _GdkColor
+{
+  GdkColorState *color_state;
+  float alpha;
+  float values[3];
+};
+
+G_STATIC_ASSERT (sizeof (GdkColor) % sizeof (gpointer) == 0);
+
+static inline void              gdk_color_init                          (GdkColor               *self,
+                                                                         GdkColorState          *color_state,
+                                                                         float                   alpha,
+                                                                         float                   components[3]);
+static inline void              gdk_color_init_from_rgba                (GdkColor               *self,
+                                                                         const GdkRGBA          *rgba);
+static inline void              gdk_color_finish                        (GdkColor               *self);
+
+void                            gdk_color_convert                       (GdkColor               *self,
+                                                                         GdkColorState          *color_state,
+                                                                         const GdkColor         *other);
+void                            gdk_color_convert_rgba                  (GdkColor               *self,
+                                                                         GdkColorState          *color_state,
+                                                                         const GdkRGBA          *rgba);
+void                            gdk_color_mix                           (GdkColor               *self,
+                                                                         GdkColorState          *color_state,
+                                                                         const GdkColor         *src1,
+                                                                         const GdkColor         *src2,
+                                                                         double                  progress);
+
+static inline GdkColorState *   gdk_color_get_color_state               (const GdkColor         *self);
+static inline float             gdk_color_get_alpha                     (const GdkColor         *self);
+static inline const float *     gdk_color_get_components                (const GdkColor         *self);
+
+#include "gdkcolorprivateimpl.h"
+
+G_END_DECLS

gdk/gdkcolorprivateimpl.h

@@ -0,0 +1,63 @@
+/* GDK - The GIMP Drawing Kit
+ *
+ * Copyright (C) 2021 Benjamin Otte
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+static inline void
+gdk_color_init (GdkColor        *self,
+                GdkColorState   *color_state,
+                float            alpha,
+                float            components[3])
+{
+  self->color_state = g_object_ref (color_state);
+  self->alpha = alpha;
+  if (components)
+    memcpy (self->values, components, sizeof (float) * 3);
+}
+
+static inline void
+gdk_color_init_from_rgba (GdkColor      *self,
+                          const GdkRGBA *rgba)
+{
+  gdk_color_init (self,
+                  gdk_color_state_get_srgb (),
+                  rgba->alpha,
+                  (float[3]) { rgba->red, rgba->green, rgba->blue });
+}
+
+static inline void
+gdk_color_finish (GdkColor *self)
+{
+  g_object_unref (self->color_state);
+}
+
+static inline GdkColorState *
+gdk_color_get_color_state (const GdkColor *self)
+{
+  return self->color_state;
+}
+
+static inline float
+gdk_color_get_alpha (const GdkColor *self)
+{
+  return self->alpha;
+}
+
+static inline const float *
+gdk_color_get_components (const GdkColor *self)
+{
+  return self->values;
+}

gdk/gdkcolorstate.c

@@ -0,0 +1,405 @@
+/* gdkcolorstate.c
+ *
+ * Copyright 2024 Matthias Clasen
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "config.h"
+
+#include "gdkcolorstateprivate.h"
+
+#include <glib/gi18n-lib.h>
+
+#include "gdknamedcolorstateprivate.h"
+#include "gdklcmscolorstateprivate.h"
+
+#include "gtk/gtkcolorutilsprivate.h"
+
+
+G_DEFINE_TYPE (GdkColorState, gdk_color_state, G_TYPE_OBJECT)
+
+static void
+gdk_color_state_init (GdkColorState *self)
+{
+}
+
+static GBytes *
+gdk_color_state_default_save_to_icc_profile (GdkColorState  *self,
+                                             GError        **error)
+{
+  g_set_error_literal (error, G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
+                       _("This color state does not support ICC profiles"));
+  return NULL;
+}
+
+static gboolean
+gdk_color_state_default_equal (GdkColorState *self,
+                               GdkColorState *other)
+{
+  return self == other;
+}
+
+static const char *
+gdk_color_state_default_get_name (GdkColorState *self)
+{
+  return "color state";
+}
+
+static GdkMemoryDepth
+gdk_color_state_default_get_min_depth (GdkColorState *self)
+{
+  return GDK_MEMORY_U8;
+}
+
+static void
+gdk_color_state_class_init (GdkColorStateClass *class)
+{
+  class->save_to_icc_profile = gdk_color_state_default_save_to_icc_profile;
+  class->equal = gdk_color_state_default_equal;
+  class->get_name = gdk_color_state_default_get_name;
+  class->get_min_depth = gdk_color_state_default_get_min_depth;
+}
+
+/**
+ * gdk_color_state_equal:
+ * @cs1: a `GdkColorState`
+ * @cs2: another `GdkColorStatee`
+ *
+ * Compares two `GdkColorStates` for equality.
+ *
+ * Note that this function is not guaranteed to be perfect and two objects
+ * describing the same color state may compare not equal. However, different
+ * color state will never compare equal.
+ *
+ * Returns: %TRUE if the two color states compare equal
+ *
+ * Since: 4.16
+ */
+gboolean
+gdk_color_state_equal (GdkColorState *cs1,
+                       GdkColorState *cs2)
+{
+  if (cs1 == cs2)
+    return TRUE;
+
+  if (GDK_COLOR_STATE_GET_CLASS (cs1) != GDK_COLOR_STATE_GET_CLASS (cs2))
+    return FALSE;
+
+  return GDK_COLOR_STATE_GET_CLASS (cs1)->equal (cs1, cs2);
+}
+
+/**
+ * gdk_color_state_is_linear:
+ * @self: a `GdkColorState`
+ *
+ * Returns whether the color state is linear.
+ *
+ * Returns: `TRUE` if the color state is linear
+ * Since: 4.16
+ */
+gboolean
+gdk_color_state_is_linear (GdkColorState *self)
+{
+  g_return_val_if_fail (GDK_IS_COLOR_STATE (self), FALSE);
+
+  return self == gdk_color_state_get_srgb_linear ();
+}
+
+/**
+ * gdk_color_state_save_to_icc_profile:
+ * @self: a `GdkColorState`
+ * @error: Return location for an error
+ *
+ * Saves the color state to an
+ * [ICC profile](https://en.wikipedia.org/wiki/ICC_profile).
+ *
+ * Some color state cannot be represented as ICC profiles. In
+ * that case, an error will be set and %NULL will be returned.
+ *
+ * Returns: (nullable): A new `GBytes` containing the ICC profile
+ *
+ * Since: 4.16
+ */
+GBytes *
+gdk_color_state_save_to_icc_profile (GdkColorState  *self,
+                                     GError        **error)
+{
+  g_return_val_if_fail (GDK_IS_COLOR_STATE (self), NULL);
+  g_return_val_if_fail (error == NULL || *error == NULL, NULL);
+
+  return GDK_COLOR_STATE_GET_CLASS (self)->save_to_icc_profile (self, error);
+}
+
+GdkMemoryDepth
+gdk_color_state_get_min_depth (GdkColorState *self)
+{
+  return GDK_COLOR_STATE_GET_CLASS (self)->get_min_depth (self);
+}
+
+const char *
+gdk_color_state_get_name (GdkColorState *self)
+{
+  return GDK_COLOR_STATE_GET_CLASS (self)->get_name (self);
+}
+
+typedef void (* StepFunc) (float  s0, float  s1, float  s2,
+                           float *d0, float *d1, float *d2);
+
+
+struct _GdkColorStateTransform
+{
+  cmsHTRANSFORM transform;
+  int n_funcs;
+  StepFunc funcs[10];
+  gboolean cms_first;
+  gboolean copy_alpha;
+};
+
+static void
+transform_list_append (GdkColorStateTransform *tf,
+                       StepFunc                func)
+{
+  g_assert (tf->n_funcs < G_N_ELEMENTS (tf->funcs));
+  tf->funcs[tf->n_funcs] = func;
+  tf->n_funcs++;
+}
+
+static struct {
+  GdkColorStateId n1, n2;
+  StepFunc func;
+} functions[] = {
+  { GDK_COLOR_STATE_HWB, GDK_COLOR_STATE_SRGB, gtk_hwb_to_rgb },
+  { GDK_COLOR_STATE_SRGB, GDK_COLOR_STATE_HWB, gtk_rgb_to_hwb },
+  { GDK_COLOR_STATE_HSL, GDK_COLOR_STATE_SRGB, gtk_hsl_to_rgb },
+  { GDK_COLOR_STATE_SRGB, GDK_COLOR_STATE_HSL, gtk_rgb_to_hsl },
+  { GDK_COLOR_STATE_SRGB_LINEAR, GDK_COLOR_STATE_SRGB, gtk_rgb_to_linear_srgb },
+  { GDK_COLOR_STATE_SRGB, GDK_COLOR_STATE_SRGB_LINEAR, gtk_linear_srgb_to_rgb },
+  { GDK_COLOR_STATE_SRGB_LINEAR, GDK_COLOR_STATE_OKLAB, gtk_linear_srgb_to_oklab },
+  { GDK_COLOR_STATE_OKLAB, GDK_COLOR_STATE_SRGB_LINEAR, gtk_oklab_to_linear_srgb },
+  { GDK_COLOR_STATE_OKLAB, GDK_COLOR_STATE_OKLCH, gtk_oklab_to_oklch },
+  { GDK_COLOR_STATE_OKLCH, GDK_COLOR_STATE_OKLAB, gtk_oklch_to_oklab },
+};
+
+static gpointer
+find_function (int i, int j)
+{
+  for (int k = 0; k < G_N_ELEMENTS (functions); k++)
+    {
+      if (functions[k].n1 == i && functions[k].n2 == j)
+        return functions[k].func;
+    }
+
+  return NULL;
+}
+
+static GdkColorStateId line1[] = { GDK_COLOR_STATE_SRGB,
+                                   GDK_COLOR_STATE_SRGB_LINEAR,
+                                   GDK_COLOR_STATE_OKLAB,
+                                   GDK_COLOR_STATE_OKLCH };
+static GdkColorStateId line2[] = { GDK_COLOR_STATE_HSL,
+                                   GDK_COLOR_STATE_SRGB,
+                                   GDK_COLOR_STATE_HWB};
+
+static void
+collect_functions (GdkColorStateTransform *tf,
+                   GdkColorStateId         line[],
+                   int                     si,
+                   int                     di)
+{
+  int inc = di < si ? -1 : 1;
+  int i0, i;
+
+  i0 = i = si;
+  do
+    {
+      i += inc;
+      transform_list_append (tf, find_function (line[i0], line[i]));
+      i0 = i;
+    }
+   while (i != di);
+}
+
+static void
+get_transform_list (GdkColorStateTransform *tf,
+                    GdkColorState          *from,
+                    GdkColorState          *to)
+{
+  GdkColorStateId sn, dn;
+  int si, di, sii, dii;
+
+  sn = gdk_named_color_state_get_id (from);
+  dn = gdk_named_color_state_get_id (to);
+
+  for (int i = 0; i < G_N_ELEMENTS (line1); i++)
+    {
+      if (line1[i] == sn)
+        si = i;
+      if (line1[i] == dn)
+        di = i;
+    }
+
+  if (si > -1 && di > -1)
+    {
+      collect_functions (tf, line1, si, di);
+      return;
+    }
+
+  for (int i = 0; i < G_N_ELEMENTS (line2); i++)
+    {
+      if (line2[i] == sn)
+        sii = i;
+      if (line2[i] == dn)
+        dii = i;
+    }
+
+  if (sii > -1 && dii > -1)
+    {
+      collect_functions (tf, line2, sii, dii);
+      return;
+    }
+
+  if (si > -1 && dii > -1)
+    {
+      collect_functions (tf, line1, si, 0);
+      collect_functions (tf, line2, 1, dii);
+      return;
+    }
+
+  if (sii > -1 && di > -1)
+    {
+      collect_functions (tf, line2, sii, 1);
+      collect_functions (tf, line2, 0, di);
+      return;
+    }
+}
+
+GdkColorStateTransform *
+gdk_color_state_get_transform (GdkColorState *from,
+                               GdkColorState *to,
+                               gboolean       copy_alpha)
+{
+  GdkColorStateTransform *tf;
+
+  tf = g_new0 (GdkColorStateTransform, 1);
+
+  if (gdk_color_state_equal (from, to))
+    {
+    }
+  else if (GDK_IS_LCMS_COLOR_STATE (from) &&
+           GDK_IS_LCMS_COLOR_STATE (to))
+    {
+      tf->transform = cmsCreateTransform (gdk_lcms_color_state_get_lcms_profile (from),
+                                          TYPE_RGBA_FLT,
+                                          gdk_lcms_color_state_get_lcms_profile (to),
+                                          TYPE_RGBA_FLT,
+                                          INTENT_PERCEPTUAL,
+                                          copy_alpha ? cmsFLAGS_COPY_ALPHA : 0);
+    }
+  else if (GDK_IS_NAMED_COLOR_STATE (from) &&
+           GDK_IS_NAMED_COLOR_STATE (to))
+    {
+      get_transform_list (tf, from, to);
+    }
+  else if (GDK_IS_NAMED_COLOR_STATE (from) &&
+           GDK_IS_LCMS_COLOR_STATE (to))
+    {
+      cmsHPROFILE profile;
+
+      get_transform_list (tf, from, gdk_color_state_get_srgb ());
+
+      profile = cmsCreate_sRGBProfile ();
+      tf->transform = cmsCreateTransform (profile,
+                                          TYPE_RGBA_FLT,
+                                          gdk_lcms_color_state_get_lcms_profile (to),
+                                          TYPE_RGBA_FLT,
+                                          INTENT_PERCEPTUAL,
+                                          copy_alpha ? cmsFLAGS_COPY_ALPHA : 0);
+      cmsCloseProfile (profile);
+
+      tf->cms_first = FALSE;
+    }
+  else if (GDK_IS_LCMS_COLOR_STATE (from) &&
+           GDK_IS_NAMED_COLOR_STATE (to))
+    {
+      cmsHPROFILE profile;
+
+      profile = cmsCreate_sRGBProfile ();
+      tf->transform = cmsCreateTransform (gdk_lcms_color_state_get_lcms_profile (from),
+                                          TYPE_RGBA_FLT,
+                                          profile,
+                                          TYPE_RGBA_FLT,
+                                          INTENT_PERCEPTUAL,
+                                          copy_alpha ? cmsFLAGS_COPY_ALPHA : 0);
+      cmsCloseProfile (profile);
+
+      get_transform_list (tf, gdk_color_state_get_srgb (), to);
+
+      tf->cms_first = TRUE;
+    }
+
+  tf->copy_alpha = copy_alpha;
+
+  return tf;
+}
+
+void
+gdk_color_state_transform_free (GdkColorStateTransform *tf)
+{
+  if (tf->transform)
+    cmsDeleteTransform (tf->transform);
+  g_free (tf);
+}
+
+void
+gdk_color_state_transform (GdkColorStateTransform *tf,
+                           const float            *src,
+                           float                  *dst,
+                           int                     width)
+{
+  if (tf->copy_alpha)
+    memcpy (dst, src, sizeof (float) * 4 * width);
+  else
+    {
+      for (int i = 0; i < width * 4; i += 4)
+        {
+          dst[i] = src[i];
+          dst[i + 1] = src[i + 1];
+          dst[i + 2] = src[i + 2];
+        }
+    }
+
+  if (tf->cms_first && tf->transform)
+    cmsDoTransform (tf->transform, dst, dst, width);
+
+  if (tf->n_funcs)
+    {
+      for (int i = 0; i < width * 4; i += 4)
+        {
+          float s0 = dst[i];
+          float s1 = dst[i + 1];
+          float s2 = dst[i + 2];
+
+          for (int k = 0; k < tf->n_funcs; k++)
+            tf->funcs[k] (s0, s1, s2, &s0, &s1, &s2);
+
+          dst[i]     = s0;
+          dst[i + 1] = s1;
+          dst[i + 2] = s2;
+        }
+    }
+
+  if (!tf->cms_first && tf->transform)
+    cmsDoTransform (tf->transform, dst, dst, width);
+}

gdk/gdkcolorstate.h

@@ -0,0 +1,68 @@
+/* gdkcolorstate.h
+ *
+ * Copyright 2024 Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#if !defined (__GDK_H_INSIDE__) && !defined (GTK_COMPILATION)
+#error "Only <gdk/gdk.h> can be included directly."
+#endif
+
+#include <gdk/gdktypes.h>
+
+G_BEGIN_DECLS
+
+#define GDK_TYPE_COLOR_STATE (gdk_color_state_get_type ())
+
+GDK_AVAILABLE_IN_4_16
+GDK_DECLARE_INTERNAL_TYPE (GdkColorState, gdk_color_state, GDK, COLOR_STATE, GObject)
+
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_color_state_get_srgb (void);
+
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_color_state_get_srgb_linear (void);
+
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_color_state_get_hsl (void);
+
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_color_state_get_hwb (void);
+
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_color_state_get_oklab (void);
+
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_color_state_get_oklch (void);
+
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_color_state_new_from_icc_profile (GBytes               *icc_profile,
+                                                              GError              **error);
+
+GDK_AVAILABLE_IN_4_16
+gboolean                gdk_color_state_equal               (GdkColorState        *cs1,
+                                                             GdkColorState        *cs2);
+
+GDK_AVAILABLE_IN_4_16
+gboolean                gdk_color_state_is_linear           (GdkColorState        *self);
+
+GDK_AVAILABLE_IN_4_16
+GBytes *                gdk_color_state_save_to_icc_profile (GdkColorState        *self,
+                                                             GError              **error);
+
+
+G_END_DECLS

gdk/gdkcolorstateprivate.h

@@ -0,0 +1,40 @@
+#pragma once
+
+#include "gdkcolorstate.h"
+#include "gdkmemoryformatprivate.h"
+
+struct _GdkColorState
+{
+  GObject parent_instance;
+};
+
+struct _GdkColorStateClass
+{
+  GObjectClass parent_class;
+
+  GBytes *              (* save_to_icc_profile) (GdkColorState        *self,
+                                                 GError              **error);
+
+  gboolean              (* equal)               (GdkColorState        *self,
+                                                 GdkColorState        *other);
+
+  const char *          (* get_name)            (GdkColorState        *self);
+  GdkMemoryDepth        (* get_min_depth)       (GdkColorState        *self);
+};
+
+const char *   gdk_color_state_get_name      (GdkColorState *color_state);
+GdkMemoryDepth gdk_color_state_get_min_depth (GdkColorState *color_state);
+
+
+typedef struct _GdkColorStateTransform GdkColorStateTransform;
+
+GdkColorStateTransform * gdk_color_state_get_transform (GdkColorState           *from,
+                                                        GdkColorState           *to,
+                                                        gboolean                 copy_alpha);
+
+void                     gdk_color_state_transform_free (GdkColorStateTransform *tf);
+
+void                     gdk_color_state_transform (GdkColorStateTransform *tf,
+                                                    const float            *src,
+                                                    float                  *dst,
+                                                    int                     width);

gdk/gdkcontentdeserializer.c

@@ -540,9 +540,6 @@ deserialize_not_found (GdkContentDeserializer *deserializer)
  *
  * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
  * indicate a higher priority.
- *
- * When the operation is finished, @callback will be called. You must then
- * call [func@Gdk.content_deserialize_finish] to get the result of the operation.
  */
 void
 gdk_content_deserialize_async (GInputStream        *stream,

gdk/gdkcontentprovider.c

@@ -279,10 +279,6 @@ gdk_content_provider_content_changed (GdkContentProvider *provider)
  * Asynchronously writes the contents of @provider to @stream in the given
  * @mime_type.
  *
- * When the operation is finished @callback will be called. You must then call
- * [method@Gdk.ContentProvider.write_mime_type_finish] to get the result
- * of the operation.
- *
  * The given mime type does not need to be listed in the formats returned by
  * [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is
  * not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported.

gdk/gdkcontentserializer.c

@@ -546,9 +546,6 @@ serialize_not_found (GdkContentSerializer *serializer)
  *
  * The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers
  * indicate a higher priority.
- *
- * When the operation is finished, @callback will be called. You must then
- * call [func@Gdk.content_serialize_finish] to get the result of the operation.
  */
 void
 gdk_content_serialize_async (GOutputStream       *stream,

gdk/gdkcursor.h

@@ -52,7 +52,7 @@ GdkCursor*  gdk_cursor_new_from_name     (const char      *name,
                                           GdkCursor       *fallback);
 
 /**
- * GdkCursorGetTestureCallback:
+ * GdkCursorGetTextureCallback:
  * @cursor: the `GdkCursor`
  * @cursor_size: the nominal cursor size, in application pixels
  * @scale: the device scale

gdk/gdkdebugprivate.h

@@ -40,11 +40,12 @@ typedef enum {
   GDK_DEBUG_OFFLOAD         = 1 << 12,
 
   /* flags below are influencing behavior */
+  GDK_DEBUG_SRGB            = 1 << 13,
   GDK_DEBUG_PORTALS         = 1 << 14,
   GDK_DEBUG_NO_PORTALS      = 1 << 15,
   GDK_DEBUG_GL_DISABLE      = 1 << 16,
   GDK_DEBUG_GL_NO_FRACTIONAL= 1 << 17,
-
+  GDK_DEBUG_FORCE_OFFLOAD   = 1 << 18,
   GDK_DEBUG_GL_DISABLE_GL   = 1 << 19,
   GDK_DEBUG_GL_DISABLE_GLES = 1 << 20,
   GDK_DEBUG_GL_PREFER_GL    = 1 << 21,

gdk/gdkdmabuf.c

@@ -24,6 +24,7 @@
 #include "gdkdmabuffourccprivate.h"
 #include "gdkdmabuftextureprivate.h"
 #include "gdkmemoryformatprivate.h"
+#include "gdkcolorstate.h"
 
 #ifdef HAVE_DMABUF
 #include <sys/mman.h>
@@ -144,8 +145,8 @@ struct _YUVCoefficients
 };
 
 /* multiplied by 65536 */
-//static const YUVCoefficients itu601_narrow = { 104597, -25675, -53279, 132201 };
-static const YUVCoefficients itu601_wide = { 74711, -25864, -38050, 133176 };
+static const YUVCoefficients itu601_narrow = { 104597, -25675, -53279, 132201 };
+//static const YUVCoefficients itu601_wide = { 74711, -25864, -38050, 133176 };
 
 static inline void
 get_uv_values (const YUVCoefficients *coeffs,
@@ -229,7 +230,7 @@ download_nv12 (guchar          *dst_data,
           int r, g, b;
           gsize xs, ys;
 
-          get_uv_values (&itu601_wide, uv_data[x / X_SUB * 2 + U], uv_data[x / X_SUB * 2 + V], &r, &g, &b);
+          get_uv_values (&itu601_narrow, uv_data[x / X_SUB * 2 + U], uv_data[x / X_SUB * 2 + V], &r, &g, &b);
 
           for (ys = 0; ys < Y_SUB && y + ys < height; ys++)
             for (xs = 0; xs < X_SUB && x + xs < width; xs++)
@@ -309,7 +310,7 @@ download_yuv_3 (guchar          *dst_data,
           int r, g, b;
           gsize xs, ys;
 
-          get_uv_values (&itu601_wide, u_data[x / X_SUB], v_data[x / X_SUB], &r, &g, &b);
+          get_uv_values (&itu601_narrow, u_data[x / X_SUB], v_data[x / X_SUB], &r, &g, &b);
 
           for (ys = 0; ys < Y_SUB && y + ys < height; ys++)
             for (xs = 0; xs < X_SUB && x + xs < width; xs++)
@@ -365,7 +366,7 @@ download_yuyv (guchar          *dst_data,
         {
           int r, g, b;
 
-          get_uv_values (&itu601_wide, src_data[2 * x + U], src_data[2 * x + V], &r, &g, &b);
+          get_uv_values (&itu601_narrow, src_data[2 * x + U], src_data[2 * x + V], &r, &g, &b);
           set_rgb_values (&dst_data[3 * x], src_data[2 * x + Y1], r, g, b);
           if (x + 1 < width)
             set_rgb_values (&dst_data[3 * (x + 1)], src_data[2 * x + Y2], r, g, b);
@@ -2062,12 +2063,15 @@ out:
 void
 gdk_dmabuf_download_mmap (GdkTexture      *texture,
                           GdkMemoryFormat  format,
+                          GdkColorState   *color_state,
                           guchar          *data,
                           gsize            stride)
 {
   GdkMemoryFormat src_format = gdk_texture_get_format (texture);
+  GdkColorState *src_color_state = gdk_texture_get_color_state (texture);
 
-  if (format == src_format)
+  if (format == src_format &&
+      gdk_color_state_equal (color_state, src_color_state))
     gdk_dmabuf_do_download_mmap (texture, data, stride);
   else
     {
@@ -2083,8 +2087,10 @@ gdk_dmabuf_download_mmap (GdkTexture      *texture,
 
       gdk_dmabuf_do_download_mmap (texture, src_data, src_stride);
 
-      gdk_memory_convert (data, stride, format,
-                          src_data, src_stride, src_format,
+      gdk_memory_convert (data, stride,
+                          format, color_state,
+                          src_data, src_stride,
+                          src_format, src_color_state,
                           width, height);
 
       g_free (src_data);

gdk/gdkdmabufdownloader.c

@@ -35,6 +35,7 @@ void
 gdk_dmabuf_downloader_download (GdkDmabufDownloader *self,
                                 GdkDmabufTexture    *texture,
                                 GdkMemoryFormat      format,
+                                GdkColorState       *color_state,
                                 guchar              *data,
                                 gsize                stride)
 {
@@ -43,6 +44,6 @@ gdk_dmabuf_downloader_download (GdkDmabufDownloader *self,
   g_return_if_fail (GDK_IS_DMABUF_DOWNLOADER (self));
 
   iface = GDK_DMABUF_DOWNLOADER_GET_IFACE (self);
-  iface->download (self, texture, format, data, stride);
+  iface->download (self, texture, format, color_state, data, stride);
 }
 

gdk/gdkdmabufdownloaderprivate.h

@@ -20,6 +20,7 @@ struct _GdkDmabufDownloaderInterface
   void                  (* download)                            (GdkDmabufDownloader            *downloader,
                                                                  GdkDmabufTexture               *texture,
                                                                  GdkMemoryFormat                 format,
+                                                                 GdkColorState                  *color_state,
                                                                  guchar                         *data,
                                                                  gsize                           stride);
 };
@@ -31,6 +32,7 @@ gboolean                gdk_dmabuf_downloader_supports          (GdkDmabufDownlo
 void                    gdk_dmabuf_downloader_download          (GdkDmabufDownloader            *downloader,
                                                                  GdkDmabufTexture               *texture,
                                                                  GdkMemoryFormat                 format,
+                                                                 GdkColorState                  *color_state,
                                                                  guchar                         *data,
                                                                  gsize                           stride);
 

gdk/gdkdmabufegl.c

@@ -163,6 +163,8 @@ gdk_dmabuf_get_egl_downloader (GdkDisplay              *display,
     return NULL;
 
   previous = gdk_gl_context_get_current ();
+  if (previous)
+    g_object_ref (previous);
   formats = gdk_dmabuf_formats_builder_new ();
   external = gdk_dmabuf_formats_builder_new ();
 
@@ -194,7 +196,10 @@ gdk_dmabuf_get_egl_downloader (GdkDisplay              *display,
     }
 
   if (previous)
-    gdk_gl_context_make_current (previous);
+    {
+      gdk_gl_context_make_current (previous);
+      g_object_unref (previous);
+    }
 
   return GDK_DMABUF_DOWNLOADER (renderer);
 }
@@ -239,7 +244,7 @@ gdk_dmabuf_egl_create_image (GdkDisplay      *display,
   attribs[i++] = EGL_YUV_COLOR_SPACE_HINT_EXT;
   attribs[i++] = EGL_ITU_REC601_EXT;
   attribs[i++] = EGL_SAMPLE_RANGE_HINT_EXT;
-  attribs[i++] = EGL_YUV_FULL_RANGE_EXT;
+  attribs[i++] = EGL_YUV_NARROW_RANGE_EXT;
 
 #define ADD_PLANE(plane) \
   { \
@@ -265,6 +270,7 @@ gdk_dmabuf_egl_create_image (GdkDisplay      *display,
   if (dmabuf->n_planes > 3) ADD_PLANE (3);
 
   attribs[i++] = EGL_NONE;
+  g_assert (i < G_N_ELEMENTS (attribs));
 
   image = eglCreateImageKHR (egl_display,
                              EGL_NO_CONTEXT,

gdk/gdkdmabufprivate.h

@@ -27,6 +27,7 @@ struct _GdkDmabuf
 GdkDmabufFormats *          gdk_dmabuf_get_mmap_formats         (void) G_GNUC_CONST;
 void                        gdk_dmabuf_download_mmap            (GdkTexture                     *texture,
                                                                  GdkMemoryFormat                 format,
+                                                                 GdkColorState                  *color_state,
                                                                  guchar                         *data,
                                                                  gsize                           stride);
 

gdk/gdkdmabuftexture.c

@@ -62,6 +62,13 @@ struct _GdkDmabufTextureClass
   GdkTextureClass parent_class;
 };
 
+/**
+ * gdk_dmabuf_error_quark:
+ *
+ * Registers an error quark for [class@Gdk.DmabufTexture] errors.
+ *
+ * Returns: the error quark
+ **/
 G_DEFINE_QUARK (gdk-dmabuf-error-quark, gdk_dmabuf_error)
 
 G_DEFINE_TYPE (GdkDmabufTexture, gdk_dmabuf_texture, GDK_TYPE_TEXTURE)
@@ -89,6 +96,7 @@ struct _Download
 {
   GdkDmabufTexture *texture;
   GdkMemoryFormat format;
+  GdkColorState *color_state;
   guchar *data;
   gsize stride;
   volatile int spinlock;
@@ -102,6 +110,7 @@ gdk_dmabuf_texture_invoke_callback (gpointer data)
   gdk_dmabuf_downloader_download (download->texture->downloader,
                                   download->texture,
                                   download->format,
+                                  download->color_state,
                                   download->data,
                                   download->stride);
 
@@ -113,16 +122,17 @@ gdk_dmabuf_texture_invoke_callback (gpointer data)
 static void
 gdk_dmabuf_texture_download (GdkTexture      *texture,
                              GdkMemoryFormat  format,
+                             GdkColorState   *color_state,
                              guchar          *data,
                              gsize            stride)
 {
   GdkDmabufTexture *self = GDK_DMABUF_TEXTURE (texture);
-  Download download = { self, format, data, stride, 0 };
+  Download download = { self, format, color_state, data, stride, 0 };
 
   if (self->downloader == NULL)
     {
 #ifdef HAVE_DMABUF
-      gdk_dmabuf_download_mmap (texture, format, data, stride);
+      gdk_dmabuf_download_mmap (texture, format, color_state, data, stride);
 #endif
       return;
     }
@@ -193,6 +203,7 @@ gdk_dmabuf_texture_new_from_builder (GdkDmabufTextureBuilder *builder,
   self = g_object_new (GDK_TYPE_DMABUF_TEXTURE,
                        "width", width,
                        "height", height,
+                       "color-state", gdk_dmabuf_texture_builder_get_color_state (builder),
                        NULL);
 
   g_set_object (&self->display, display);

gdk/gdkdmabuftexturebuilder.c

@@ -24,6 +24,7 @@
 #include "gdkdebugprivate.h"
 #include "gdkdisplay.h"
 #include "gdkenumtypes.h"
+#include "gdkcolorstate.h"
 #include "gdkdmabuftextureprivate.h"
 #include "gdkdmabuftexturebuilderprivate.h"
 
@@ -41,6 +42,8 @@ struct _GdkDmabufTextureBuilder
 
   GdkDmabuf dmabuf;
 
+  GdkColorState *color_state;
+
   GdkTexture *update_texture;
   cairo_region_t *update_region;
 };
@@ -124,6 +127,7 @@ enum
   PROP_MODIFIER,
   PROP_PREMULTIPLIED,
   PROP_N_PLANES,
+  PROP_COLOR_STATE,
   PROP_UPDATE_REGION,
   PROP_UPDATE_TEXTURE,
 
@@ -141,6 +145,7 @@ gdk_dmabuf_texture_builder_dispose (GObject *object)
 
   g_clear_object (&self->update_texture);
   g_clear_pointer (&self->update_region, cairo_region_destroy);
+  g_clear_object (&self->color_state);
 
   G_OBJECT_CLASS (gdk_dmabuf_texture_builder_parent_class)->dispose (object);
 }
@@ -183,6 +188,10 @@ gdk_dmabuf_texture_builder_get_property (GObject    *object,
       g_value_set_uint (value, self->dmabuf.n_planes);
       break;
 
+    case PROP_COLOR_STATE:
+      g_value_set_object (value, self->color_state);
+      break;
+
     case PROP_UPDATE_REGION:
       g_value_set_boxed (value, self->update_region);
       break;
@@ -235,6 +244,10 @@ gdk_dmabuf_texture_builder_set_property (GObject      *object,
       gdk_dmabuf_texture_builder_set_n_planes (self, g_value_get_uint (value));
       break;
 
+    case PROP_COLOR_STATE:
+      gdk_dmabuf_texture_builder_set_color_state (self, g_value_get_object (value));
+      break;
+
     case PROP_UPDATE_REGION:
       gdk_dmabuf_texture_builder_set_update_region (self, g_value_get_boxed (value));
       break;
@@ -347,6 +360,18 @@ gdk_dmabuf_texture_builder_class_init (GdkDmabufTextureBuilderClass *klass)
                        1, GDK_DMABUF_MAX_PLANES, 1,
                        G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkDmabufTextureBuilder:color-state: (attributes org.gtk.Property.get=gdk_dmabuf_texture_builder_get_color_state org.gtk.Property.set=gdk_dmabuf_texture_builder_set_color_state)
+   *
+   * The color state of the texture.
+   *
+   * Since: 4.16
+   */
+  properties[PROP_COLOR_STATE] =
+    g_param_spec_object ("color-state", NULL, NULL,
+                         GDK_TYPE_COLOR_STATE,
+                         G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
+
   /**
    * GdkDmabufTextureBuilder:update-region: (attributes org.gtk.Property.get=gdk_dmabuf_texture_builder_get_update_region org.gtk.Property.set=gdk_dmabuf_texture_builder_set_update_region)
    *
@@ -383,6 +408,8 @@ gdk_dmabuf_texture_builder_init (GdkDmabufTextureBuilder *self)
 
   for (int i = 0; i < GDK_DMABUF_MAX_PLANES; i++)
     self->dmabuf.planes[i].fd = -1;
+
+  self->color_state = g_object_ref (gdk_color_state_get_srgb ());
 }
 
 /**
@@ -843,6 +870,44 @@ gdk_dmabuf_texture_builder_set_offset (GdkDmabufTextureBuilder *self,
   self->dmabuf.planes[plane].offset = offset;
 }
 
+/**
+ * gdk_dmabuf_texture_builder_get_color_state: (attributes org.gtk.Method.get_property=color-state)
+ * @self: a `GdkDmabufTextureBuilder`
+ *
+ * Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state().
+ *
+ * Returns: the color state
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_dmabuf_texture_builder_get_color_state (GdkDmabufTextureBuilder *self)
+{
+  g_return_val_if_fail (GDK_IS_DMABUF_TEXTURE_BUILDER (self), NULL);
+
+  return self->color_state;
+}
+
+/**
+ * gdk_dmabuf_texture_builder_set_color_state: (attributes org.gtk.Method.set_property=color-state)
+ * @self: a `GdkDmabufTextureBuilder`
+ * @color_state: a `GdkColorState`
+ *
+ * Sets the color state for the texture.
+ *
+ * Since: 4.16
+ */
+void
+gdk_dmabuf_texture_builder_set_color_state (GdkDmabufTextureBuilder *self,
+                                            GdkColorState           *color_state)
+{
+  g_return_if_fail (GDK_IS_DMABUF_TEXTURE_BUILDER (self));
+  g_return_if_fail (GDK_IS_COLOR_STATE (color_state));
+
+  if (g_set_object (&self->color_state, color_state))
+    g_object_notify_by_pspec (G_OBJECT (self), properties[PROP_COLOR_STATE]);
+}
+
 /**
  * gdk_dmabuf_texture_builder_get_update_texture: (attributes org.gtk.Method.get_property=update-texture)
  * @self: a `GdkDmabufTextureBuilder`

gdk/gdkdmabuftexturebuilder.h

@@ -100,6 +100,12 @@ void                     gdk_dmabuf_texture_builder_set_offset       (GdkDmabufT
                                                                       unsigned int                plane,
                                                                       unsigned int                offset);
 
+GDK_AVAILABLE_IN_4_16
+GdkColorState *          gdk_dmabuf_texture_builder_get_color_state    (GdkDmabufTextureBuilder  *self);
+GDK_AVAILABLE_IN_4_16
+void                     gdk_dmabuf_texture_builder_set_color_state    (GdkDmabufTextureBuilder  *self,
+                                                                        GdkColorState            *color_state);
+
 GDK_AVAILABLE_IN_4_14
 GdkTexture *             gdk_dmabuf_texture_builder_get_update_texture (GdkDmabufTextureBuilder  *self) G_GNUC_PURE;
 GDK_AVAILABLE_IN_4_14

gdk/gdkdrop.c

@@ -134,7 +134,7 @@ gdk_drop_read_local_async (GdkDrop             *self,
 
   g_object_get (priv->drag, "content", &content, NULL);
   content_formats = gdk_content_provider_ref_formats (content);
-  g_object_unref (content); 
+  g_object_unref (content);
   content_formats = gdk_content_formats_union_serialize_mime_types (content_formats);
   mime_type = gdk_content_formats_match_mime_type (content_formats, formats);
 
@@ -784,7 +784,7 @@ gdk_drop_read_value_internal (GdkDrop             *self,
   GdkContentFormats *formats;
   GValue *value;
   GTask *task;
- 
+
   g_return_if_fail (priv->state != GDK_DROP_STATE_FINISHED);
 
   task = g_task_new (self, cancellable, callback, user_data);
@@ -849,10 +849,6 @@ gdk_drop_read_value_internal (GdkDrop             *self,
  * Asynchronously request the drag operation's contents converted
  * to the given @type.
  *
- * When the operation is finished @callback will be called. You must
- * then call [method@Gdk.Drop.read_value_finish] to get the resulting
- * `GValue`.
- *
  * For local drag-and-drop operations that are available in the given
  * `GType`, the value will be copied directly. Otherwise, GDK will
  * try to use [func@Gdk.content_deserialize_async] to convert the data.

gdk/gdkevents.c

@@ -1371,6 +1371,8 @@ gdk_event_get_modifier_state (GdkEvent *event)
  * Extract the event surface relative x/y coordinates from an event.
  *
  * This position is in [surface coordinates](coordinates.html).
+ *
+ * Returns: whether the positions were set
  */
 gboolean
 gdk_event_get_position (GdkEvent *event,

gdk/gdkframeclockidle.c

@@ -192,13 +192,6 @@ compute_smooth_frame_time (GdkFrameClock *clock,
    *        and new_frame_time >= old_frame_time. */
   frames_passed = (new_frame_time - smoothed_frame_time_base + frame_interval / 2) / frame_interval;
 
-  if (frames_passed > 1)
-    gdk_profiler_add_markf ((smoothed_frame_time_base - (frame_interval * (frames_passed-1))) * 1000L,
-                            frame_interval * (frames_passed-1) * 1000L,
-                            "Dropped Frames",
-                            "%u frames may have been dropped",
-                            frames_passed-1);
-
   /* We use an approximately whole number of frames in the future from
    * last smoothed frame time. This way we avoid minor jitter in the
    * frame times making the animation speed uneven, but still animate

gdk/gdkglcontext.c

@@ -152,6 +152,13 @@ enum {
 
 static GParamSpec *properties[LAST_PROP] = { NULL, };
 
+/**
+ * gdk_gl_error_quark:
+ *
+ * Registers an error quark for [class@Gdk.GLContext] errors.
+ *
+ * Returns: the error quark
+ **/
 G_DEFINE_QUARK (gdk-gl-error-quark, gdk_gl_error)
 
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GdkGLContext, gdk_gl_context, GDK_TYPE_DRAW_CONTEXT)
@@ -1956,8 +1963,6 @@ gdk_gl_context_get_glsl_version_string (GdkGLContext *self)
         return "#version 310 es";
       else if (gdk_gl_version_greater_equal (&priv->gl_version, &GDK_GL_VERSION_INIT (3, 0)))
         return "#version 300 es";
-      else if (gdk_gl_version_greater_equal (&priv->gl_version, &GDK_GL_VERSION_INIT (3, 0)))
-        return "#version 300 es";
       else
         return "#version 100";
     }
@@ -2198,12 +2203,78 @@ gdk_gl_context_import_dmabuf (GdkGLContext    *self,
 
   gdk_display_init_dmabuf (display);
 
-  if (!gdk_dmabuf_formats_contains (display->egl_external_formats, dmabuf->fourcc, dmabuf->modifier))
+  if (gdk_dmabuf_formats_contains (display->egl_dmabuf_formats, dmabuf->fourcc, dmabuf->modifier))
     {
+      /* This is the path for modern drivers that support modifiers */
+
+      if (!gdk_dmabuf_formats_contains (display->egl_external_formats, dmabuf->fourcc, dmabuf->modifier))
+        {
+          texture_id = gdk_gl_context_import_dmabuf_for_target (self,
+                                                                width, height,
+                                                                dmabuf,
+                                                                GL_TEXTURE_2D);
+          if (texture_id == 0)
+            {
+              GDK_DISPLAY_DEBUG (display, DMABUF,
+                                 "Import of %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf failed",
+                                 width, height,
+                                 (char *) &dmabuf->fourcc, dmabuf->modifier);
+              return 0;
+            }
+
+          GDK_DISPLAY_DEBUG (display, DMABUF,
+                             "Imported %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf as GL_TEXTURE_2D texture",
+                             width, height,
+                             (char *) &dmabuf->fourcc, dmabuf->modifier);
+          *external = FALSE;
+          return texture_id;
+        }
+
+      if (!gdk_gl_context_get_use_es (self))
+        {
+          GDK_DISPLAY_DEBUG (display, DMABUF,
+                             "Can't import external_only %.4s:%#" G_GINT64_MODIFIER "x outside of GLES",
+                             (char *) &dmabuf->fourcc, dmabuf->modifier);
+          return 0;
+        }
+
       texture_id = gdk_gl_context_import_dmabuf_for_target (self,
                                                             width, height,
                                                             dmabuf,
-                                                            GL_TEXTURE_2D);
+                                                            GL_TEXTURE_EXTERNAL_OES);
+      if (texture_id == 0)
+        {
+          GDK_DISPLAY_DEBUG (display, DMABUF,
+                             "Import of external_only %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf failed",
+                             width, height,
+                             (char *) &dmabuf->fourcc, dmabuf->modifier);
+          return 0;
+        }
+
+      GDK_DISPLAY_DEBUG (display, DMABUF,
+                         "Imported %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf as GL_TEXTURE_EXTERNAL_OES texture",
+                         width, height,
+                         (char *) &dmabuf->fourcc, dmabuf->modifier);
+      *external = TRUE;
+      return texture_id;
+    }
+  else
+    {
+      /* This is the opportunistic path.
+       * We hit it both for drivers that do not support modifiers as well as for dmabufs
+       * that the driver did not explicitly advertise. */
+      int target;
+
+      if (gdk_gl_context_get_use_es (self))
+        target = GL_TEXTURE_EXTERNAL_OES;
+      else
+        target = GL_TEXTURE_2D;
+
+      texture_id = gdk_gl_context_import_dmabuf_for_target (self,
+                                                            width, height,
+                                                            dmabuf,
+                                                            target);
+
       if (texture_id == 0)
         {
           GDK_DISPLAY_DEBUG (display, DMABUF,
@@ -2214,40 +2285,13 @@ gdk_gl_context_import_dmabuf (GdkGLContext    *self,
         }
 
       GDK_DISPLAY_DEBUG (display, DMABUF,
-                         "Imported %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf as GL_TEXTURE_2D texture",
+                         "Imported %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf as %s texture",
                          width, height,
-                         (char *) &dmabuf->fourcc, dmabuf->modifier);
-      *external = FALSE;
+                         (char *) &dmabuf->fourcc, dmabuf->modifier,
+                         target == GL_TEXTURE_EXTERNAL_OES ? "GL_TEXTURE_EXTERNAL_OES" : "GL_TEXTURE_2D");
+      *external = target == GL_TEXTURE_EXTERNAL_OES;
       return texture_id;
     }
-
-  if (!gdk_gl_context_get_use_es (self))
-    {
-      GDK_DISPLAY_DEBUG (display, DMABUF,
-                         "Can't import external_only %.4s:%#" G_GINT64_MODIFIER "x outside of GLES",
-                         (char *) &dmabuf->fourcc, dmabuf->modifier);
-      return 0;
-    }
-
-  texture_id = gdk_gl_context_import_dmabuf_for_target (self,
-                                                        width, height,
-                                                        dmabuf,
-                                                        GL_TEXTURE_EXTERNAL_OES);
-  if (texture_id == 0)
-    {
-      GDK_DISPLAY_DEBUG (display, DMABUF,
-                         "Import of external_only %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf failed",
-                         width, height,
-                         (char *) &dmabuf->fourcc, dmabuf->modifier);
-      return 0;
-    }
-
-  GDK_DISPLAY_DEBUG (display, DMABUF,
-                     "Imported %dx%d %.4s:%#" G_GINT64_MODIFIER "x dmabuf as GL_TEXTURE_EXTERNAL_OES texture",
-                     width, height,
-                     (char *) &dmabuf->fourcc, dmabuf->modifier);
-  *external = TRUE;
-  return texture_id;
 }
 
 gboolean

gdk/gdkgltexture.c

@@ -24,6 +24,7 @@
 #include "gdkglcontextprivate.h"
 #include "gdkmemoryformatprivate.h"
 #include "gdkmemorytextureprivate.h"
+#include "gdkcolorstate.h"
 
 #include <epoxy/gl.h>
 
@@ -136,6 +137,7 @@ typedef struct _Download Download;
 struct _Download
 {
   GdkMemoryFormat format;
+  GdkColorState *color_state;
   guchar *data;
   gsize stride;
 };
@@ -185,13 +187,15 @@ gdk_gl_texture_do_download (GdkGLTexture *self,
 {
   GdkTexture *texture = GDK_TEXTURE (self);
   GdkMemoryFormat format;
+  GdkColorState *color_state;
   gsize expected_stride;
   Download *download = download_;
   GLint gl_internal_format;
   GLenum gl_format, gl_type;
   GLint gl_swizzle[4];
 
-  format = gdk_texture_get_format (texture),
+  format = gdk_texture_get_format (texture);
+  color_state = gdk_texture_get_color_state (texture);
   expected_stride = texture->width * gdk_memory_format_bytes_per_pixel (download->format);
 
   if (!gdk_gl_context_get_use_es (context) &&
@@ -225,9 +229,11 @@ gdk_gl_texture_do_download (GdkGLTexture *self,
           gdk_memory_convert (download->data,
                               download->stride,
                               download->format,
+                              download->color_state,
                               pixels,
                               stride,
                               format,
+                              color_state,
                               texture->width,
                               texture->height);
 
@@ -377,9 +383,11 @@ gdk_gl_texture_do_download (GdkGLTexture *self,
           gdk_memory_convert (download->data,
                               download->stride,
                               download->format,
+                              download->color_state,
                               pixels,
                               stride,
                               actual_format,
+                              color_state,
                               texture->width,
                               texture->height);
 
@@ -393,6 +401,7 @@ gdk_gl_texture_do_download (GdkGLTexture *self,
 static void
 gdk_gl_texture_download (GdkTexture      *texture,
                          GdkMemoryFormat  format,
+                         GdkColorState   *color_state,
                          guchar          *data,
                          gsize            stride)
 {
@@ -401,11 +410,12 @@ gdk_gl_texture_download (GdkTexture      *texture,
 
   if (self->saved)
     {
-      gdk_texture_do_download (self->saved, format, data, stride);
+      gdk_texture_do_download (self->saved, format, color_state, data, stride);
       return;
     }
 
   download.format = format;
+  download.color_state = color_state;
   download.data = data;
   download.stride = stride;
 
@@ -471,8 +481,7 @@ gdk_gl_texture_release (GdkGLTexture *self)
   g_return_if_fail (self->saved == NULL);
 
   texture = GDK_TEXTURE (self);
-  self->saved = GDK_TEXTURE (gdk_memory_texture_from_texture (texture,
-                                                              gdk_texture_get_format (texture)));
+  self->saved = GDK_TEXTURE (gdk_memory_texture_from_texture (texture));
 
   drop_gl_resources (self);
 }
@@ -488,6 +497,7 @@ gdk_gl_texture_new_from_builder (GdkGLTextureBuilder *builder,
   self = g_object_new (GDK_TYPE_GL_TEXTURE,
                        "width", gdk_gl_texture_builder_get_width (builder),
                        "height", gdk_gl_texture_builder_get_height (builder),
+                       "color-state", gdk_gl_texture_builder_get_color_state (builder),
                        NULL);
 
   self->context = g_object_ref (gdk_gl_texture_builder_get_context (builder));

gdk/gdkgltexturebuilder.c

@@ -23,6 +23,7 @@
 
 #include "gdkenumtypes.h"
 #include "gdkglcontext.h"
+#include "gdkcolorstate.h"
 #include "gdkgltextureprivate.h"
 
 #include <cairo-gobject.h>
@@ -38,6 +39,7 @@ struct _GdkGLTextureBuilder
   GdkMemoryFormat format;
   gboolean has_mipmap;
   gpointer sync;
+  GdkColorState *color_state;
 
   GdkTexture *update_texture;
   cairo_region_t *update_region;
@@ -75,6 +77,7 @@ enum
   PROP_HEIGHT,
   PROP_ID,
   PROP_SYNC,
+  PROP_COLOR_STATE,
   PROP_UPDATE_REGION,
   PROP_UPDATE_TEXTURE,
   PROP_WIDTH,
@@ -95,6 +98,7 @@ gdk_gl_texture_builder_dispose (GObject *object)
 
   g_clear_object (&self->update_texture);
   g_clear_pointer (&self->update_region, cairo_region_destroy);
+  g_clear_object (&self->color_state);
 
   G_OBJECT_CLASS (gdk_gl_texture_builder_parent_class)->dispose (object);
 }
@@ -133,6 +137,10 @@ gdk_gl_texture_builder_get_property (GObject    *object,
       g_value_set_pointer (value, self->sync);
       break;
 
+    case PROP_COLOR_STATE:
+      g_value_set_object (value, self->color_state);
+      break;
+
     case PROP_UPDATE_REGION:
       g_value_set_boxed (value, self->update_region);
       break;
@@ -185,6 +193,10 @@ gdk_gl_texture_builder_set_property (GObject      *object,
       gdk_gl_texture_builder_set_sync (self, g_value_get_pointer (value));
       break;
 
+    case PROP_COLOR_STATE:
+      gdk_gl_texture_builder_set_color_state (self, g_value_get_object (value));
+      break;
+
     case PROP_UPDATE_REGION:
       gdk_gl_texture_builder_set_update_region (self, g_value_get_boxed (value));
       break;
@@ -286,6 +298,18 @@ gdk_gl_texture_builder_class_init (GdkGLTextureBuilderClass *klass)
     g_param_spec_pointer ("sync", NULL, NULL,
                           G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GdkGLTextureBuilder:color-state: (attributes org.gtk.Property.get=gdk_gl_texture_builder_get_color_state org.gtk.Property.set=gdk_gl_texture_builder_set_color_state)
+   *
+   * The color state of the texture.
+   *
+   * Since: 4.16
+   */
+  properties[PROP_COLOR_STATE] =
+    g_param_spec_object ("color-state", NULL, NULL,
+                         GDK_TYPE_COLOR_STATE,
+                         G_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
+
   /**
    * GdkGLTextureBuilder:update-region: (attributes org.gtk.Property.get=gdk_gl_texture_builder_get_update_region org.gtk.Property.set=gdk_gl_texture_builder_set_update_region)
    *
@@ -329,6 +353,7 @@ static void
 gdk_gl_texture_builder_init (GdkGLTextureBuilder *self)
 {
   self->format = GDK_MEMORY_R8G8B8A8_PREMULTIPLIED;
+  self->color_state = g_object_ref (gdk_color_state_get_srgb ());
 }
 
 /**
@@ -616,6 +641,44 @@ gdk_gl_texture_builder_set_sync (GdkGLTextureBuilder *self,
   g_object_notify_by_pspec (G_OBJECT (self), properties[PROP_SYNC]);
 }
 
+/**
+ * gdk_gl_texture_builder_get_color_state: (attributes org.gtk.Method.get_property=color-state)
+ * @self: a `GdkGLTextureBuilder`
+ *
+ * Gets the color state previously set via gdk_gl_texture_builder_set_color_state().
+ *
+ * Returns: the color state
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_gl_texture_builder_get_color_state (GdkGLTextureBuilder *self)
+{
+  g_return_val_if_fail (GDK_IS_GL_TEXTURE_BUILDER (self), NULL);
+
+  return self->color_state;
+}
+
+/**
+ * gdk_gl_texture_builder_set_color_state: (attributes org.gtk.Method.set_property=color-state)
+ * @self: a `GdkGLTextureBuilder`
+ * @color_state: a `GdkColorState`
+ *
+ * Sets the color state for the texture.
+ *
+ * Since: 4.16
+ */
+void
+gdk_gl_texture_builder_set_color_state (GdkGLTextureBuilder *self,
+                                        GdkColorState       *color_state)
+{
+  g_return_if_fail (GDK_IS_GL_TEXTURE_BUILDER (self));
+  g_return_if_fail (GDK_IS_COLOR_STATE (color_state));
+
+  if (g_set_object (&self->color_state, color_state))
+    g_object_notify_by_pspec (G_OBJECT (self), properties[PROP_COLOR_STATE]);
+}
+
 /**
  * gdk_gl_texture_builder_get_format: (attributes org.gtk.Method.get_property=format)
  * @self: a `GdkGLTextureBuilder`

gdk/gdkgltexturebuilder.h

@@ -76,6 +76,12 @@ GDK_AVAILABLE_IN_4_12
 void                    gdk_gl_texture_builder_set_sync         (GdkGLTextureBuilder    *self,
                                                                  gpointer                sync);
 
+GDK_AVAILABLE_IN_4_16
+GdkColorState *         gdk_gl_texture_builder_get_color_state  (GdkGLTextureBuilder    *self);
+GDK_AVAILABLE_IN_4_16
+void                    gdk_gl_texture_builder_set_color_state  (GdkGLTextureBuilder    *self,
+                                                                 GdkColorState          *color_state);
+
 GDK_AVAILABLE_IN_4_12
 GdkTexture *            gdk_gl_texture_builder_get_update_texture (GdkGLTextureBuilder  *self) G_GNUC_PURE;
 GDK_AVAILABLE_IN_4_12

gdk/gdklcmscolorstate.c

@@ -0,0 +1,255 @@
+/* gdklcmscolorstate.c
+ *
+ * Copyright 2021 (c) Benjamin Otte
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "config.h"
+
+#include "gdklcmscolorstateprivate.h"
+
+#include <glib/gi18n-lib.h>
+
+struct _GdkLcmsColorState
+{
+  GdkColorState parent_instance;
+
+  cmsHPROFILE lcms_profile;
+};
+
+struct _GdkLcmsColorStateClass
+{
+  GdkColorStateClass parent_class;
+};
+
+G_DEFINE_TYPE (GdkLcmsColorState, gdk_lcms_color_state, GDK_TYPE_COLOR_STATE)
+
+static GBytes *
+gdk_lcms_color_state_save_to_icc_profile (GdkColorState  *state,
+                                          GError        **error)
+{
+  GdkLcmsColorState *self = GDK_LCMS_COLOR_STATE (state);
+  cmsUInt32Number size;
+  guchar *data;
+
+  size = 0;
+  if (!cmsSaveProfileToMem (self->lcms_profile, NULL, &size))
+    {
+      g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED, _("Could not prepare ICC profile"));
+      return NULL;
+    }
+
+  data = g_malloc (size);
+  if (!cmsSaveProfileToMem (self->lcms_profile, data, &size))
+    {
+      g_free (data);
+      g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED, _("Failed to save ICC profile"));
+      return NULL;
+    }
+
+  return g_bytes_new_take (data, size);
+}
+
+static gboolean
+gdk_lcms_color_state_equal (GdkColorState *cs1,
+                            GdkColorState *cs2)
+{
+  GBytes *icc1, *icc2;
+  gboolean res;
+
+  icc1 = gdk_color_state_save_to_icc_profile (cs1, NULL);
+  icc2 = gdk_color_state_save_to_icc_profile (cs2, NULL);
+
+  res = g_bytes_equal (icc1, icc2);
+
+  g_bytes_unref (icc1);
+  g_bytes_unref (icc2);
+
+  return res;
+}
+
+static void
+gdk_lcms_color_state_dispose (GObject *object)
+{
+  GdkLcmsColorState *self = GDK_LCMS_COLOR_STATE (object);
+
+  g_clear_pointer (&self->lcms_profile, cmsCloseProfile);
+
+  G_OBJECT_CLASS (gdk_lcms_color_state_parent_class)->dispose (object);
+}
+
+static const char *
+gdk_lcms_color_state_get_name (GdkColorState *self)
+{
+  static char buffer[48];
+
+  g_snprintf (buffer, sizeof (buffer), "lcms color state %p", self);
+
+  return buffer;
+}
+
+static void
+gdk_lcms_color_state_class_init (GdkLcmsColorStateClass *klass)
+{
+  GdkColorStateClass *color_state_class = GDK_COLOR_STATE_CLASS (klass);
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+
+  gobject_class->dispose = gdk_lcms_color_state_dispose;
+
+  color_state_class->save_to_icc_profile = gdk_lcms_color_state_save_to_icc_profile;
+  color_state_class->equal = gdk_lcms_color_state_equal;
+  color_state_class->get_name = gdk_lcms_color_state_get_name;
+}
+
+static void
+gdk_lcms_color_state_init (GdkLcmsColorState *self)
+{
+}
+
+GdkColorState *
+gdk_lcms_color_state_new_from_lcms_profile (cmsHPROFILE lcms_profile)
+{
+  GdkLcmsColorState *result;
+
+  result = g_object_new (GDK_TYPE_LCMS_COLOR_STATE, NULL);
+  result->lcms_profile = lcms_profile;
+
+  return GDK_COLOR_STATE (result);
+}
+
+/**
+ * gdk_color_state_new_from_icc_profile:
+ * @icc_profile: The ICC profiles given as a `GBytes`
+ * @error: Return location for an error
+ *
+ * Creates a new color state for the given ICC profile data.
+ *
+ * if the profile is not valid, %NULL is returned and an error
+ * is raised.
+ *
+ * Returns: a new `GdkColorState` or %NULL on error
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_color_state_new_from_icc_profile (GBytes  *icc_profile,
+                                      GError **error)
+{
+  cmsHPROFILE lcms_profile;
+  const guchar *data;
+  gsize size;
+
+  g_return_val_if_fail (icc_profile != NULL, NULL);
+  g_return_val_if_fail (error == NULL || *error == NULL, NULL);
+
+  data = g_bytes_get_data (icc_profile, &size);
+
+  lcms_profile = cmsOpenProfileFromMem (data, size);
+  if (lcms_profile == NULL)
+    {
+      g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED, _("Failed to load ICC profile"));
+      return NULL;
+    }
+
+  return gdk_lcms_color_state_new_from_lcms_profile (lcms_profile);
+}
+
+cmsHPROFILE
+gdk_lcms_color_state_get_lcms_profile (GdkColorState *self)
+{
+  g_return_val_if_fail (GDK_IS_LCMS_COLOR_STATE (self), NULL);
+
+  return GDK_LCMS_COLOR_STATE (self)->lcms_profile;
+}
+
+typedef struct _GdkColorTransformCache GdkColorTransformCache;
+
+struct _GdkColorTransformCache
+{
+  GdkColorState *source;
+  guint          source_type;
+  GdkColorState *dest;
+  guint          dest_type;
+};
+
+static void
+gdk_color_transform_cache_free (gpointer data)
+{
+  g_free (data);
+}
+
+static guint
+gdk_color_transform_cache_hash (gconstpointer data)
+{
+  const GdkColorTransformCache *cache = data;
+
+  return g_direct_hash (cache->source) ^
+         (g_direct_hash (cache->dest) >> 2) ^
+         ((cache->source_type << 16) | (cache->source_type >> 16)) ^
+         cache->dest_type;
+}
+
+static gboolean
+gdk_color_transform_cache_equal (gconstpointer data1,
+                                 gconstpointer data2)
+{
+  const GdkColorTransformCache *cache1 = data1;
+  const GdkColorTransformCache *cache2 = data2;
+
+  return cache1->source == cache2->source &&
+         cache1->source_type == cache2->source_type &&
+         cache1->dest == cache2->dest &&
+         cache1->dest_type == cache2->dest_type;
+}
+
+cmsHTRANSFORM *
+gdk_lcms_color_state_lookup_transform (GdkColorState *source,
+                                       guint          source_type,
+                                       GdkColorState *dest,
+                                       guint          dest_type)
+{
+  GdkColorTransformCache *entry;
+  static GHashTable *cache = NULL;
+  cmsHTRANSFORM *transform;
+
+  if (cache == NULL)
+    cache = g_hash_table_new_full (gdk_color_transform_cache_hash,
+                                   gdk_color_transform_cache_equal,
+                                   gdk_color_transform_cache_free,
+                                   cmsDeleteTransform);
+
+  transform = g_hash_table_lookup (cache,
+                                   &(GdkColorTransformCache) {
+                                     source, source_type,
+                                     dest, dest_type
+                                   });
+  if (G_UNLIKELY (transform == NULL && source && dest))
+    {
+      transform = cmsCreateTransform (gdk_lcms_color_state_get_lcms_profile (source),
+                                      source_type,
+                                      gdk_lcms_color_state_get_lcms_profile (dest),
+                                      dest_type,
+                                      INTENT_PERCEPTUAL,
+                                      cmsFLAGS_COPY_ALPHA);
+      entry = g_new (GdkColorTransformCache, 1);
+      *entry = (GdkColorTransformCache) {
+                 source, source_type,
+                 dest, dest_type
+               };
+      g_hash_table_insert (cache, entry, transform);
+    }
+
+  return transform;
+}

gdk/gdklcmscolorstateprivate.h

@@ -0,0 +1,38 @@
+/* gdklcmscolorstate.h
+ *
+ * Copyright 2021 (c) Benjamin Otte
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "gdkcolorstateprivate.h"
+
+#include <lcms2.h>
+
+G_BEGIN_DECLS
+
+#define GDK_TYPE_LCMS_COLOR_STATE (gdk_lcms_color_state_get_type ())
+
+GDK_DECLARE_INTERNAL_TYPE (GdkLcmsColorState, gdk_lcms_color_state, GDK, LCMS_COLOR_STATE, GdkColorState)
+
+GdkColorState *         gdk_lcms_color_state_new_from_lcms_profile      (cmsHPROFILE             lcms_profile);
+cmsHPROFILE             gdk_lcms_color_state_get_lcms_profile           (GdkColorState          *color_state);
+cmsHTRANSFORM *         gdk_lcms_color_state_lookup_transform           (GdkColorState          *source,
+                                                                         guint                   source_type,
+                                                                         GdkColorState          *dest,
+                                                                         guint                   dest_type);
+
+G_END_DECLS

gdk/gdkmemoryformat.c

@@ -23,8 +23,9 @@
 
 #include "gdkdmabuffourccprivate.h"
 #include "gdkglcontextprivate.h"
-
+#include "gdkcolorstateprivate.h"
 #include "gsk/gl/fp16private.h"
+#include "gtk/gtkcolorutilsprivate.h"
 
 #include <epoxy/gl.h>
 
@@ -1694,14 +1695,17 @@ void
 gdk_memory_convert (guchar              *dest_data,
                     gsize                dest_stride,
                     GdkMemoryFormat      dest_format,
+                    GdkColorState       *dest_color_state,
                     const guchar        *src_data,
                     gsize                src_stride,
                     GdkMemoryFormat      src_format,
+                    GdkColorState       *src_color_state,
                     gsize                width,
                     gsize                height)
 {
   const GdkMemoryFormatDescription *dest_desc = &memory_formats[dest_format];
   const GdkMemoryFormatDescription *src_desc = &memory_formats[src_format];
+  GdkColorStateTransform *transform;
   float *tmp;
   gsize y;
   void (*func) (guchar *, const guchar *, gsize) = NULL;
@@ -1709,7 +1713,8 @@ gdk_memory_convert (guchar              *dest_data,
   g_assert (dest_format < GDK_MEMORY_N_FORMATS);
   g_assert (src_format < GDK_MEMORY_N_FORMATS);
 
-  if (src_format == dest_format)
+  if (gdk_color_state_equal (src_color_state, dest_color_state) &&
+      src_format == dest_format)
     {
       gsize bytes_per_row = src_desc->bytes_per_pixel * width;
 
@@ -1729,7 +1734,9 @@ gdk_memory_convert (guchar              *dest_data,
       return;
     }
 
-  if (src_format == GDK_MEMORY_R8G8B8A8 && dest_format == GDK_MEMORY_R8G8B8A8_PREMULTIPLIED)
+  if (!gdk_color_state_equal (src_color_state, dest_color_state))
+    func = NULL;
+  else if (src_format == GDK_MEMORY_R8G8B8A8 && dest_format == GDK_MEMORY_R8G8B8A8_PREMULTIPLIED)
     func = r8g8b8a8_to_r8g8b8a8_premultiplied;
   else if (src_format == GDK_MEMORY_B8G8R8A8 && dest_format == GDK_MEMORY_R8G8B8A8_PREMULTIPLIED)
     func = r8g8b8a8_to_b8g8r8a8_premultiplied;
@@ -1777,15 +1784,31 @@ gdk_memory_convert (guchar              *dest_data,
       return;
     }
 
+  if (!gdk_color_state_equal (src_color_state, dest_color_state))
+    transform = gdk_color_state_get_transform (src_color_state, dest_color_state, TRUE);
+  else
+    transform = NULL;
+
   tmp = g_new (float, width * 4);
 
   for (y = 0; y < height; y++)
     {
       src_desc->to_float (tmp, src_data, width);
-      if (src_desc->alpha == GDK_MEMORY_ALPHA_PREMULTIPLIED && dest_desc->alpha == GDK_MEMORY_ALPHA_STRAIGHT)
-        unpremultiply (tmp, width);
-      else if (src_desc->alpha == GDK_MEMORY_ALPHA_STRAIGHT && dest_desc->alpha != GDK_MEMORY_ALPHA_STRAIGHT)
-        premultiply (tmp, width);
+      if (transform)
+        {
+          if (src_desc->alpha == GDK_MEMORY_ALPHA_PREMULTIPLIED)
+            unpremultiply (tmp, width);
+          gdk_color_state_transform (transform, tmp, tmp, width);
+          if (dest_desc->alpha != GDK_MEMORY_ALPHA_STRAIGHT)
+            premultiply (tmp, width);
+        }
+      else
+        {
+          if (src_desc->alpha == GDK_MEMORY_ALPHA_PREMULTIPLIED && dest_desc->alpha == GDK_MEMORY_ALPHA_STRAIGHT)
+            unpremultiply (tmp, width);
+          else if (src_desc->alpha == GDK_MEMORY_ALPHA_STRAIGHT && dest_desc->alpha != GDK_MEMORY_ALPHA_STRAIGHT)
+            premultiply (tmp, width);
+        }
       dest_desc->from_float (dest_data, tmp, width);
       src_data += src_stride;
       dest_data += dest_stride;

gdk/gdkmemoryformatprivate.h

@@ -80,9 +80,11 @@ guint32                 gdk_memory_format_get_dmabuf_fourcc (GdkMemoryFormat
 void                    gdk_memory_convert                  (guchar                     *dest_data,
                                                              gsize                       dest_stride,
                                                              GdkMemoryFormat             dest_format,
+                                                             GdkColorState              *dest_color_state,
                                                              const guchar               *src_data,
                                                              gsize                       src_stride,
                                                              GdkMemoryFormat             src_format,
+                                                             GdkColorState              *src_color_state,
                                                              gsize                       width,
                                                              gsize                       height);
 

gdk/gdkmemorytexture.c

@@ -22,6 +22,7 @@
 #include "gdkmemorytextureprivate.h"
 
 #include "gdkmemoryformatprivate.h"
+#include "gdkcolorstate.h"
 #include "gsk/gl/fp16private.h"
 
 /**
@@ -58,6 +59,7 @@ gdk_memory_texture_dispose (GObject *object)
 static void
 gdk_memory_texture_download (GdkTexture      *texture,
                              GdkMemoryFormat  format,
+                             GdkColorState   *color_state,
                              guchar          *data,
                              gsize            stride)
 {
@@ -65,9 +67,11 @@ gdk_memory_texture_download (GdkTexture      *texture,
 
   gdk_memory_convert (data, stride,
                       format,
+                      color_state,
                       (guchar *) g_bytes_get_data (self->bytes, NULL),
                       self->stride,
                       texture->format,
+                      texture->color_state,
                       gdk_texture_get_width (texture),
                       gdk_texture_get_height (texture));
 }
@@ -131,7 +135,7 @@ gdk_memory_sanitize (GBytes          *bytes,
  * @bytes: the `GBytes` containing the pixel data
  * @stride: rowstride for the data
  *
- * Creates a new texture for a blob of image data.
+ * Creates a new texture for a blob of sRGB image data.
  *
  * The `GBytes` must contain @stride × @height pixels
  * in the given format.
@@ -144,11 +148,43 @@ gdk_memory_texture_new (int              width,
                         GdkMemoryFormat  format,
                         GBytes          *bytes,
                         gsize            stride)
+{
+  return  gdk_memory_texture_new_with_color_state (width, height, format,
+                                                   gdk_color_state_get_srgb (),
+                                                   bytes, stride);
+}
+
+/**
+ * gdk_memory_texture_new_with_color_state:
+ * @width: the width of the texture
+ * @height: the height of the texture
+ * @format: the format of the data
+ * @color_state: a `GdkColorSpace`
+ * @bytes: the `GBytes` containing the pixel data
+ * @stride: rowstride for the data
+ *
+ * Creates a new texture for a blob of image data with a given color state.
+ *
+ * The `GBytes` must contain @stride x @height pixels
+ * in the given format.
+ *
+ * Returns: A newly-created `GdkTexture`
+ *
+ * Since: 4.16
+ */
+GdkTexture *
+gdk_memory_texture_new_with_color_state (int              width,
+                                         int              height,
+                                         GdkMemoryFormat  format,
+                                         GdkColorState   *color_state,
+                                         GBytes          *bytes,
+                                         gsize            stride)
 {
   GdkMemoryTexture *self;
 
   g_return_val_if_fail (width > 0, NULL);
   g_return_val_if_fail (height > 0, NULL);
+  g_return_val_if_fail (GDK_IS_COLOR_STATE (color_state), NULL);
   g_return_val_if_fail (bytes != NULL, NULL);
   g_return_val_if_fail (stride >= width * gdk_memory_format_bytes_per_pixel (format), NULL);
   /* needs to be this complex to support subtexture of the bottom right part */
@@ -159,6 +195,7 @@ gdk_memory_texture_new (int              width,
   self = g_object_new (GDK_TYPE_MEMORY_TEXTURE,
                        "width", width,
                        "height", height,
+                       "color-state", color_state,
                        NULL);
 
   GDK_TEXTURE (self)->format = format;
@@ -191,19 +228,19 @@ gdk_memory_texture_new_subtexture (GdkMemoryTexture  *source,
   size = source->stride * (height - 1) + width * bpp;
   bytes = g_bytes_new_from_bytes (source->bytes, offset, size);
 
-  result = gdk_memory_texture_new (width,
-                                   height,
-                                   texture->format,
-                                   bytes,
-                                   source->stride);
+  result = gdk_memory_texture_new_with_color_state (width,
+                                                    height,
+                                                    texture->format,
+                                                    texture->color_state,
+                                                    bytes,
+                                                    source->stride);
   g_bytes_unref (bytes);
 
   return result;
 }
 
 GdkMemoryTexture *
-gdk_memory_texture_from_texture (GdkTexture      *texture,
-                                 GdkMemoryFormat  format)
+gdk_memory_texture_from_texture (GdkTexture *texture)
 {
   GdkTexture *result;
   GBytes *bytes;
@@ -213,23 +250,19 @@ gdk_memory_texture_from_texture (GdkTexture      *texture,
   g_return_val_if_fail (GDK_IS_TEXTURE (texture), NULL);
 
   if (GDK_IS_MEMORY_TEXTURE (texture))
-    {
-      GdkMemoryTexture *memtex = GDK_MEMORY_TEXTURE (texture);
+    return g_object_ref (GDK_MEMORY_TEXTURE (texture));
 
-      if (gdk_texture_get_format (texture) == format)
-        return g_object_ref (memtex);
-    }
-
-  stride = texture->width * gdk_memory_format_bytes_per_pixel (format);
+  stride = texture->width * gdk_memory_format_bytes_per_pixel (texture->format);
   data = g_malloc_n (stride, texture->height);
 
-  gdk_texture_do_download (texture, format, data, stride);
+  gdk_texture_do_download (texture, texture->format, texture->color_state, data, stride);
   bytes = g_bytes_new_take (data, stride * texture->height);
-  result = gdk_memory_texture_new (texture->width,
-                                   texture->height,
-                                   format,
-                                   bytes,
-                                   stride);
+  result = gdk_memory_texture_new_with_color_state (texture->width,
+                                                    texture->height,
+                                                    texture->format,
+                                                    texture->color_state,
+                                                    bytes,
+                                                    stride);
   g_bytes_unref (bytes);
 
   return GDK_MEMORY_TEXTURE (result);

gdk/gdkmemorytexture.h

@@ -68,6 +68,14 @@ GdkTexture *            gdk_memory_texture_new              (int
                                                              GBytes            *bytes,
                                                              gsize              stride);
 
+GDK_AVAILABLE_IN_4_16
+GdkTexture *            gdk_memory_texture_new_with_color_state (int              width,
+                                                                 int              height,
+                                                                 GdkMemoryFormat  format,
+                                                                 GdkColorState   *color_state,
+                                                                 GBytes          *bytes,
+                                                                 gsize            stride);
+
 
 G_END_DECLS
 

gdk/gdkmemorytextureprivate.h

@@ -28,8 +28,7 @@ G_BEGIN_DECLS
 #define GDK_MEMORY_GDK_PIXBUF_OPAQUE GDK_MEMORY_R8G8B8
 #define GDK_MEMORY_GDK_PIXBUF_ALPHA GDK_MEMORY_R8G8B8A8
 
-GdkMemoryTexture *      gdk_memory_texture_from_texture     (GdkTexture        *texture,
-                                                             GdkMemoryFormat    format);
+GdkMemoryTexture *      gdk_memory_texture_from_texture     (GdkTexture        *texture);
 GdkTexture *            gdk_memory_texture_new_subtexture   (GdkMemoryTexture  *texture,
                                                              int                x,
                                                              int                y,

gdk/gdknamedcolorstate.c

@@ -0,0 +1,282 @@
+/* gdknamedcolorstate.c
+ *
+ * Copyright 2024 (c) Matthias Clasen
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "config.h"
+
+#include "gdknamedcolorstateprivate.h"
+
+#include <glib/gi18n-lib.h>
+
+
+struct _GdkNamedColorState
+{
+  GdkColorState parent_instance;
+
+  GdkColorStateId id;
+};
+
+struct _GdkNamedColorStateClass
+{
+  GdkColorStateClass parent_class;
+};
+
+G_DEFINE_TYPE (GdkNamedColorState, gdk_named_color_state, GDK_TYPE_COLOR_STATE)
+
+static gboolean
+gdk_named_color_state_equal (GdkColorState *self,
+                             GdkColorState *other)
+{
+  return ((GdkNamedColorState *) self)->id == ((GdkNamedColorState *) other)->id;
+}
+
+static GdkMemoryDepth
+gdk_named_color_state_get_min_depth (GdkColorState *self)
+{
+  switch (((GdkNamedColorState *) self)->id)
+    {
+    case GDK_COLOR_STATE_SRGB_LINEAR:
+    case GDK_COLOR_STATE_OKLAB:
+    case GDK_COLOR_STATE_OKLCH:
+      return GDK_MEMORY_U16;
+    case GDK_COLOR_STATE_SRGB:
+    case GDK_COLOR_STATE_HSL:
+    case GDK_COLOR_STATE_HWB:
+      return GDK_MEMORY_U8;
+    default:
+      g_assert_not_reached ();
+    }
+}
+
+static const char *
+gdk_named_color_state_get_name (GdkColorState *self)
+{
+  const char *names[] = {
+    "srgb", "srgb-linear", "hsl", "hwb", "oklab", "oklch"
+  };
+
+  return names[((GdkNamedColorState *) self)->id];
+}
+
+static void
+gdk_named_color_state_dispose (GObject *object)
+{
+  g_assert_not_reached ();
+
+  G_OBJECT_CLASS (gdk_named_color_state_parent_class)->dispose (object);
+}
+
+static void
+gdk_named_color_state_class_init (GdkNamedColorStateClass *klass)
+{
+  GdkColorStateClass *color_state_class = GDK_COLOR_STATE_CLASS (klass);
+  GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+
+  gobject_class->dispose = gdk_named_color_state_dispose;
+
+  color_state_class->equal = gdk_named_color_state_equal;
+  color_state_class->get_min_depth = gdk_named_color_state_get_min_depth;
+  color_state_class->get_name = gdk_named_color_state_get_name;
+}
+
+static void
+gdk_named_color_state_init (GdkNamedColorState *self)
+{
+}
+
+static GdkColorState *
+gdk_named_color_state_new (GdkColorStateId id)
+{
+  GdkNamedColorState *self;
+
+  self = g_object_new (GDK_TYPE_NAMED_COLOR_STATE, NULL);
+
+  self->id = id;
+
+  return (GdkColorState *) self;
+}
+
+/**
+ * gdk_color_state_get_srgb:
+ *
+ * Returns the object representing the sRGB color state.
+ *
+ * If you don't know anything about color states but need one for
+ * use with some function, this one is most likely the right one.
+ *
+ * Returns: (transfer none): the object for the sRGB color state.
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_color_state_get_srgb (void)
+{
+  static GdkColorState *srgb_color_state;
+
+  if (g_once_init_enter (&srgb_color_state))
+    {
+      GdkColorState *color_state;
+
+      color_state = gdk_named_color_state_new (GDK_COLOR_STATE_SRGB);
+      g_assert (color_state);
+
+      g_once_init_leave (&srgb_color_state, color_state);
+    }
+
+  return srgb_color_state;
+}
+
+/**
+ * gdk_color_state_get_srgb_linear:
+ *
+ * Returns the object representing the linear sRGB color state.
+ *
+ * Returns: (transfer none): the object for the linear sRGB color state.
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_color_state_get_srgb_linear (void)
+{
+  static GdkColorState *srgb_linear_color_state;
+
+  if (g_once_init_enter (&srgb_linear_color_state))
+    {
+      GdkColorState *color_state;
+
+      color_state = gdk_named_color_state_new (GDK_COLOR_STATE_SRGB);
+      g_assert (color_state);
+
+      g_once_init_leave (&srgb_linear_color_state, color_state);
+    }
+
+  return srgb_linear_color_state;
+}
+
+/**
+ * gdk_color_state_get_hsl:
+ *
+ * Returns the object representing the HSL color state.
+ *
+ * Returns: (transfer none): the object for the HSL color state.
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_color_state_get_hsl (void)
+{
+  static GdkColorState *hsl_color_state;
+
+  if (g_once_init_enter (&hsl_color_state))
+    {
+      GdkColorState *color_state;
+
+      color_state = gdk_named_color_state_new (GDK_COLOR_STATE_HSL);
+      g_assert (color_state);
+
+      g_once_init_leave (&hsl_color_state, color_state);
+    }
+
+  return hsl_color_state;
+}
+
+/**
+ * gdk_color_state_get_hwb:
+ *
+ * Returns the object representing the HWB color state.
+ *
+ * Returns: (transfer none): the object for the HWB color state.
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_color_state_get_hwb (void)
+{
+  static GdkColorState *hwb_color_state;
+
+  if (g_once_init_enter (&hwb_color_state))
+    {
+      GdkColorState *color_state;
+
+      color_state = gdk_named_color_state_new (GDK_COLOR_STATE_HWB);
+      g_assert (color_state);
+
+      g_once_init_leave (&hwb_color_state, color_state);
+    }
+
+  return hwb_color_state;
+}
+
+/**
+ * gdk_color_state_get_oklab:
+ *
+ * Returns the object representing the OKLAB color state.
+ *
+ * Returns: (transfer none): the object for the OKLAB color state.
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_color_state_get_oklab (void)
+{
+  static GdkColorState *oklab_color_state;
+
+  if (g_once_init_enter (&oklab_color_state))
+    {
+      GdkColorState *color_state;
+
+      color_state = gdk_named_color_state_new (GDK_COLOR_STATE_OKLAB);
+      g_assert (color_state);
+
+      g_once_init_leave (&oklab_color_state, color_state);
+    }
+
+  return oklab_color_state;
+}
+
+/**
+ * gdk_color_state_get_oklcb:
+ *
+ * Returns the object representing the OKLCH color state.
+ *
+ * Returns: (transfer none): the object for the OKLCH color state.
+ *
+ * Since: 4.16
+ */
+GdkColorState *
+gdk_color_state_get_oklch (void)
+{
+  static GdkColorState *oklch_color_state;
+
+  if (g_once_init_enter (&oklch_color_state))
+    {
+      GdkColorState *color_state;
+
+      color_state = gdk_named_color_state_new (GDK_COLOR_STATE_OKLCH);
+      g_assert (color_state);
+
+      g_once_init_leave (&oklch_color_state, color_state);
+    }
+
+  return oklch_color_state;
+}
+
+GdkColorStateId
+gdk_named_color_state_get_id (GdkColorState *self)
+{
+  return ((GdkNamedColorState *) self)->id;
+}

gdk/gdknamedcolorstateprivate.h

@@ -0,0 +1,40 @@
+/* gdknamedscolorstate.h
+ *
+ * Copyright 2024 (c) Matthias Clasen
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "gdkcolorstateprivate.h"
+
+G_BEGIN_DECLS
+
+#define GDK_TYPE_NAMED_COLOR_STATE (gdk_named_color_state_get_type ())
+
+typedef enum {
+  GDK_COLOR_STATE_SRGB,
+  GDK_COLOR_STATE_SRGB_LINEAR,
+  GDK_COLOR_STATE_HSL,
+  GDK_COLOR_STATE_HWB,
+  GDK_COLOR_STATE_OKLAB,
+  GDK_COLOR_STATE_OKLCH,
+} GdkColorStateId;
+
+GDK_DECLARE_INTERNAL_TYPE (GdkNamedColorState, gdk_named_color_state, GDK, NAMED_COLOR_STATE, GdkColorState)
+
+GdkColorStateId gdk_named_color_state_get_id (GdkColorState *self);
+
+G_END_DECLS

gdk/gdkrgba.c

@@ -98,9 +98,9 @@ gdk_rgba_free (GdkRGBA *rgba)
  * Returns: %TRUE if the @rgba is clear
  */
 gboolean
-gdk_rgba_is_clear (const GdkRGBA *rgba)
+(gdk_rgba_is_clear) (const GdkRGBA *rgba)
 {
-  return rgba->alpha < ((float) 0x00ff / (float) 0xffff);
+  return _gdk_rgba_is_clear (rgba);
 }
 
 /**
@@ -115,9 +115,9 @@ gdk_rgba_is_clear (const GdkRGBA *rgba)
  * Returns: %TRUE if the @rgba is opaque
  */
 gboolean
-gdk_rgba_is_opaque (const GdkRGBA *rgba)
+(gdk_rgba_is_opaque) (const GdkRGBA *rgba)
 {
-  return rgba->alpha > ((float)0xff00 / (float)0xffff);
+  return _gdk_rgba_is_opaque (rgba);
 }
 
 #define SKIP_WHITESPACES(s) while (*(s) == ' ') (s)++;
@@ -368,21 +368,10 @@ gdk_rgba_hash (gconstpointer p)
  * Returns: %TRUE if the two colors compare equal
  */
 gboolean
-gdk_rgba_equal (gconstpointer p1,
-                gconstpointer p2)
+(gdk_rgba_equal) (gconstpointer p1,
+                  gconstpointer p2)
 {
-  const GdkRGBA *rgba1, *rgba2;
-
-  rgba1 = p1;
-  rgba2 = p2;
-
-  if (rgba1->red == rgba2->red &&
-      rgba1->green == rgba2->green &&
-      rgba1->blue == rgba2->blue &&
-      rgba1->alpha == rgba2->alpha)
-    return TRUE;
-
-  return FALSE;
+  return _gdk_rgba_equal (p1, p2);
 }
 
 /**
@@ -407,10 +396,18 @@ gdk_rgba_equal (gconstpointer p1,
  */
 char *
 gdk_rgba_to_string (const GdkRGBA *rgba)
+{
+  return g_string_free (gdk_rgba_print (rgba, g_string_new ("")), FALSE);
+}
+
+GString *
+gdk_rgba_print (const GdkRGBA *rgba,
+                GString       *string)
 {
   if (rgba->alpha > 0.999)
     {
-      return g_strdup_printf ("rgb(%d,%d,%d)",
+      g_string_append_printf (string,
+                              "rgb(%d,%d,%d)",
                               (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
                               (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
                               (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.));
@@ -421,12 +418,15 @@ gdk_rgba_to_string (const GdkRGBA *rgba)
 
       g_ascii_formatd (alpha, G_ASCII_DTOSTR_BUF_SIZE, "%g", CLAMP (rgba->alpha, 0, 1));
 
-      return g_strdup_printf ("rgba(%d,%d,%d,%s)",
+      g_string_append_printf (string,
+                              "rgba(%d,%d,%d,%s)",
                               (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
                               (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
                               (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.),
                               alpha);
     }
+
+  return string;
 }
 
 static gboolean

gdk/gdkrgbaprivate.h

@@ -43,5 +43,37 @@
 gboolean               gdk_rgba_parser_parse                    (GtkCssParser           *parser,
                                                                  GdkRGBA                *rgba);
 
+#define gdk_rgba_is_clear(rgba) _gdk_rgba_is_clear (rgba)
+#define gdk_rgba_is_opaque(rgba) _gdk_rgba_is_opaque (rgba)
+#define gdk_rgba_equal(p1, p2) _gdk_rgba_equal (p1, p2)
+
+static inline gboolean
+_gdk_rgba_is_clear (const GdkRGBA *rgba)
+{
+  return rgba->alpha < ((float) 0x00ff / (float) 0xffff);
+}
+
+static inline gboolean
+_gdk_rgba_is_opaque (const GdkRGBA *rgba)
+{
+  return rgba->alpha > ((float)0xff00 / (float)0xffff);
+}
+
+static inline gboolean
+_gdk_rgba_equal (gconstpointer p1,
+                 gconstpointer p2)
+{
+  const GdkRGBA *rgba1 = p1;
+  const GdkRGBA *rgba2 = p2;
+
+  return rgba1->red == rgba2->red &&
+         rgba1->green == rgba2->green &&
+         rgba1->blue == rgba2->blue &&
+         rgba1->alpha == rgba2->alpha;
+}
+
+GString * gdk_rgba_print (const GdkRGBA *rgba,
+                          GString       *string);
+
 G_END_DECLS
 

gdk/gdksubsurface.c

@@ -48,6 +48,14 @@ gdk_subsurface_class_init (GdkSubsurfaceClass *class)
   object_class->finalize = gdk_subsurface_finalize;
 }
 
+/*< private >
+ * gdk_subsurface_get_parent:
+ * @subsurface: a `GdkSubsurface`
+ *
+ * Returns the parent surface of @subsurface.
+ *
+ * Returns: the parent surface
+ */
 GdkSurface *
 gdk_subsurface_get_parent (GdkSubsurface *subsurface)
 {
@@ -108,16 +116,41 @@ insert_subsurface (GdkSubsurface *subsurface,
     }
 }
 
+/*< private >
+ * gdk_subsurface_attach:
+ * @subsurface: the `GdkSubsurface`
+ * @texture: the texture to attach. This typically has to be a `GdkDmabufTexture`
+ * @source: the source rectangle (i.e. the subset of the texture) to display
+ * @dest: the dest rectangle, in application pixels, relative to the parent surface.
+ *   It must be integral in application and device pixels, or attaching will fail
+ * @transform: the transform to apply to the texture contents before displaying
+ * @background: (nullable): the background rectangle, in application pixels relative
+ *   to the parent surface. This tells GDK to put a black background of this
+ *   size below the subsurface. It must be integral in application and device pixels,
+ *   or attaching will fail
+ * @above: whether the subsurface should be above its sibling
+ * @sibling: (nullable): the sibling subsurface to stack relative to, or `NULL` to
+ *   stack relative to the parent surface
+ *
+ * Attaches content to a subsurface.
+ *
+ * This function takes all the necessary arguments to determine the subsurface
+ * configuration, including its position, size, content, background and stacking.
+ *
+ * Returns: `TRUE` if the attaching succeeded
+ */
 gboolean
 gdk_subsurface_attach (GdkSubsurface         *subsurface,
                        GdkTexture            *texture,
                        const graphene_rect_t *source,
                        const graphene_rect_t *dest,
                        GdkTextureTransform    transform,
+                       const graphene_rect_t *background,
                        gboolean               above,
                        GdkSubsurface         *sibling)
 {
   GdkSurface *parent = subsurface->parent;
+  gboolean result;
 
   g_return_val_if_fail (GDK_IS_SUBSURFACE (subsurface), FALSE);
   g_return_val_if_fail (GDK_IS_TEXTURE (texture), FALSE);
@@ -131,6 +164,15 @@ gdk_subsurface_attach (GdkSubsurface         *subsurface,
   g_return_val_if_fail (sibling == NULL || GDK_IS_SUBSURFACE (sibling), FALSE);
   g_return_val_if_fail (sibling == NULL || sibling->parent == subsurface->parent, FALSE);
 
+  result = GDK_SUBSURFACE_GET_CLASS (subsurface)->attach (subsurface,
+                                                          texture,
+                                                          source,
+                                                          dest,
+                                                          transform,
+                                                          background,
+                                                          above,
+                                                          sibling);
+
   remove_subsurface (subsurface);
 
   if (sibling)
@@ -156,9 +198,17 @@ gdk_subsurface_attach (GdkSubsurface         *subsurface,
         }
     }
 
-  return GDK_SUBSURFACE_GET_CLASS (subsurface)->attach (subsurface, texture, source, dest, transform, above, sibling);
+  return result;
 }
 
+/*< private >
+ * gdk_subsurface_detach:
+ * @subsurface: a `GdkSubsurface`
+ *
+ * Hides the subsurface.
+ *
+ * To show it again, you need to call gdk_subsurface_attach().
+ */
 void
 gdk_subsurface_detach (GdkSubsurface *subsurface)
 {
@@ -169,6 +219,14 @@ gdk_subsurface_detach (GdkSubsurface *subsurface)
   GDK_SUBSURFACE_GET_CLASS (subsurface)->detach (subsurface);
 }
 
+/*< private >
+ * gdk_subsurface_get_texture:
+ * @subsurface: a `GdkSubsurface`
+ *
+ * Gets the texture that is currently displayed by the subsurface.
+ *
+ * Returns: (nullable): the texture that is displayed
+ */
 GdkTexture *
 gdk_subsurface_get_texture (GdkSubsurface *subsurface)
 {
@@ -177,34 +235,91 @@ gdk_subsurface_get_texture (GdkSubsurface *subsurface)
   return GDK_SUBSURFACE_GET_CLASS (subsurface)->get_texture (subsurface);
 }
 
+/*< private >
+ * gdk_subsurface_get_source_rect:
+ * @subsurface: a `GdkSubsurface`
+ * @rect: (out caller-allocates): return location for the rectangle
+ *
+ * Returns the source rect that was specified in the most recent
+ * gdk_subsurface_attach() call for @subsurface.
+ */
 void
-gdk_subsurface_get_source (GdkSubsurface   *subsurface,
-                           graphene_rect_t *source)
+gdk_subsurface_get_source_rect (GdkSubsurface   *subsurface,
+                                graphene_rect_t *rect)
 {
   g_return_if_fail (GDK_IS_SUBSURFACE (subsurface));
-  g_return_if_fail (source != NULL);
+  g_return_if_fail (rect != NULL);
 
-  GDK_SUBSURFACE_GET_CLASS (subsurface)->get_source (subsurface, source);
+  GDK_SUBSURFACE_GET_CLASS (subsurface)->get_source_rect (subsurface, rect);
 }
 
+/*< private >
+ * gdk_subsurface_get_texture_rect:
+ * @subsurface: a `GdkSubsurface`
+ * @rect: (out caller-allocates): return location for the rectangle
+ *
+ * Returns the texture rect that was specified in the most recent
+ * gdk_subsurface_attach() call for @subsurface.
+ */
 void
-gdk_subsurface_get_dest (GdkSubsurface   *subsurface,
-                         graphene_rect_t *dest)
+gdk_subsurface_get_texture_rect (GdkSubsurface   *subsurface,
+                                 graphene_rect_t *rect)
 {
   g_return_if_fail (GDK_IS_SUBSURFACE (subsurface));
-  g_return_if_fail (dest != NULL);
+  g_return_if_fail (rect != NULL);
 
-  GDK_SUBSURFACE_GET_CLASS (subsurface)->get_dest (subsurface, dest);
+  GDK_SUBSURFACE_GET_CLASS (subsurface)->get_texture_rect (subsurface, rect);
 }
 
+/*< private >
+ * gdk_subsurface_is_above_parent:
+ * @subsurface: a `GdkSubsurface`
+ *
+ * Returns whether the subsurface is above the parent surface
+ * or below. Note that a subsurface can be above its parent
+ * surface, and still be covered by sibling subsurfaces.
+ *
+ * Returns: `TRUE` if @subsurface is above its parent
+ */
 gboolean
 gdk_subsurface_is_above_parent (GdkSubsurface *subsurface)
 {
-  g_return_val_if_fail (GDK_IS_SUBSURFACE (subsurface), TRUE);
+  g_return_val_if_fail (GDK_IS_SUBSURFACE (subsurface), FALSE);
 
   return subsurface->above_parent;
 }
 
+/*< private>
+ * gdk_subsurface_get_sibling:
+ * @subsurface: the `GdkSubsurface`
+ * @above: whether to get the subsurface above
+ *
+ * Returns the subsurface above (or below) @subsurface in
+ * the stacking order.
+ *
+ * Returns: the sibling, or `NULL` if there is none.
+ */
+GdkSubsurface *
+gdk_subsurface_get_sibling (GdkSubsurface *subsurface,
+                            gboolean       above)
+{
+  g_return_val_if_fail (GDK_IS_SUBSURFACE (subsurface), NULL);
+
+  if (above)
+    return subsurface->sibling_above;
+  else
+    return subsurface->sibling_below;
+}
+
+/*< private >
+ * gdk_subsurface_get_transform:
+ * @subsurface: a `GdkSubsurface`
+ *
+ * Returns the transform that was specified in the most recent call to
+ * gdk_subsurface_attach() call for @subsurface.
+ *
+ * Returns: the transform
+ */
 GdkTextureTransform
 gdk_subsurface_get_transform (GdkSubsurface *subsurface)
 {
@@ -213,3 +328,45 @@ gdk_subsurface_get_transform (GdkSubsurface *subsurface)
   return GDK_SUBSURFACE_GET_CLASS (subsurface)->get_transform (subsurface);
 }
 
+/*< private >
+ * gdk_subsurface_get_background_rect:
+ * @subsurface: a `GdkSubsurface`
+ * @rect: (out caller-allocates): return location for the rectangle
+ *
+ * Obtains the background rect that was specified in the most recent
+ * gdk_subsurface_attach() call for @subsurface.
+ *
+ * Returns: `TRUE` if @subsurface has a background
+ */
+gboolean
+gdk_subsurface_get_background_rect (GdkSubsurface   *subsurface,
+                                    graphene_rect_t *rect)
+{
+  g_return_val_if_fail (GDK_IS_SUBSURFACE (subsurface), FALSE);
+  g_return_val_if_fail (rect != NULL, FALSE);
+
+  return GDK_SUBSURFACE_GET_CLASS (subsurface)->get_background_rect (subsurface, rect);
+}
+
+/*< private >
+ * gdk_subsurface_get_bounds:
+ * @subsurface: a `GdkSubsurface`
+ * @bounds: (out caller-allocates): return location for the bounds
+ *
+ * Returns the bounds of the subsurface.
+ *
+ * The bounds are the union of the texture and background rects.
+ */
+void
+gdk_subsurface_get_bounds (GdkSubsurface   *subsurface,
+                           graphene_rect_t *bounds)
+{
+  graphene_rect_t background;
+
+  g_return_if_fail (GDK_IS_SUBSURFACE (subsurface));
+  g_return_if_fail (bounds != NULL);
+
+  gdk_subsurface_get_texture_rect (subsurface, bounds);
+  if (gdk_subsurface_get_background_rect (subsurface, &background))
+    graphene_rect_union (bounds, &background, bounds);
+}