gdk: Add GdkTextureDownloader

It's the new object that allows more control about accessing texture
data.

7 files changed, 384 insertions, 0 deletions

diff --git a/gdk/gdk.h b/gdk/gdk.h
index a91ec39f45..af43c7f175 100644
--- a/gdk/gdk.h
+++ b/gdk/gdk.h
@@ -69,6 +69,7 @@
 #include <gdk/gdksnapshot.h>
 #include <gdk/gdksurface.h>
 #include <gdk/gdktexture.h>
+#include <gdk/gdktexturedownloader.h>
 #include <gdk/gdktoplevel.h>
 #include <gdk/gdktoplevellayout.h>
 #include <gdk/gdktoplevelsize.h>
diff --git a/gdk/gdkmemorytextureprivate.h b/gdk/gdkmemorytextureprivate.h
index 57dafd567b..7e4092b77c 100644
--- a/gdk/gdkmemorytextureprivate.h
+++ b/gdk/gdkmemorytextureprivate.h
@@ -38,6 +38,7 @@ GdkTexture *            gdk_memory_texture_new_subtexture   (GdkMemoryTexture  *
                                                              int                height);
 
 const guchar *          gdk_memory_texture_get_data         (GdkMemoryTexture  *self);
+GBytes *                gdk_memory_texture_get_bytes        (GdkMemoryTexture  *self);
 gsize                   gdk_memory_texture_get_stride       (GdkMemoryTexture  *self);
 
 
diff --git a/gdk/gdktexturedownloader.c b/gdk/gdktexturedownloader.c
new file mode 100644
index 0000000000..f45a6aceb7
--- /dev/null
+++ b/gdk/gdktexturedownloader.c
@@ -0,0 +1,269 @@
+/* GTK - The GIMP Toolkit
+ * Copyright (C) 2023 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/>.
+ */
+
+/**
+ * GdkTextureDownloader:
+ *
+ * The `GdkTextureDownloader` is used to download the contents of a
+ * [class@Gdk.Texture].
+ *
+ * It is intended to be created as a short-term object for a single download,
+ * but can be used for multipe downloads of different textures or with different
+ * settings.
+ *
+ * `GdkTextureDownloader` can be used to convert data between different formats.
+ * Create a `GdkTexture` for the existing format and then download it in a
+ * different format.
+ *
+ * Since: 4.10
+ */
+
+#include "config.h"
+
+#include "gdktexturedownloaderprivate.h"
+
+#include "gdkmemoryformatprivate.h"
+#include "gdkmemorytextureprivate.h"
+#include "gdktextureprivate.h"
+
+G_DEFINE_BOXED_TYPE (GdkTextureDownloader, gdk_texture_downloader,
+                     gdk_texture_downloader_copy,
+                     gdk_texture_downloader_free)
+
+
+void
+gdk_texture_downloader_init (GdkTextureDownloader *self,
+                             GdkTexture           *texture)
+{
+  self->texture = g_object_ref (texture);
+  self->format = GDK_MEMORY_DEFAULT;
+}
+
+void
+gdk_texture_downloader_finish (GdkTextureDownloader *self)
+{
+  g_object_unref (self->texture);
+}
+
+/**
+ * gdk_texture_downloader_new:
+ * @texture: texture to download
+ *
+ * Creates a new texture downloader for @texture.
+ *
+ * Returns: A new texture downloader
+ *
+ * Since: 4.10
+ **/
+GdkTextureDownloader *
+gdk_texture_downloader_new (GdkTexture *texture)
+{
+  GdkTextureDownloader *self;
+
+  g_return_val_if_fail (GDK_IS_TEXTURE (texture), NULL);
+
+  self = g_slice_new (GdkTextureDownloader);
+  gdk_texture_downloader_init (self, texture);
+
+  return self;
+}
+
+/**
+ * gdk_texture_downloader_copy:
+ * @self: the downloader to copy
+ *
+ * Creates a copy of the downloader.
+ *
+ * This function is meant for language bindings.
+ *
+ * Returns: A copy of the downloader
+ *
+ * Since: 4.10
+ **/
+GdkTextureDownloader *
+gdk_texture_downloader_copy (const GdkTextureDownloader *self)
+{
+  GdkTextureDownloader *copy;
+
+  g_return_val_if_fail (self != NULL, NULL);
+
+  copy = gdk_texture_downloader_new (self->texture);
+  gdk_texture_downloader_set_format (copy, self->format);
+
+  return copy;
+}
+
+/**
+ * gdk_texture_downloader_free:
+ * @self: texture downloader to free
+ *
+ * Frees the given downloader and all its associated resources.
+ *
+ * Since: 4.10
+ **/
+void
+gdk_texture_downloader_free (GdkTextureDownloader *self)
+{
+  g_return_if_fail (self != NULL);
+
+  gdk_texture_downloader_finish (self);
+  g_slice_free (GdkTextureDownloader, self);
+}
+
+/**
+ * gdk_texture_downloader_set_texture:
+ * @self: a texture downloader
+ * @texture: the new texture to download
+ *
+ * Changes the texture the downloader will download.
+ *
+ * Since: 4.10
+ **/
+void
+gdk_texture_downloader_set_texture (GdkTextureDownloader *self,
+                                    GdkTexture           *texture)
+{
+  g_return_if_fail (self != NULL);
+  g_return_if_fail (GDK_IS_TEXTURE (texture));
+
+  g_set_object (&self->texture, texture);
+}
+
+/**
+ * gdk_texture_downloader_get_texture:
+ * @self: a texture downloader
+ *
+ * Gets the texture that the downloader will download.
+ *
+ * Returns: (transfer none): The texture to download
+ *
+ * Since: 4.10
+ **/
+GdkTexture *
+gdk_texture_downloader_get_texture (const GdkTextureDownloader *self)
+{
+  g_return_val_if_fail (self != NULL, NULL);
+
+  return self->texture;
+}
+
+/**
+ * gdk_texture_downloader_set_format:
+ * @self: a texture downloader
+ * @format: the format to use
+ *
+ * Sets the format the downloader will download.
+ *
+ * By default, GDK_MEMORY_DEFAULT is set.
+ *
+ * Since: 4.10
+ */
+void
+gdk_texture_downloader_set_format (GdkTextureDownloader *self,
+                                   GdkMemoryFormat       format)
+{
+  g_return_if_fail (self != NULL);
+
+  self->format = format;
+}
+
+/**
+ * gdk_texture_downloader_get_format:
+ * @self: a texture downloader
+ *
+ * Gets the format that the data will be downloaded in.
+ *
+ * Returns: The format of the download
+ *
+ * Since: 4.10
+ **/
+GdkMemoryFormat
+gdk_texture_downloader_get_format (const GdkTextureDownloader *self)
+{
+  g_return_val_if_fail (self != NULL, GDK_MEMORY_DEFAULT);
+
+  return self->format;
+}
+
+/**
+ * gdk_texture_downloader_download_into:
+ * @self: a texture downloader
+ * @data: (array): pointer to enough memory to be filled with the
+ *   downloaded data of the texture
+ * @stride: rowstride in bytes
+ *
+ * Downloads the @texture into local memory.
+ *
+ * Since: 4.10
+ **/
+void
+gdk_texture_downloader_download_into (const GdkTextureDownloader *self,
+                                      guchar                     *data,
+                                      gsize                       stride)
+{
+  g_return_if_fail (self != NULL);
+  g_return_if_fail (data != NULL);
+  g_return_if_fail (stride >= gdk_texture_get_width (self->texture) * gdk_memory_format_bytes_per_pixel (self->format));
+
+  gdk_texture_do_download (self->texture, self->format, data, stride);
+}
+
+/**
+ * gdk_texture_downloader_download_bytes:
+ * @self: the downloader
+ * @out_stride: (out): The stride of the resulting data in bytes.
+ *
+ * Downloads the given texture pixels into a `GBytes`. The rowstride will
+ * be stored in the stride value.
+ *
+ * This function will abort if it tries to download a large texture and
+ * fails to allocate memory. If you think that may happen, you should
+ * handle memory allocation yourself and use
+ * gdk_texture_downloader_download_into() once allocation succeeded.
+ *
+ * Returns: The downloaded pixels.
+ *
+ * Since: 4.10
+ **/
+GBytes *
+gdk_texture_downloader_download_bytes (const GdkTextureDownloader *self,
+                                       gsize                      *out_stride)
+{
+  guchar *data;
+  gsize stride;
+
+  g_return_val_if_fail (self != NULL, NULL);
+  g_return_val_if_fail (out_stride != NULL, NULL);
+
+  if (GDK_IS_MEMORY_TEXTURE (self->texture) &&
+      gdk_texture_get_format (self->texture) == self->format)
+    {
+      GdkMemoryTexture *memtex = GDK_MEMORY_TEXTURE (self->texture);
+
+      *out_stride = gdk_memory_texture_get_stride (memtex);
+      return g_bytes_ref (gdk_memory_texture_get_bytes (memtex));
+    }
+
+  stride = self->texture->width * gdk_memory_format_bytes_per_pixel (self->format);
+  data = g_malloc_n (stride, self->texture->height);
+
+  gdk_texture_do_download (self->texture, self->format, data, stride);
+
+  *out_stride = stride;
+  return g_bytes_new_take (data, stride * self->texture->height);
+}
+
diff --git a/gdk/gdktexturedownloader.h b/gdk/gdktexturedownloader.h
new file mode 100644
index 0000000000..0bdb75b573
--- /dev/null
+++ b/gdk/gdktexturedownloader.h
@@ -0,0 +1,69 @@
+/* GTK - The GIMP Toolkit
+ * Copyright (C) 2023 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/>.
+ */
+
+#ifndef __GTK_TEXTURE_DOWNLOADER_H__
+#define __GTK_TEXTURE_DOWNLOADER_H__
+
+#if !defined (__GDK_H_INSIDE__) && !defined (GTK_COMPILATION)
+#error "Only <gdk/gdk.h> can be included directly."
+#endif
+
+
+#include <gdk/gdkversionmacros.h>
+#include <gdk/gdkenums.h>
+#include <gdk/gdktypes.h>
+
+G_BEGIN_DECLS
+
+#define GDK_TYPE_TEXTURE_DOWNLOADER    (gdk_texture_downloader_get_type ())
+
+GDK_AVAILABLE_IN_4_10
+GType                   gdk_texture_downloader_get_type         (void) G_GNUC_CONST;
+GDK_AVAILABLE_IN_4_10
+GdkTextureDownloader *  gdk_texture_downloader_new              (GdkTexture             *texture);
+
+GDK_AVAILABLE_IN_4_10
+GdkTextureDownloader *  gdk_texture_downloader_copy             (const GdkTextureDownloader     *self);
+GDK_AVAILABLE_IN_4_10
+void                    gdk_texture_downloader_free             (GdkTextureDownloader           *self);
+
+
+GDK_AVAILABLE_IN_4_10
+void                    gdk_texture_downloader_set_texture      (GdkTextureDownloader           *self,
+                                                                 GdkTexture                     *texture);
+GDK_AVAILABLE_IN_4_10
+GdkTexture *            gdk_texture_downloader_get_texture      (const GdkTextureDownloader     *self);
+GDK_AVAILABLE_IN_4_10
+void                    gdk_texture_downloader_set_format       (GdkTextureDownloader           *self,
+                                                                 GdkMemoryFormat                 format);
+GDK_AVAILABLE_IN_4_10
+GdkMemoryFormat         gdk_texture_downloader_get_format       (const GdkTextureDownloader     *self);
+
+
+GDK_AVAILABLE_IN_4_10
+void                    gdk_texture_downloader_download_into    (const GdkTextureDownloader     *self,
+                                                                 guchar                         *data,
+                                                                 gsize                           stride);
+GDK_AVAILABLE_IN_4_10
+GBytes *                gdk_texture_downloader_download_bytes   (const GdkTextureDownloader     *self,
+                                                                 gsize                          *out_stride);
+
+G_DEFINE_AUTOPTR_CLEANUP_FUNC(GdkTextureDownloader, gdk_texture_downloader_free)
+
+G_END_DECLS
+
+#endif /* __GTK_TEXTURE_DOWNLOADER_H__ */
diff --git a/gdk/gdktexturedownloaderprivate.h b/gdk/gdktexturedownloaderprivate.h
new file mode 100644
index 0000000000..ca83889210
--- /dev/null
+++ b/gdk/gdktexturedownloaderprivate.h
@@ -0,0 +1,41 @@
+/* GTK - The GIMP Toolkit
+ *
+ * Copyright (C) 2023 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.1 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/>.
+ */
+
+
+#ifndef __GTK_TEXTURE_DOWNLOADER_PRIVATE_H__
+#define __GTK_TEXTURE_DOWNLOADER_PRIVATE_H__
+
+#include "gdktexturedownloader.h"
+
+G_BEGIN_DECLS
+
+struct _GdkTextureDownloader
+{
+  /*< private >*/
+  GdkTexture *texture;
+  GdkMemoryFormat format;
+};
+
+void                    gdk_texture_downloader_init              (GdkTextureDownloader           *self,
+                                                                  GdkTexture                     *texture);
+void                    gdk_texture_downloader_finish            (GdkTextureDownloader           *self);
+
+
+G_END_DECLS
+
+#endif /* __GTK_TEXTURE_DOWNLOADER_PRIVATE_H__ */
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index 3cf195df09..fc3b16e3c7 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -77,6 +77,7 @@ typedef struct _GdkContentFormats     GdkContentFormats;
 typedef struct _GdkContentProvider    GdkContentProvider;
 typedef struct _GdkCursor             GdkCursor;
 typedef struct _GdkTexture            GdkTexture;
+typedef struct _GdkTextureDownloader  GdkTextureDownloader;
 typedef struct _GdkDevice             GdkDevice;
 typedef struct _GdkDrag               GdkDrag;
 typedef struct _GdkDrop               GdkDrop;
diff --git a/gdk/meson.build b/gdk/meson.build
index c690ef821e..b903747fc6 100644
--- a/gdk/meson.build
+++ b/gdk/meson.build
@@ -43,6 +43,7 @@ gdk_public_sources = files([
   'gdkseatdefault.c',
   'gdksnapshot.c',
   'gdktexture.c',
+  'gdktexturedownloader.c',
   'gdkvulkancontext.c',
   'gdksurface.c',
   'gdkpopuplayout.c',
@@ -95,6 +96,7 @@ gdk_public_headers = files([
   'gdkseat.h',
   'gdksnapshot.h',
   'gdktexture.h',
+  'gdktexturedownloader.h',
   'gdktypes.h',
   'gdkvulkancontext.h',
   'gdksurface.h',