wayland: Add api to set a foreign shell

Since the wayland protocol doesn't currently provide a way to
retrospectively query the interfaces that get notified when a client
first connects then when using a foreign display with Cogl then we also
need api for telling cogl what compositor and shell objects to use. We
already had api for setting a foreign compositor so this patch just adds
api for setting a foreign shell.

This patch also adds documentation for all the wayland specific apis.

Reviewed-by: Neil Roberts <neil@linux.intel.com>

cogl/cogl-renderer-private.h

@@ -56,6 +56,7 @@ struct _CoglRenderer
 #if defined (COGL_HAS_EGL_PLATFORM_WAYLAND_SUPPORT)
   struct wl_display *foreign_wayland_display;
   struct wl_compositor *foreign_wayland_compositor;
+  struct wl_shell *foreign_wayland_shell;
 #endif
   /* List of callback functions that will be given every native event */
   GSList *event_filters;

cogl/cogl-wayland-renderer.h

@@ -37,26 +37,140 @@ G_BEGIN_DECLS
 
 #define cogl_wayland_renderer_set_foreign_display \
   cogl_wayland_renderer_set_foreign_display_EXP
+/**
+ * cogl_wayland_renderer_set_foreign_display:
+ * @renderer: A #CoglRenderer
+ * @display: A Wayland display
+ *
+ * Allows you to explicitly control what Wayland display you want Cogl
+ * to work with instead of leaving Cogl to automatically connect to a
+ * wayland compositor.
+ *
+ * <note>If you use this API you must also explicitly set foreign
+ * Wayland compositor and shell objects using the
+ * cogl_wayland_renderer_set_foreign_compositor() and
+ * cogl_wayland_renderer_set_foreign_shell() respectively. This ie
+ * because Wayland doesn't currently provide a way to retrospectively
+ * query these interfaces so the expectation is that if you have taken
+ * ownership of the display then you will also have been notified of
+ * the compositor and shell interfaces which Cogl needs to use.</note>
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
 void
 cogl_wayland_renderer_set_foreign_display (CoglRenderer *renderer,
                                            struct wl_display *display);
 
 #define cogl_wayland_renderer_get_display \
   cogl_wayland_renderer_get_display_EXP
+/**
+ * cogl_wayland_renderer_get_display:
+ * @renderer: A #CoglRenderer
+ * @display: A Wayland display
+ *
+ * Retrieves the Wayland display that Cogl is using. If a foreign
+ * display has been specified using
+ * cogl_wayland_renderer_set_foreign_display() then that display will
+ * be returned. If no foreign display has been specified then the
+ * display that Cogl creates internally will be returned unless the
+ * renderer has not yet been connected (either implicitly or explicitly by
+ * calling cogl_renderer_connect()) in which case %NULL is returned.
+ *
+ * Returns: The wayland display currently associated with @renderer,
+ *          or %NULL if the renderer hasn't yet been connected and no
+ *          foreign display has been specified.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
 struct wl_display *
 cogl_wayland_renderer_get_display (CoglRenderer *renderer);
 
 #define cogl_wayland_renderer_set_foreign_compositor \
   cogl_wayland_renderer_set_foreign_compositor_EXP
+/**
+ * cogl_wayland_renderer_set_foreign_compositor:
+ * @renderer: A #CoglRenderer
+ * @compositor: A Wayland compositor
+ *
+ * Allows you to explicitly notify Cogl of a Wayland compositor
+ * interface to use. This API should be used in conjunction with
+ * cogl_wayland_renderer_set_foreign_display() because if you are
+ * connecting to a wayland compositor manually that will also mean you
+ * will be notified on connection of the available interfaces that
+ * can't be queried retrosectively with the current Wayland protocol.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
 void
 cogl_wayland_renderer_set_foreign_compositor (CoglRenderer *renderer,
                                               struct wl_compositor *compositor);
 
 #define cogl_wayland_renderer_get_compositor \
   cogl_wayland_renderer_get_compositor_EXP
+/**
+ * cogl_wayland_renderer_get_compositor:
+ * @renderer: A #CoglRenderer
+ *
+ * Retrieves the Wayland compositor interface that Cogl is using. If a
+ * foreign compositor has been specified using
+ * cogl_wayland_renderer_set_foreign_compositor() then that compositor
+ * will be returned. If no foreign compositor has been specified then
+ * the compositor that Cogl is notified of internally will be returned
+ * unless the renderer has not yet been connected (either implicitly
+ * or explicitly by calling cogl_renderer_connect()) in which case
+ * %NULL is returned.
+ *
+ * Since: 1.8
+ * Stability: unstable
+ */
 struct wl_compositor *
 cogl_wayland_renderer_get_compositor (CoglRenderer *renderer);
 
+#define cogl_wayland_renderer_set_foreign_shell \
+  cogl_wayland_renderer_set_foreign_shell_EXP
+/**
+ * cogl_wayland_renderer_set_foreign_shell:
+ * @renderer: A #CoglRenderer
+ * @shell: A Wayland shell
+ *
+ * Allows you to explicitly notify Cogl of a Wayland shell interface
+ * to use.  This API should be used in conjunction with
+ * cogl_wayland_renderer_set_foreign_display() because if you are
+ * connecting to a wayland compositor manually that will also mean you
+ * will be notified on connection of the available interfaces that
+ * can't be queried retrosectively with the current Wayland protocol.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+void
+cogl_wayland_renderer_set_foreign_shell (CoglRenderer *renderer,
+                                         struct wl_shell *shell);
+
+#define cogl_wayland_renderer_get_shell \
+  cogl_wayland_renderer_get_shell_EXP
+/**
+ * cogl_wayland_renderer_get_shell:
+ * @renderer: A #CoglRenderer
+ *
+ * Retrieves the Wayland shell interface that Cogl is using. If a
+ * foreign shell has been specified using
+ * cogl_wayland_renderer_set_foreign_shell() then that shell
+ * will be returned. If no foreign shell has been specified then
+ * the shell that Cogl is notified of internally will be returned
+ * unless the renderer has not yet been connected (either implicitly
+ * or explicitly by calling cogl_renderer_connect()) in which case
+ * %NULL is returned.
+ *
+ * Since: 1.10
+ * Stability: unstable
+ */
+struct wl_shell *
+cogl_wayland_renderer_get_shell (CoglRenderer *renderer);
+
 G_END_DECLS
 
 #endif /* __COGL_WAYLAND_RENDERER_H__ */

cogl/winsys/cogl-winsys-egl.c

@@ -328,10 +328,13 @@ _cogl_winsys_renderer_connect (CoglRenderer *renderer,
     {
       egl_renderer->wayland_display = renderer->foreign_wayland_display;
       /* XXX: For now we have to assume that if a foreign display is
-       * given then so is a foreing compositor because there is no way
+       * given then a foreign compositor and shell must also have been
-       * to retrospectively be notified of the compositor. */
+       * given because wayland doesn't provide a way to
+       * retrospectively be notified of the these objects. */
       g_assert (renderer->foreign_wayland_compositor);
+      g_assert (renderer->foreign_wayland_shell);
       egl_renderer->wayland_compositor = renderer->foreign_wayland_compositor;
+      egl_renderer->wayland_shell = renderer->foreign_wayland_shell;
     }
   else
     {
@@ -1886,6 +1889,34 @@ cogl_wayland_renderer_get_compositor (CoglRenderer *renderer)
     return NULL;
 }
 
+void
+cogl_wayland_renderer_set_foreign_shell (CoglRenderer *renderer,
+                                         struct wl_shell *shell)
+{
+  _COGL_RETURN_IF_FAIL (cogl_is_renderer (renderer));
+
+  /* NB: Renderers are considered immutable once connected */
+  _COGL_RETURN_IF_FAIL (!renderer->connected);
+
+  renderer->foreign_wayland_shell = shell;
+}
+
+struct wl_shell *
+cogl_wayland_renderer_get_shell (CoglRenderer *renderer)
+{
+  _COGL_RETURN_VAL_IF_FAIL (cogl_is_renderer (renderer), NULL);
+
+  if (renderer->foreign_wayland_shell)
+    return renderer->foreign_wayland_shell;
+  else if (renderer->connected)
+    {
+      CoglRendererEGL *egl_renderer = renderer->winsys;
+      return egl_renderer->wayland_shell;
+    }
+  else
+    return NULL;
+}
+
 struct wl_surface *
 cogl_wayland_onscreen_get_surface (CoglOnscreen *onscreen)
 {