diff --git a/cogl/Makefile.am b/cogl/Makefile.am
index dffec078a..550493b21 100644
--- a/cogl/Makefile.am
+++ b/cogl/Makefile.am
@@ -499,6 +499,7 @@ cogl_nodist_experimental_h += \
        $(builddir)/cogl-egl-defines.h
 
 cogl_sources_c += \
+       $(srcdir)/cogl-egl-private.h \
        $(srcdir)/winsys/cogl-winsys-egl.c \
        $(srcdir)/winsys/cogl-winsys-egl-feature-functions.h \
        $(srcdir)/winsys/cogl-winsys-egl-private.h
@@ -666,7 +667,7 @@ if UNIT_TESTS
 Cogl_1_0_gir_LIBS += $(top_builddir)/test-fixtures/libtest-fixtures.la
 endif
 Cogl_1_0_gir_FILES = $(cogl_1_public_h) cogl-enum-types.h
-Cogl_1_0_gir_CFLAGS = $(AM_CPPFLAGS) $(COGL_DEP_CFLAGS) -UCOGL_ENABLE_EXPERIMENTAL_API -UCOGL_ENABLE_EXPERIMENTAL_2_0_API -UCOGL_COMPILATION -D__COGL_H_INSIDE__ -D__COGL_XLIB_H_INSIDE__ -DCOGL_GIR_SCANNING
+Cogl_1_0_gir_CFLAGS = $(AM_CPPFLAGS) $(COGL_DEP_CFLAGS) -UCOGL_ENABLE_EXPERIMENTAL_API -UCOGL_ENABLE_EXPERIMENTAL_2_0_API -UCOGL_COMPILATION -D__COGL_H_INSIDE__ -D__COGL_XLIB_H_INSIDE__ -D__COGL_EGL_H_INSIDE__ -DCOGL_GIR_SCANNING
 Cogl_1_0_gir_INCLUDES = GL-1.0 GObject-2.0
 Cogl_1_0_gir_EXPORT_PACKAGES = cogl-1.0
 Cogl_1_0_gir_SCANNERFLAGS = --warn-all --c-include='cogl/cogl.h'
diff --git a/cogl/cogl-egl-private.h b/cogl/cogl-egl-private.h
new file mode 100644
index 000000000..c4b0dfe1b
--- /dev/null
+++ b/cogl/cogl-egl-private.h
@@ -0,0 +1,40 @@
+/*
+ * Cogl
+ *
+ * A Low Level GPU Graphics and Utilities API
+ *
+ * Copyright (C) 2007,2008,2009,2010 Intel Corporation.
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies
+ * of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ *
+ *
+ */
+
+#ifndef __COGL_EGL_PRIVATE_H__
+#define __COGL_EGL_PRIVATE_H__
+
+#include "cogl-egl-defines.h"
+
+#ifndef GL_OES_EGL_image
+#define GLeglImageOES void *
+#endif
+
+#endif /* __COGL_EGL_PRIVATE_H__ */
diff --git a/cogl/cogl-egl.h b/cogl/cogl-egl.h
index 96abb785f..624b06908 100644
--- a/cogl/cogl-egl.h
+++ b/cogl/cogl-egl.h
@@ -31,16 +31,35 @@
 #ifndef __COGL_EGL_H__
 #define __COGL_EGL_H__
 
-#ifdef COGL_HAS_EGL_SUPPORT
+/* NB: this is a top-level header that can be included directly but we
+ * want to be careful not to define __COGL_H_INSIDE__ when this is
+ * included internally while building Cogl itself since
+ * __COGL_H_INSIDE__ is used in headers to guard public vs private api
+ * definitions
+ */
+#ifndef COGL_COMPILATION
 
-#include "cogl-egl-defines.h"
+/* Note: When building Cogl .gir we explicitly define
+ * __COGL_EGL_H_INSIDE__ */
+#ifndef __COGL_EGL_H_INSIDE__
+#define __COGL_EGL_H_INSIDE__
+#endif
+
+/* Note: When building Cogl .gir we explicitly define
+ * __COGL_H_INSIDE__ */
+#ifndef __COGL_H_INSIDE__
+#define __COGL_H_INSIDE__
+#define __COGL_MUST_UNDEF_COGL_H_INSIDE__
+#endif
+
+#endif /* COGL_COMPILATION */
+
+
+#include <cogl/cogl-egl-defines.h>
+#include <cogl/cogl-types.h>
 
 COGL_BEGIN_DECLS
 
-#ifndef GL_OES_EGL_image
-#define GLeglImageOES void *
-#endif
-
 /**
  * cogl_egl_context_get_egl_display:
  * @context: A #CoglContext pointer
@@ -50,6 +69,9 @@ COGL_BEGIN_DECLS
  * handle that was setup internally. The result is undefined if Cogl
  * is not using EGL.
  *
+ * Note: The current window system backend can be checked using
+ * cogl_renderer_get_winsys_id().
+ *
  * Return value: The internally setup EGLDisplay handle.
  * Since: 1.8
  * Stability: unstable
@@ -59,6 +81,18 @@ cogl_egl_context_get_egl_display (CoglContext *context);
 
 COGL_END_DECLS
 
-#endif /* COGL_HAS_EGL_SUPPORT */
-
+/* The gobject introspection scanner seems to parse public headers in
+ * isolation which means we need to be extra careful about how we
+ * define and undefine __COGL_H_INSIDE__ used to detect when internal
+ * headers are incorrectly included by developers. In the gobject
+ * introspection case we have to manually define __COGL_H_INSIDE__ as
+ * a commandline argument for the scanner which means we must be
+ * careful not to undefine it in a header...
+ */
+#ifdef __COGL_MUST_UNDEF_COGL_H_INSIDE__
+#undef __COGL_H_INSIDE__
+#undef __COGL_EGL_H_INSIDE__
+#undef __COGL_MUST_UNDEF_COGL_H_INSIDE__
 #endif
+
+#endif /* __COGL_EGL_H__ */
diff --git a/cogl/winsys/cogl-winsys-private.h b/cogl/winsys/cogl-winsys-private.h
index c14b89969..a08e1b084 100644
--- a/cogl/winsys/cogl-winsys-private.h
+++ b/cogl/winsys/cogl-winsys-private.h
@@ -45,7 +45,7 @@
 #endif
 
 #ifdef COGL_HAS_EGL_SUPPORT
-#include "cogl-egl.h"
+#include "cogl-egl-private.h"
 #endif
 
 #include "cogl-poll.h"