graphicsoffload: Add a black-background property

This property allows explicit control over whether to draw
a black background behind offloaded content or not, instead
of relying on the theme background.

gtk/gtkgraphicsoffload.c

@@ -28,6 +28,7 @@
 #include "gtkprivate.h"
 #include "gdk/gdksurfaceprivate.h"
 #include "gdk/gdksubsurfaceprivate.h"
+#include "gdk/gdkrgbaprivate.h"
 #include "gtktypebuiltins.h"
 
 /**
@@ -82,6 +83,7 @@ struct _GtkGraphicsOffload
   GdkSubsurface *subsurface;
 
   GtkGraphicsOffloadEnabled enabled;
+  gboolean black_background;
 };
 
 struct _GtkGraphicsOffloadClass
@@ -94,6 +96,7 @@ enum
   PROP_0,
   PROP_CHILD,
   PROP_ENABLED,
+  PROP_BLACK_BACKGROUND,
   LAST_PROP,
 };
 
@@ -135,6 +138,10 @@ gtk_graphics_offload_set_property (GObject      *object,
       gtk_graphics_offload_set_enabled (self, g_value_get_enum (value));
       break;
 
+    case PROP_BLACK_BACKGROUND:
+      gtk_graphics_offload_set_black_background (self, g_value_get_boolean (value));
+      break;
+
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
     }
@@ -158,6 +165,10 @@ gtk_graphics_offload_get_property (GObject    *object,
       g_value_set_enum (value, gtk_graphics_offload_get_enabled (self));
       break;
 
+    case PROP_BLACK_BACKGROUND:
+      g_value_set_boolean (value, gtk_graphics_offload_get_black_background (self));
+      break;
+
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
     }
@@ -208,6 +219,13 @@ gtk_graphics_offload_snapshot (GtkWidget   *widget,
   if (self->subsurface)
     gtk_snapshot_push_subsurface (snapshot, self->subsurface);
 
+  if (self->black_background)
+    gtk_snapshot_append_color (snapshot,
+                               &GDK_RGBA_BLACK,
+                               &GRAPHENE_RECT_INIT (0, 0,
+                                                    gtk_widget_get_width (widget),
+                                                    gtk_widget_get_height (widget)));
+
   gtk_widget_snapshot_child (widget, self->child, snapshot);
 
   if (self->subsurface)
@@ -251,6 +269,17 @@ gtk_graphics_offload_class_init (GtkGraphicsOffloadClass *class)
                                                 GTK_GRAPHICS_OFFLOAD_ENABLED,
                                                 GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
 
+  /**
+   * GtkGraphicsOffload:black_background: (attributes org.gtk.Property.get=gtk_graphics_offload_get_black_background org.gtk.Property.set=gtk_graphics_offload_set_black_background)
+   *
+   * Whether to draw a black background.
+   *
+   * Since: 4.16
+   */
+  properties[PROP_BLACK_BACKGROUND] = g_param_spec_boolean ("black-background", NULL, NULL,
+                                                            FALSE,
+                                                            GTK_PARAM_READWRITE | G_PARAM_EXPLICIT_NOTIFY | G_PARAM_STATIC_STRINGS);
+
   g_object_class_install_properties (object_class, LAST_PROP, properties);
 
   gtk_widget_class_set_layout_manager_type (widget_class, GTK_TYPE_BIN_LAYOUT);
@@ -367,3 +396,61 @@ gtk_graphics_offload_get_enabled (GtkGraphicsOffload *self)
 
   return self->enabled;
 }
+
+/**
+ * gtk_graphics_offload_set_black_background:
+ * @self: a `GtkGraphicsOffload`
+ * @value: whether to draw a black background behind the content
+ *
+ * Sets whether this GtkGraphicsOffload widget will draw a black
+ * background.
+ *
+ * A main use case for this is **_letterboxing_** where black bars are
+ * visible next to the content if the aspect ratio of the content does
+ * not match the dimensions of the monitor.
+ *
+ * Using this property for letterboxing instead of CSS allows compositors
+ * to show content with maximum efficiency, using direct scanout to avoid
+ * extra copies in the compositor.
+ *
+ * On Wayland, this is implemented using the
+ * [single-pixel buffer](https://wayland.app/protocols/single-pixel-buffer-v1)
+ * protocol.
+ *
+ * Since: 4.16
+ */
+void
+gtk_graphics_offload_set_black_background (GtkGraphicsOffload *self,
+                                           gboolean            value)
+{
+  g_return_if_fail (GTK_IS_GRAPHICS_OFFLOAD (self));
+
+  if (self->black_background == value)
+    return;
+
+  self->black_background = value;
+
+  gtk_widget_queue_draw (GTK_WIDGET (self));
+
+  g_object_notify_by_pspec (G_OBJECT (self), properties[PROP_BLACK_BACKGROUND]);
+}
+
+/**
+ * gtk_graphics_offload_get_black_background:
+ * @self: a `GtkGraphicsOffload`
+ *
+ * Returns whether the widget draws a black background.
+ *
+ * See [method@Gtk.GraphicsOffload.set_black_background].
+ *
+ * Returns: `TRUE` if black background is drawn
+ *
+ * Since: 4.16
+ */
+gboolean
+gtk_graphics_offload_get_black_background (GtkGraphicsOffload *self)
+{
+  g_return_val_if_fail (GTK_IS_GRAPHICS_OFFLOAD (self), FALSE);
+
+  return self->black_background;
+}

gtk/gtkgraphicsoffload.h

@@ -67,4 +67,11 @@ GDK_AVAILABLE_IN_4_14
 GtkGraphicsOffloadEnabled
                  gtk_graphics_offload_get_enabled  (GtkGraphicsOffload        *self);
 
+GDK_AVAILABLE_IN_4_16
+void             gtk_graphics_offload_set_black_background (GtkGraphicsOffload *self,
+                                                            gboolean            value);
+
+GDK_AVAILABLE_IN_4_16
+gboolean         gtk_graphics_offload_get_black_background (GtkGraphicsOffload *self);
+
 G_END_DECLS