wayland: Add documentation to wayland_shell_init

Especially preventing the confusion that it might only initalize the
wl_shell interface.

https://gitlab.gnome.org/GNOME/mutter/merge_requests/871

src/compositor/meta-shaped-texture-private.h

@@ -63,17 +63,4 @@ gboolean meta_shaped_texture_update_area (MetaShapedTexture     *stex,
                                           int                    height,
                                           cairo_rectangle_int_t *clip);
 
-void meta_shaped_texture_paint_node (MetaShapedTexture *stex,
-                                     ClutterPaintNode  *root_node,
-                                     ClutterActorBox   *box,
-                                     guchar             opacity);
-
-typedef void (*MetaShapedTextureInvalidateFunc) (MetaShapedTexture *stex,
-                                                 gboolean           size_changed,
-                                                 gpointer           user_data);
-
-void meta_shaped_texture_set_invalidate_func (MetaShapedTexture               *stex,
-                                              MetaShapedTextureInvalidateFunc  func,
-                                              gpointer                         user_data);
-
 #endif

src/compositor/meta-shaped-texture.c

@@ -107,9 +107,6 @@ struct _MetaShapedTexture
 
   int buffer_scale;
 
-  MetaShapedTextureInvalidateFunc invalidate_func;
-  gpointer invalidate_user_data;
-
   guint create_mipmaps : 1;
 };
 
@@ -684,24 +681,6 @@ do_paint_content (MetaShapedTexture *stex,
   g_clear_pointer (&blended_tex_region, cairo_region_destroy);
 }
 
-static void
-update_invalidation_counters (MetaShapedTexture *stex)
-{
-  stex->prev_invalidation = stex->last_invalidation;
-  stex->last_invalidation = g_get_monotonic_time ();
-
-  if (stex->prev_invalidation)
-    {
-      gint64 interval = stex->last_invalidation - stex->prev_invalidation;
-      gboolean fast_update = interval < MIN_MIPMAP_AGE_USEC;
-
-      if (!fast_update)
-        stex->fast_updates = 0;
-      else if (stex->fast_updates < MIN_FAST_UPDATES_BEFORE_UNMIPMAP)
-        stex->fast_updates++;
-    }
-}
-
 static CoglTexture *
 select_texture_for_paint (MetaShapedTexture *stex)
 {
@@ -795,39 +774,11 @@ meta_shaped_texture_get_preferred_size (ClutterContent *content,
   return TRUE;
 }
 
-static void
-meta_shaped_texture_invalidate (ClutterContent *content)
-{
-  MetaShapedTexture *stex = META_SHAPED_TEXTURE (content);
-
-  update_invalidation_counters (stex);
-
-  if (!stex->invalidate_func)
-    return;
-
-  stex->invalidate_func (stex, FALSE, stex->invalidate_user_data);
-}
-
-static void
-meta_shaped_texture_invalidate_size (ClutterContent *content)
-{
-  MetaShapedTexture *stex = META_SHAPED_TEXTURE (content);
-
-  update_invalidation_counters (stex);
-
-  if (!stex->invalidate_func)
-    return;
-
-  stex->invalidate_func (stex, TRUE, stex->invalidate_user_data);
-}
-
 static void
 clutter_content_iface_init (ClutterContentInterface *iface)
 {
   iface->paint_content = meta_shaped_texture_paint_content;
   iface->get_preferred_size = meta_shaped_texture_get_preferred_size;
-  iface->invalidate = meta_shaped_texture_invalidate;
-  iface->invalidate_size = meta_shaped_texture_invalidate_size;
 }
 
 void
@@ -1480,26 +1431,3 @@ meta_shaped_texture_get_buffer_scale (MetaShapedTexture *stex)
 
   return stex->buffer_scale;
 }
-
-void
-meta_shaped_texture_paint_node (MetaShapedTexture *stex,
-                                ClutterPaintNode  *root_node,
-                                ClutterActorBox   *box,
-                                guchar             opacity)
-{
-  g_return_if_fail (META_IS_SHAPED_TEXTURE (stex));
-
-  if (!stex->texture)
-    return;
-
-  do_paint_content (stex, root_node, stex->texture, box, opacity);
-}
-
-void
-meta_shaped_texture_set_invalidate_func (MetaShapedTexture               *stex,
-                                         MetaShapedTextureInvalidateFunc  func,
-                                         gpointer                         user_data)
-{
-  stex->invalidate_func = func;
-  stex->invalidate_user_data = user_data;
-}

src/compositor/meta-window-actor-x11.c

@@ -1095,15 +1095,12 @@ meta_window_actor_x11_update_shape (MetaWindowActorX11 *actor_x11)
 {
   MetaSurfaceActor *surface =
     meta_window_actor_get_surface (META_WINDOW_ACTOR (actor_x11));
-  ClutterContent *content =
-    meta_window_actor_get_content (META_WINDOW_ACTOR (actor_x11));
 
   actor_x11->needs_reshape = TRUE;
 
   if (meta_window_actor_is_frozen (META_WINDOW_ACTOR (actor_x11)))
     return;
 
-  clutter_content_invalidate_size (content);
   clutter_actor_queue_redraw (CLUTTER_ACTOR (surface));
 }
 

src/compositor/meta-window-actor.c

@@ -32,7 +32,6 @@
 #include "compositor/meta-surface-actor-x11.h"
 #include "compositor/meta-surface-actor.h"
 #include "compositor/meta-window-actor-private.h"
-#include "compositor/meta-window-content-private.h"
 #include "core/boxes-private.h"
 #include "core/window-private.h"
 #include "meta/window.h"
@@ -56,8 +55,6 @@ typedef struct _MetaWindowActorPrivate
 
   MetaSurfaceActor *surface;
 
-  MetaWindowContent *content;
-
   int geometry_scale;
 
   /*
@@ -97,7 +94,6 @@ static guint signals[LAST_SIGNAL] = { 0 };
 enum
 {
   PROP_META_WINDOW = 1,
-  PROP_CONTENT,
 };
 
 static void meta_window_actor_dispose    (GObject *object);
@@ -211,10 +207,6 @@ meta_window_actor_class_init (MetaWindowActorClass *klass)
   g_object_class_install_property (object_class,
                                    PROP_META_WINDOW,
                                    pspec);
-
-  g_object_class_override_property (object_class,
-                                    PROP_CONTENT,
-                                    "content");
 }
 
 static void
@@ -224,7 +216,6 @@ meta_window_actor_init (MetaWindowActor *self)
     meta_window_actor_get_instance_private (self);
 
   priv->geometry_scale = 1;
-  priv->content = meta_window_content_new (self);
 }
 
 static void
@@ -232,11 +223,7 @@ window_appears_focused_notify (MetaWindow *mw,
                                GParamSpec *arg1,
                                gpointer    data)
 {
-  MetaWindowActor *window_actor = META_WINDOW_ACTOR (data);
-  MetaWindowActorPrivate *priv =
-    meta_window_actor_get_instance_private (window_actor);
-
-  clutter_content_invalidate (CLUTTER_CONTENT (priv->content));
+  clutter_actor_queue_redraw (CLUTTER_ACTOR (data));
 }
 
 gboolean
@@ -328,8 +315,6 @@ meta_window_actor_real_assign_surface_actor (MetaWindowActor  *self,
     meta_surface_actor_set_frozen (priv->surface, TRUE);
   else
     meta_window_actor_sync_thawed_state (self);
-
-  clutter_content_invalidate (CLUTTER_CONTENT (priv->content));
 }
 
 void
@@ -404,8 +389,6 @@ meta_window_actor_dispose (GObject *object)
 
   priv->disposed = TRUE;
 
-  g_clear_object (&priv->content);
-
   meta_compositor_remove_window_actor (compositor, self);
 
   g_clear_object (&priv->window);
@@ -432,9 +415,6 @@ meta_window_actor_set_property (GObject      *object,
 
   switch (prop_id)
     {
-    case PROP_CONTENT:
-      g_warning ("Overriding the content of MetaWindowActor is not allowed.");
-      break;
     case PROP_META_WINDOW:
       priv->window = g_value_dup_object (value);
       g_signal_connect_object (priv->window, "notify::appears-focused",
@@ -458,9 +438,6 @@ meta_window_actor_get_property (GObject      *object,
 
   switch (prop_id)
     {
-    case PROP_CONTENT:
-      g_value_set_object (value, priv->content);
-      break;
     case PROP_META_WINDOW:
       g_value_set_object (value, priv->window);
       break;
@@ -508,25 +485,6 @@ meta_window_actor_get_texture (MetaWindowActor *self)
     return NULL;
 }
 
-/**
- * meta_window_actor_get_content:
- * @window_actor: a #MetaWindowActor
- *
- * Gets the #ClutterContent that represents the visible contents of the
- * window. This includes subsurfaces. It should be used as the content
- * of a #ClutterActor, through clutter_actor_set_content().
- *
- * Return value: (transfer none): a #ClutterContent
- */
-ClutterContent *
-meta_window_actor_get_content (MetaWindowActor *window_actor)
-{
-  MetaWindowActorPrivate *priv =
-    meta_window_actor_get_instance_private (window_actor);
-
-  return CLUTTER_CONTENT (priv->content);
-}
-
 /**
  * meta_window_actor_get_surface:
  * @self: a #MetaWindowActor

src/compositor/meta-window-content-private.h

@@ -1,31 +0,0 @@
-/*
- * Copyright (C) 2018 Endless, Inc.
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License as
- * published by the Free Software Foundation; either version 2 of the
- * License, or (at your option) any later version.
- *
- * This program 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
- * General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
- * 02111-1307, USA.
- *
- * Written by:
- *     Georges Basile Stavracas Neto <gbsneto@gnome.org>
- */
-
-#ifndef META_WINDOW_CONTENT_PRIVATE_H
-#define META_WINDOW_CONTENT_PRIVATE_H
-
-#include "meta/meta-window-content.h"
-#include "meta/meta-window-actor.h"
-
-MetaWindowContent* meta_window_content_new (MetaWindowActor *window_actor);
-
-#endif /* META_WINDOW_CONTENT_PRIVATE_H */

src/compositor/meta-window-content.c

@@ -1,349 +0,0 @@
-/*
- * Copyright (C) 2018 Endless, Inc.
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License as
- * published by the Free Software Foundation; either version 2 of the
- * License, or (at your option) any later version.
- *
- * This program 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
- * General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
- * 02111-1307, USA.
- *
- * Written by:
- *     Georges Basile Stavracas Neto <gbsneto@gnome.org>
- */
-
-#include "compositor/meta-shaped-texture-private.h"
-#include "compositor/meta-surface-actor.h"
-#include "compositor/meta-window-actor-private.h"
-#include "compositor/meta-window-content-private.h"
-
-struct _MetaWindowContent
-{
-  GObject parent;
-
-  MetaWindowActor *window_actor;
-
-  unsigned int attached_actors;
-};
-
-static void clutter_content_iface_init (ClutterContentInterface *iface);
-
-G_DEFINE_TYPE_WITH_CODE (MetaWindowContent, meta_window_content, G_TYPE_OBJECT,
-                         G_IMPLEMENT_INTERFACE (CLUTTER_TYPE_CONTENT, clutter_content_iface_init))
-
-/**
- * SECTION:meta-window-content
- * @title: MetaWindowContent
- * @short_description: Contents of a MetaWindowActor
- *
- * #MetaWindowContent represents the user-visible content of
- * a #MetaWindowActor. It combines the contents of all the
- * #MetaSurfaceActors that the window contains into a final
- * texture.
- *
- * It is intended to be used as follows:
- *
- * |[
- * ClutterActor *
- * create_window_clone (MetaWindowActor *window_actor)
- * {
- *   ClutterContent *window_content;
- *   ClutterActor *clone;
- *
- *   window_content = meta_window_actor_get_content (window_actor);
- *
- *   clone = clutter_actor_new ();
- *   clutter_actor_set_content (clone, window_content);
- *
- *   return clone;
- * }
- * ]|
- *
- * It is also exposed as the #MetaWindowActor.content property
- * that can be binded to other actors. Notice, however, that
- * the value of #MetaWindowActor.content cannot be modified,
- * only read.
- */
-
-enum
-{
-  PROP_0,
-  PROP_WINDOW_ACTOR,
-  N_PROPS
-};
-
-static GParamSpec *properties [N_PROPS];
-
-static void
-texture_invalidate_func (MetaShapedTexture *stex,
-                         gboolean           size_changed,
-                         gpointer           user_data)
-{
-  MetaWindowContent *window_content = (MetaWindowContent*) user_data;
-
-  if (window_content->attached_actors == 0)
-    return;
-
-  if (size_changed)
-    clutter_content_invalidate_size (CLUTTER_CONTENT (user_data));
-  else
-    clutter_content_invalidate (CLUTTER_CONTENT (user_data));
-}
-
-static void
-set_surface_invalidate_func (MetaWindowContent               *window_content,
-                             MetaShapedTextureInvalidateFunc  func)
-{
-  ClutterActor *window_actor = CLUTTER_ACTOR (window_content->window_actor);
-  ClutterActor *child;
-
-  for (child = clutter_actor_get_first_child (window_actor);
-       child != NULL;
-       child = clutter_actor_get_next_sibling (child))
-    {
-      MetaShapedTexture *stex;
-
-      if (!META_IS_SURFACE_ACTOR (child))
-        continue;
-
-      stex = meta_surface_actor_get_texture (META_SURFACE_ACTOR (child));
-
-      if (!stex)
-        continue;
-
-      meta_shaped_texture_set_invalidate_func (stex, func, window_content);
-    }
-}
-
-static void
-ensure_shaped_textures_invalidate_func (MetaWindowContent *window_content)
-{
-  set_surface_invalidate_func (window_content, texture_invalidate_func);
-}
-
-static void
-add_surface_paint_nodes (MetaSurfaceActor *surface_actor,
-                         ClutterActor     *actor,
-                         ClutterPaintNode *root_node,
-                         float             scale_h,
-                         float             scale_v)
-{
-  MetaShapedTexture *stex;
-  ClutterActorBox box;
-  CoglTexture *texture;
-  uint8_t opacity;
-
-  stex = meta_surface_actor_get_texture (surface_actor);
-
-  if (!stex)
-    return;
-
-  texture = meta_shaped_texture_get_texture (stex);
-
-  if (!texture)
-    return;
-
-  opacity = (guint) clutter_actor_get_paint_opacity (CLUTTER_ACTOR (surface_actor)) *
-            (guint) clutter_actor_get_paint_opacity (actor) /
-            255;
-
-  clutter_actor_get_content_box (CLUTTER_ACTOR (surface_actor),
-                                 &box);
-  box.x1 = box.x1 * scale_h;
-  box.x2 = box.x2 * scale_h;
-  box.y1 = box.y1 * scale_v;
-  box.y2 = box.y2 * scale_v;
-
-  meta_shaped_texture_paint_node (stex,
-                                  root_node,
-                                  &box,
-                                  opacity);
-}
-
-static void
-meta_window_content_paint_content (ClutterContent   *content,
-                                   ClutterActor     *actor,
-                                   ClutterPaintNode *node)
-{
-  MetaWindowContent *window_content = META_WINDOW_CONTENT (content);
-  ClutterActor *window_actor = CLUTTER_ACTOR (window_content->window_actor);
-  ClutterActor *child;
-  float dst_width, dst_height;
-  float scale_h, scale_v;
-  float width, height;
-
-  g_assert (!META_IS_WINDOW_ACTOR (actor));
-  g_assert (!META_IS_SURFACE_ACTOR (actor));
-
-  ensure_shaped_textures_invalidate_func (window_content);
-
-  /* Horizontal and vertical scales */
-  clutter_actor_get_size (window_actor, &width, &height);
-  clutter_actor_get_size (actor, &dst_width, &dst_height);
-  scale_h = dst_width / width;
-  scale_v = dst_height / height;
-
-  for (child = clutter_actor_get_first_child (window_actor);
-       child != NULL;
-       child = clutter_actor_get_next_sibling (child))
-    {
-      if (!META_IS_SURFACE_ACTOR (child))
-        continue;
-
-      add_surface_paint_nodes (META_SURFACE_ACTOR (child),
-                               actor, node,
-                               scale_h, scale_v);
-    }
-}
-
-static gboolean
-meta_window_content_get_preferred_size (ClutterContent *content,
-                                        float          *width,
-                                        float          *height)
-{
-  MetaWindowContent *window_content = META_WINDOW_CONTENT (content);
-
-  ensure_shaped_textures_invalidate_func (window_content);
-
-  clutter_actor_get_size (CLUTTER_ACTOR (window_content->window_actor),
-                          width, height);
-  return TRUE;
-}
-
-static void
-meta_window_content_attached (ClutterContent *content,
-                            ClutterActor   *actor)
-{
-  MetaWindowContent *window_content = META_WINDOW_CONTENT (content);
-
-  window_content->attached_actors++;
-
-  ensure_shaped_textures_invalidate_func (window_content);
-}
-
-static void
-meta_window_content_detached (ClutterContent *content,
-                            ClutterActor   *actor)
-{
-  MetaWindowContent *window_content = META_WINDOW_CONTENT (content);
-
-  window_content->attached_actors--;
-}
-
-static void
-clutter_content_iface_init (ClutterContentInterface *iface)
-{
-  iface->paint_content = meta_window_content_paint_content;
-  iface->get_preferred_size = meta_window_content_get_preferred_size;
-  iface->attached = meta_window_content_attached;
-  iface->detached = meta_window_content_detached;
-}
-
-static void
-meta_window_content_get_property (GObject    *object,
-                                  guint       prop_id,
-                                  GValue     *value,
-                                  GParamSpec *pspec)
-{
-  MetaWindowContent *window_content = META_WINDOW_CONTENT (object);
-
-  switch (prop_id)
-    {
-    case PROP_WINDOW_ACTOR:
-      g_value_set_object (value, window_content->window_actor);
-      break;
-
-    default:
-      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
-    }
-}
-
-static void
-meta_window_content_set_property (GObject      *object,
-                                  guint         prop_id,
-                                  const GValue *value,
-                                  GParamSpec   *pspec)
-{
-  MetaWindowContent *window_content = META_WINDOW_CONTENT (object);
-
-  switch (prop_id)
-    {
-    case PROP_WINDOW_ACTOR:
-      g_assert (window_content->window_actor == NULL);
-
-      window_content->window_actor = g_value_get_object (value);
-      g_assert (window_content->window_actor != NULL);
-      break;
-
-    default:
-      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
-    }
-}
-
-static void
-meta_window_content_dispose (GObject *object)
-{
-  MetaWindowContent *window_content = META_WINDOW_CONTENT (object);
-
-  set_surface_invalidate_func (window_content, NULL);
-
-  G_OBJECT_CLASS (meta_window_content_parent_class)->dispose (object);
-}
-
-static void
-meta_window_content_class_init (MetaWindowContentClass *klass)
-{
-  GObjectClass *object_class = G_OBJECT_CLASS (klass);
-
-  object_class->dispose = meta_window_content_dispose;
-  object_class->get_property = meta_window_content_get_property;
-  object_class->set_property = meta_window_content_set_property;
-
-  properties[PROP_WINDOW_ACTOR] =
-    g_param_spec_object ("window-actor",
-                         "Window actor",
-                         "Window actor",
-                         META_TYPE_WINDOW_ACTOR,
-                         G_PARAM_READWRITE |
-                         G_PARAM_CONSTRUCT_ONLY |
-                         G_PARAM_STATIC_STRINGS);
-
-  g_object_class_install_properties (object_class, N_PROPS, properties);
-}
-
-static void
-meta_window_content_init (MetaWindowContent *self)
-{
-}
-
-MetaWindowContent *
-meta_window_content_new (MetaWindowActor *window_actor)
-{
-  return g_object_new (META_TYPE_WINDOW_CONTENT,
-                       "window-actor", window_actor,
-                       NULL);
-}
-
-/**
- * meta_window_content_get_window_actor:
- * @window_content: a #MetaWindowContent
- *
- * Retrieves the window actor that @window_content represents.
- *
- * Returns: (transfer none): a #MetaWindowActor
- */
-MetaWindowActor *
-meta_window_content_get_window_actor (MetaWindowContent *window_content)
-{
-  g_return_val_if_fail (META_IS_WINDOW_CONTENT (window_content), NULL);
-
-  return window_content->window_actor;
-}

src/meson.build

@@ -319,8 +319,6 @@ mutter_sources = [
   'compositor/meta-window-actor-private.h',
   'compositor/meta-window-actor-x11.c',
   'compositor/meta-window-actor-x11.h',
-  'compositor/meta-window-content.c',
-  'compositor/meta-window-content-private.h',
   'compositor/meta-window-group.c',
   'compositor/meta-window-group-private.h',
   'compositor/meta-window-shape.c',

src/meta/meson.build

@@ -32,7 +32,6 @@ mutter_public_headers = [
   'meta-stage.h',
   'meta-startup-notification.h',
   'meta-window-actor.h',
-  'meta-window-content.h',
   'meta-window-group.h',
   'meta-window-shape.h',
   'meta-workspace-manager.h',

src/meta/meta-window-actor.h

@@ -51,9 +51,6 @@ META_EXPORT
 cairo_surface_t * meta_window_actor_get_image (MetaWindowActor       *self,
                                                cairo_rectangle_int_t *clip);
 
-META_EXPORT
-ClutterContent *meta_window_actor_get_content (MetaWindowActor *self);
-
 typedef enum
 {
   META_SHADOW_MODE_AUTO,

src/meta/meta-window-content.h

@@ -1,39 +0,0 @@
-/*
- * Copyright (C) 2018 Endless, Inc.
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License as
- * published by the Free Software Foundation; either version 2 of the
- * License, or (at your option) any later version.
- *
- * This program 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
- * General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
- * 02111-1307, USA.
- *
- * Written by:
- *     Georges Basile Stavracas Neto <gbsneto@gnome.org>
- */
-
-#ifndef META_WINDOW_CONTENT_H
-#define META_WINDOW_CONTENT_H
-
-#include "meta/meta-window-actor.h"
-
-#define META_TYPE_WINDOW_CONTENT (meta_window_content_get_type())
-
-META_EXPORT
-G_DECLARE_FINAL_TYPE (MetaWindowContent,
-                      meta_window_content,
-                      META, WINDOW_CONTENT,
-                      GObject)
-
-META_EXPORT
-MetaWindowActor * meta_window_content_get_window_actor (MetaWindowContent *window_content);
-
-#endif /* META_WINDOW_CONTENT_H */

src/wayland/meta-wayland-buffer.c

@@ -22,6 +22,30 @@
  *     Jasper St. Pierre <jstpierre@mecheye.net>
  */
 
+/**
+ * SECTION:meta-wayland-buffer
+ * @title: MetaWaylandBuffer
+ * @short_description: A wrapper for wayland buffers
+ *
+ * #MetaWaylandBuffer is a general wrapper around wl_buffer, the basic way of
+ * passing rendered data from Wayland clients to the compositor. Note there are
+ * multiple ways of passing a buffer to the compositor, as specified by
+ * #MetaWaylandBufferType.
+ */
+
+/**
+ * MetaWaylandBufferType:
+ * @META_WAYLAND_BUFFER_TYPE_UNKNOWN: Unknown type.
+ * @META_WAYLAND_BUFFER_TYPE_SHM: wl_buffer backed by shared memory
+ * @META_WAYLAND_BUFFER_TYPE_EGL_IMAGE: wl_buffer backed by an EGLImage
+ * @META_WAYLAND_BUFFER_TYPE_EGL_STREAM: wl_buffer backed by an EGLStream (NVIDIA-specific)
+ * @META_WAYLAND_BUFFER_TYPE_DMA_BUF: wl_buffer backed by a dma_buf
+ *
+ * Specifies the backing memory for a #MetaWaylandBuffer. Depending on the type
+ * of buffer, this will lead to different handling for the compositor.  For
+ * example, a shared-memory buffer will still need to be uploaded to the GPU.
+ */
+
 #include "config.h"
 
 #include "wayland/meta-wayland-buffer.h"
@@ -449,6 +473,15 @@ meta_wayland_buffer_attach (MetaWaylandBuffer  *buffer,
   return FALSE;
 }
 
+/**
+ * meta_wayland_buffer_create_snippet:
+ * @buffer: A #MetaWaylandBuffer object
+ *
+ * If needed, this method creates a #CoglSnippet to make sure the buffer can be
+ * dealt with appropriately in a #CoglPipeline that renders it.
+ *
+ * Returns: (transfer full) (nullable): A new #CoglSnippet, or %NULL.
+ */
 CoglSnippet *
 meta_wayland_buffer_create_snippet (MetaWaylandBuffer *buffer)
 {
@@ -582,6 +615,11 @@ meta_wayland_buffer_class_init (MetaWaylandBufferClass *klass)
 
   object_class->finalize = meta_wayland_buffer_finalize;
 
+  /**
+   * MetaWaylandBuffer::resource-destroyed:
+   *
+   * Called when the underlying wl_resource was destroyed.
+   */
   signals[RESOURCE_DESTROYED] = g_signal_new ("resource-destroyed",
                                               G_TYPE_FROM_CLASS (object_class),
                                               G_SIGNAL_RUN_LAST,

src/wayland/meta-wayland-dma-buf.c

@@ -25,6 +25,16 @@
  *     Daniel Stone <daniels@collabora.com>
  */
 
+/**
+ * SECTION:meta-wayland-dma-buf
+ * @title: MetaWaylandDmaBuf
+ * @short_description: Handles passing dma_bufs in Wayland
+ *
+ * The MetaWaylandDmaBuf namespace contains several objects and functions to
+ * handle dma_buf buffers that are passed through from clients in Wayland (e.g.
+ * using the linux_dmabuf_unstable_v1 protocol).
+ */
+
 #include "config.h"
 
 #include "wayland/meta-wayland-dma-buf.h"
@@ -260,6 +270,17 @@ static const struct wl_buffer_interface dma_buf_buffer_impl =
   buffer_destroy,
 };
 
+/**
+ * meta_wayland_dma_buf_from_buffer:
+ * @buffer: A #MetaWaylandBuffer object
+ *
+ * Fetches the associated #MetaWaylandDmaBufBuffer from the wayland buffer.
+ * This does not *create* a new object, as this happens in the create_params
+ * request of linux_dmabuf_unstable_v1.
+ *
+ * Returns: (transfer none): The corresponding #MetaWaylandDmaBufBuffer (or
+ * %NULL if it wasn't a dma_buf-based wayland buffer)
+ */
 MetaWaylandDmaBufBuffer *
 meta_wayland_dma_buf_from_buffer (MetaWaylandBuffer *buffer)
 {
@@ -513,6 +534,18 @@ dma_buf_bind (struct wl_client *client,
   send_modifiers (resource, DRM_FORMAT_RGB565);
 }
 
+/**
+ * meta_wayland_dma_buf_init:
+ * @compositor: The #MetaWaylandCompositor
+ *
+ * Creates the global Wayland object that exposes the linux_dmabuf_unstable_v1
+ * protocol. When a client binds to the resource, Mutter will make sure to
+ * also send the supported DRM format modifiers.
+ *
+ * Returns: Whether the initialization was succesfull. If this is %FALSE,
+ * clients won't be able to use the linux_dmabuf_unstable_v1 protocol to pass
+ * buffers.
+ */
 gboolean
 meta_wayland_dma_buf_init (MetaWaylandCompositor *compositor)
 {

src/wayland/meta-wayland-surface.c

@@ -726,7 +726,6 @@ meta_wayland_surface_apply_pending_state (MetaWaylandSurface      *surface,
               meta_shaped_texture_set_texture (stex, texture);
               meta_shaped_texture_set_snippet (stex, snippet);
               meta_shaped_texture_set_is_y_inverted (stex, is_y_inverted);
-              clutter_content_invalidate (CLUTTER_CONTENT (stex));
               g_clear_pointer (&snippet, cogl_object_unref);
             }
         }
@@ -1479,6 +1478,13 @@ meta_wayland_surface_begin_grab_op (MetaWaylandSurface *surface,
                                      x, y);
 }
 
+/**
+ * meta_wayland_shell_init:
+ * @compositor: The #MetaWaylandCompositor object
+ *
+ * Initializes the Wayland interfaces providing features that deal with
+ * desktop-specific conundrums, like XDG shell, wl_shell (deprecated), etc.
+ */
 void
 meta_wayland_shell_init (MetaWaylandCompositor *compositor)
 {