display: add _set_onscreen_template() api

Currently it's only possible to set an onscreen template on a
CoglDisplay by passing a template to cogl_display_new(). For
applications that want to deal with fallbacks then they may want to
replace the onscreen template so this adds a
cogl_display_set_onscreen_template() function.

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

(cherry picked from commit f307c9545791dae5472a9568fef6b31b3bf52854)

cogl/cogl-display.c

@@ -95,19 +95,17 @@ cogl_display_new (CoglRenderer *renderer,
   if (!cogl_renderer_connect (display->renderer, &error))
     g_error ("Failed to connect to renderer: %s\n", error->message);
 
-  display->onscreen_template = onscreen_template;
-  if (onscreen_template)
-    cogl_object_ref (onscreen_template);
-  else
-    display->onscreen_template = cogl_onscreen_template_new (NULL);
-
   display->setup = FALSE;
 
 #ifdef COGL_HAS_EGL_PLATFORM_GDL_SUPPORT
   display->gdl_plane = GDL_PLANE_ID_UPP_C;
 #endif
 
-  return _cogl_display_object_new (display);
+  display = _cogl_display_object_new (display);
+
+  cogl_display_set_onscreen_template (display, onscreen_template);
+
+  return display;
 }
 
 CoglRenderer *
@@ -116,6 +114,26 @@ cogl_display_get_renderer (CoglDisplay *display)
   return display->renderer;
 }
 
+void
+cogl_display_set_onscreen_template (CoglDisplay *display,
+                                    CoglOnscreenTemplate *onscreen_template)
+{
+  _COGL_RETURN_IF_FAIL (display->setup == FALSE);
+
+  if (onscreen_template)
+    cogl_object_ref (onscreen_template);
+
+  if (display->onscreen_template)
+    cogl_object_unref (display->onscreen_template);
+
+  display->onscreen_template = onscreen_template;
+
+  /* NB: we want to maintain the invariable that there is always an
+   * onscreen template associated with a CoglDisplay... */
+  if (!onscreen_template)
+    display->onscreen_template = cogl_onscreen_template_new (NULL);
+}
+
 CoglBool
 cogl_display_setup (CoglDisplay *display,
                     CoglError **error)

cogl/cogl-display.h

@@ -85,7 +85,8 @@ typedef struct _CoglDisplay	      CoglDisplay;
  *
  * A common use for explicitly allocating a display object is to
  * define a template for allocating onscreen framebuffers which is
- * what the @onscreen_template argument is for.
+ * what the @onscreen_template argument is for, or alternatively
+ * you can use cogl_display_set_onscreen_template().
  *
  * When a display is first allocated via cogl_display_new() it is in a
  * mutable configuration mode. It's designed this way so we can
@@ -121,6 +122,26 @@ cogl_display_new (CoglRenderer *renderer,
 CoglRenderer *
 cogl_display_get_renderer (CoglDisplay *display);
 
+/**
+ * cogl_display_set_onscreen_template:
+ * @display: a #CoglDisplay
+ * @onscreen_template: A template for creating #CoglOnscreen framebuffers
+ *
+ * Specifies a template for creating #CoglOnscreen framebuffers.
+ *
+ * Depending on the system, the constraints for creating #CoglOnscreen
+ * framebuffers need to be known before setting up a #CoglDisplay because the
+ * final setup of the display may constrain how onscreen framebuffers may be
+ * allocated. If Cogl knows how an application wants to allocate onscreen
+ * framebuffers then it can try to make sure to setup the display accordingly.
+ *
+ * Since: 1.16
+ * Stability: unstable
+ */
+void
+cogl_display_set_onscreen_template (CoglDisplay *display,
+                                    CoglOnscreenTemplate *onscreen_template);
+
 /**
  * cogl_display_setup:
  * @display: a #CoglDisplay