[cogl/wip/cogl-winsys-wgl: 3/4] cogl-winsys: Explicitly comment which vfuncs are optional

[Neil Roberts <nroberts src gnome org>]

commit 14d1303259e5deee7004d9f228cbab98a04214d0
Author: Neil Roberts <neil linux intel com>
Date:   Tue May 10 13:51:41 2011 +0100

    cogl-winsys: Explicitly comment which vfuncs are optional
    
    Some of the virtual functions in CoglWinsysVtable only need to be
    implemented for specific backends or when a specific feature is
    advertised. This splits the vtable struct into two commented sections
    marking which are optional and which are required. Wherever an
    optional function is used there is now a g_return_if_fail to ensure
    there is an implementation.

 cogl/cogl-clutter.c               |    3 +++
 cogl/cogl-context.c               |    4 ++++
 cogl/cogl-framebuffer.c           |   27 +++++++++++++++++++++++++--
 cogl/winsys/cogl-winsys-egl.c     |   20 --------------------
 cogl/winsys/cogl-winsys-private.h |   36 ++++++++++++++++++++----------------
 5 files changed, 52 insertions(+), 38 deletions(-)
---
diff --git a/cogl/cogl-clutter.c b/cogl/cogl-clutter.c
index 49821ac..f85f32e 100644
--- a/cogl/cogl-clutter.c
+++ b/cogl/cogl-clutter.c
@@ -74,6 +74,9 @@ cogl_clutter_winsys_xlib_get_visual_info (void)
 
   winsys = _cogl_context_get_winsys (ctx);
 
+  /* This should only be called for xlib contexts */
+  g_return_val_if_fail (winsys->xlib_get_visual_info != NULL, NULL);
+
   return winsys->xlib_get_visual_info ();
 }
 #endif
diff --git a/cogl/cogl-context.c b/cogl/cogl-context.c
index 53a09d6..90f8af4 100644
--- a/cogl/cogl-context.c
+++ b/cogl/cogl-context.c
@@ -495,6 +495,10 @@ EGLDisplay
 cogl_context_egl_get_egl_display (CoglContext *context)
 {
   const CoglWinsysVtable *winsys = _cogl_context_get_winsys (context);
+
+  /* This should only be called for EGL contexts */
+  g_return_val_if_fail (winsys->context_egl_get_egl_display != NULL, NULL);
+
   return winsys->context_egl_get_egl_display (context);
 }
 #endif
diff --git a/cogl/cogl-framebuffer.c b/cogl/cogl-framebuffer.c
index e4656f6..6afcd3f 100644
--- a/cogl/cogl-framebuffer.c
+++ b/cogl/cogl-framebuffer.c
@@ -1615,6 +1615,11 @@ cogl_framebuffer_swap_region (CoglFramebuffer *framebuffer,
     {
       const CoglWinsysVtable *winsys =
         _cogl_framebuffer_get_winsys (framebuffer);
+
+      /* This should only be called if the winsys advertises
+         COGL_WINSYS_FEATURE_SWAP_REGION */
+      g_return_if_fail (winsys->onscreen_swap_region != NULL);
+
       winsys->onscreen_swap_region (COGL_ONSCREEN (framebuffer),
                                     rectangles,
                                     n_rectangles);
@@ -1647,6 +1652,10 @@ cogl_onscreen_x11_get_window_xid (CoglOnscreen *onscreen)
   else
     {
       const CoglWinsysVtable *winsys = _cogl_framebuffer_get_winsys (framebuffer);
+
+      /* This should only be called for x11 onscreens */
+      g_return_val_if_fail (winsys->onscreen_x11_get_window_xid != NULL, 0);
+
       return winsys->onscreen_x11_get_window_xid (onscreen);
     }
 }
@@ -1656,8 +1665,14 @@ cogl_onscreen_x11_get_visual_xid (CoglOnscreen *onscreen)
 {
   CoglFramebuffer *framebuffer = COGL_FRAMEBUFFER (onscreen);
   const CoglWinsysVtable *winsys = _cogl_framebuffer_get_winsys (framebuffer);
-  XVisualInfo *visinfo = winsys->xlib_get_visual_info ();
-  guint32 id = (guint32)visinfo->visualid;
+  XVisualInfo *visinfo;
+  guint32 id;
+
+  /* This should only be called for xlib based onscreens */
+  g_return_val_if_fail (winsys->xlib_get_visual_info != NULL, 0);
+
+  visinfo = winsys->xlib_get_visual_info ();
+  id = (guint32)visinfo->visualid;
 
   XFree (visinfo);
   return id;
@@ -1675,6 +1690,10 @@ cogl_framebuffer_add_swap_buffers_callback (CoglFramebuffer *framebuffer,
   /* Should this just be cogl_onscreen API instead? */
   g_return_val_if_fail (framebuffer->type == COGL_FRAMEBUFFER_TYPE_ONSCREEN, 0);
 
+  /* This should only be called when
+     COGL_WINSYS_FEATURE_SWAP_BUFFERS_EVENT is advertised */
+  g_return_val_if_fail (winsys->onscreen_add_swap_buffers_callback != NULL, 0);
+
   return winsys->onscreen_add_swap_buffers_callback (onscreen,
                                                      callback,
                                                      user_data);
@@ -1687,6 +1706,10 @@ cogl_framebuffer_remove_swap_buffers_callback (CoglFramebuffer *framebuffer,
   CoglOnscreen *onscreen = COGL_ONSCREEN (framebuffer);
   const CoglWinsysVtable *winsys = _cogl_framebuffer_get_winsys (framebuffer);
 
+  /* This should only be called when
+     COGL_WINSYS_FEATURE_SWAP_BUFFERS_EVENT is advertised */
+  g_return_if_fail (winsys->onscreen_remove_swap_buffers_callback != NULL);
+
   winsys->onscreen_remove_swap_buffers_callback (onscreen, id);
 }
 
diff --git a/cogl/winsys/cogl-winsys-egl.c b/cogl/winsys/cogl-winsys-egl.c
index f6c4532..c7d6691 100644
--- a/cogl/winsys/cogl-winsys-egl.c
+++ b/cogl/winsys/cogl-winsys-egl.c
@@ -1412,22 +1412,6 @@ _cogl_winsys_onscreen_x11_get_window_xid (CoglOnscreen *onscreen)
 }
 #endif
 
-static unsigned int
-_cogl_winsys_onscreen_add_swap_buffers_callback (CoglOnscreen *onscreen,
-                                                 CoglSwapBuffersNotify callback,
-                                                 void *user_data)
-{
-  /* Unsupported feature */
-  return 0;
-}
-
-static void
-_cogl_winsys_onscreen_remove_swap_buffers_callback (CoglOnscreen *onscreen,
-                                                    unsigned int id)
-{
-  /* Unsupported feature */
-}
-
 static void
 _cogl_winsys_onscreen_update_swap_throttled (CoglOnscreen *onscreen)
 {
@@ -1499,10 +1483,6 @@ static CoglWinsysVtable _cogl_winsys_vtable =
     .onscreen_x11_get_window_xid =
       _cogl_winsys_onscreen_x11_get_window_xid,
 #endif
-    .onscreen_add_swap_buffers_callback =
-      _cogl_winsys_onscreen_add_swap_buffers_callback,
-    .onscreen_remove_swap_buffers_callback =
-      _cogl_winsys_onscreen_remove_swap_buffers_callback,
   };
 
 /* XXX: we use a function because no doubt someone will complain
diff --git a/cogl/winsys/cogl-winsys-private.h b/cogl/winsys/cogl-winsys-private.h
index 1fd5e57..3942b7c 100644
--- a/cogl/winsys/cogl-winsys-private.h
+++ b/cogl/winsys/cogl-winsys-private.h
@@ -56,6 +56,8 @@ typedef struct _CoglWinsysVtable
 {
   const char *name;
 
+  /* Required functions */
+
   CoglFuncPtr
   (*get_proc_address) (const char *name);
 
@@ -77,16 +79,6 @@ typedef struct _CoglWinsysVtable
   void
   (*context_deinit) (CoglContext *context);
 
-#ifdef COGL_HAS_EGL_SUPPORT
-  EGLDisplay
-  (*context_egl_get_egl_display) (CoglContext *context);
-#endif
-
-#ifdef COGL_HAS_XLIB_SUPPORT
-  XVisualInfo *
-  (*xlib_get_visual_info) (void);
-#endif
-
   gboolean
   (*onscreen_init) (CoglOnscreen *onscreen, GError **error);
 
@@ -100,12 +92,28 @@ typedef struct _CoglWinsysVtable
   (*onscreen_swap_buffers) (CoglOnscreen *onscreen);
 
   void
+  (*onscreen_update_swap_throttled) (CoglOnscreen *onscreen);
+
+  void
+  (*onscreen_set_visibility) (CoglOnscreen *onscreen,
+                              gboolean visibility);
+
+  /* Optional functions */
+
+  void
   (*onscreen_swap_region) (CoglOnscreen *onscreen,
                            int *rectangles,
                            int n_rectangles);
 
-  void
-  (*onscreen_update_swap_throttled) (CoglOnscreen *onscreen);
+#ifdef COGL_HAS_EGL_SUPPORT
+  EGLDisplay
+  (*context_egl_get_egl_display) (CoglContext *context);
+#endif
+
+#ifdef COGL_HAS_XLIB_SUPPORT
+  XVisualInfo *
+  (*xlib_get_visual_info) (void);
+#endif
 
   guint32
   (*onscreen_x11_get_window_xid) (CoglOnscreen *onscreen);
@@ -119,10 +127,6 @@ typedef struct _CoglWinsysVtable
   (*onscreen_remove_swap_buffers_callback) (CoglOnscreen *onscreen,
                                             unsigned int id);
 
-  void
-  (*onscreen_set_visibility) (CoglOnscreen *onscreen,
-                              gboolean visibility);
-
 #ifdef COGL_HAS_XLIB_SUPPORT
   gboolean
   (*texture_pixmap_x11_create) (CoglTexturePixmapX11 *tex_pixmap);