gnome-devel-docs r599 - in trunk/gtk-drawing: . C examples

[davyd svn gnome org]

Author: davyd
Date: Sat Sep 27 08:04:37 2008
New Revision: 599
URL: http://svn.gnome.org/viewvc/gnome-devel-docs?rev=599&view=rev

Log:
2008-09-27  Davyd Madeley  <davyd madeley id au>

        * C/gtkdrawingarea.xml:
        * C/cairo-pango.xml:
        * examples/example.gtkdrawingarea.opengl.c:
        - more text, including part of a GtkDrawingArea/OpenGL section


Added:
   trunk/gtk-drawing/examples/example.gtkdrawingarea.opengl.c
Modified:
   trunk/gtk-drawing/C/cairo-pango.xml
   trunk/gtk-drawing/C/gtkdrawingarea.xml
   trunk/gtk-drawing/ChangeLog

Modified: trunk/gtk-drawing/C/cairo-pango.xml
==============================================================================
--- trunk/gtk-drawing/C/cairo-pango.xml	(original)
+++ trunk/gtk-drawing/C/cairo-pango.xml	Sat Sep 27 08:04:37 2008
@@ -6,8 +6,12 @@
 <chapter id="chapter.cairo-pango">
  <title>Cairo and Pango</title>
 
- <para>
-  A paragraph.
- </para>
+ <sect1 id="sect.cairo">
+  <title>Cairo</title>
+ </sect1>
+
+ <sect1 id="sect.pango">
+  <title>Pango</title>
+ </sect1>
 
 </chapter>

Modified: trunk/gtk-drawing/C/gtkdrawingarea.xml
==============================================================================
--- trunk/gtk-drawing/C/gtkdrawingarea.xml	(original)
+++ trunk/gtk-drawing/C/gtkdrawingarea.xml	Sat Sep 27 08:04:37 2008
@@ -132,6 +132,12 @@
    <title>Drawing with Cairo</title>
 
    <para>
+    Cairo is a 2D, output independant vector graphics API that has many
+    useful features like antialiased graphics. Using Cairo is preferable to
+    using the old GDK drawing calls (or X11 drawing routines).
+   </para>
+
+   <para>
     To draw with Cairo, we need to create a Cairo context
     (<classname>cairo_t</classname>) for the
     <classname>GdkWindow</classname>. Once the Cairo context has been
@@ -152,6 +158,180 @@
 cairo_destroy (cr);]]></programlisting>
    </example>
 
+   <para>
+    Details on drawing with Cairo can be found in
+    <xref linkend="sect.cairo"/>.
+   </para>
+
+  </sect2>
+
+  <sect2 id="sect.gtkdrawingarea.expose.pango">
+   <title>Writing with Pango</title>
+
+   <para>
+    Pango is an API for writing text. Using Pango to render text is
+    preferable to functions such as <function>cairo_show_text</function>, as
+    it supports full internationalisation and other text layout features.
+   </para>
+  </sect2>
+
+  <sect2 id="sect.gtkdrawingarea.expose.gdk">
+   <title>Drawing with GDK</title>
+  </sect2>
+
+ </sect1>
+
+ <sect1 id="sect.gtkdrawingarea.updating">
+  <title>Updating and Animating the Area</title>
+ </sect1>
+
+ <sect1 id="sect.gtkdrawingarea.caching">
+  <title>Caching</title>
+ </sect1>
+
+ <sect1 id="sect.gtkdrawingarea.opengl">
+  <title>Drawing with OpenGL</title>
+
+  <important id="important.gtkdrawingarea.opengl.dep">
+   <title>External Dependancy Required</title>
+   <para>
+    Using OpenGL in a <classname>GtkDrawingArea</classname> requires the
+    additional library <application>GtkGLExt</application>.
+   </para>
+   <para>
+    These examples should be compiled with:
+   </para>
+   <screen>
+gcc -o example `pkg-config --cflags --libs gtk+-2.0 gtkglext-1.0 gtkglext-x11-1.0` example.c</screen>
+  </important>
+
+  <para>
+   The <application>GtkGLExt</application> library can be used to render
+   content drawn by OpenGL into a <classname>GtkDrawingArea</classname>.
+   Using OpenGL is much the same as using Cairo or another drawing library,
+   everything remains driven via the expose handler (see <xref
+   linkend="sect.gtkdrawingarea.expose"/>). Additionally the
+   <function>configure-event</function> signal, which is emitted when a
+   widget is resized, must be connected in order to update OpenGL viewport
+   when required.
+  </para>
+  
+  <para>
+   Actual communication with OpenGL is done using the standard OpenGL API,
+   but must be wrapped in calls to
+   <function>gdk_gl_drawable_gl_begin</function> and
+   <function>gdk_gl_drawable_gl_end</function>. After drawing to the GL
+   buffer, the buffers must be flushed (see ...).
+  </para>
+
+  <sect2 id="sect.gtkdrawingarea.opengl.setup">
+   <title>Setting up the GtkDrawingArea for OpenGL</title>
+
+   <para>
+    To set up a <classname>GtkDrawingArea</classname> for OpenGL, we need to
+    do three things: create a <classname>GdkGLConfig</classname>, enable our
+    <classname>GtkDrawingArea</classname> for OpenGL and connect up the
+    signals <function>configure-event</function> and
+    <function>expose-event</function> (<xref linkend="example.gtkdrawingarea.opengl.setup1"/>).
+   </para>
+
+   <example id="example.gtkdrawingarea.opengl.setup1">
+    <title>Setting up a GtkDrawingArea for OpenGL</title>
+    <programlisting>
+<![CDATA[#include <gtk/gtkgl.h>
+#include <GL/gl.h>
+
+GtkWidget *da = gtk_drawing_area_new ();
+GdkGLConfig *glconfig = gdk_gl_config_new_by_mode (
+                GDK_GL_MODE_RGB |
+                GDK_GL_MODE_DEPTH |
+                GDK_GL_MODE_DOUBLE);
+
+if (!glconfig) g_assert_not_reached ();
+
+if (!gtk_widget_set_gl_capability (da, glconfig, NULL, TRUE,
+                        GDK_GL_RGBA_TYPE))
+{
+        g_assert_not_reached ();
+}
+
+g_signal_connect (da, "configure-event",
+                G_CALLBACK (configure_callback), NULL);
+g_signal_connect (da, "expose-event",
+                G_CALLBACK (expose_callback), NULL);
+
+/* the drawing area must be shown before we can do anything with GL */
+gtk_widget_show (da);]]></programlisting>
+   </example>
+   <example id="example.gtkdrawingarea.opengl.setup2">
+    <title>configure-event and expose-event Callbacks</title>
+    <programlisting>
+<![CDATA[static gboolean
+configure_callback (GtkWidget *da, GdkEventConfigure *event, gpointer user_data)
+{
+        g_print ("Configure\n");
+        GdkGLContext *glcontext = gtk_widget_get_gl_context (da);
+        GdkGLDrawable *gldrawable = gtk_widget_get_gl_drawable (da);
+
+        if (!gdk_gl_drawable_gl_begin (gldrawable, glcontext))
+        {
+                g_assert_not_reached ();
+        }
+
+        /* set the OpenGL Viewport */
+
+        gdk_gl_drawable_gl_end (gldrawable);
+
+        return TRUE;
+}
+
+static gboolean
+expose_callback (GtkWidget *da, GdkEventExpose *event, gpointer user_data)
+{
+        g_print ("Expose\n");
+        GdkGLContext *glcontext = gtk_widget_get_gl_context (da);
+        GdkGLDrawable *gldrawable = gtk_widget_get_gl_drawable (da);
+
+        if (!gdk_gl_drawable_gl_begin (gldrawable, glcontext))
+        {
+                g_assert_not_reached ();
+        }
+
+        /* clear */
+        glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
+
+        /* drawing code goes here */
+
+        /* flush */
+        if (gdk_gl_drawable_is_double_buffered (gldrawable))
+                gdk_gl_drawable_swap_buffers (gldrawable);
+        else
+                glFlush ();
+
+        gdk_gl_drawable_gl_end (gldrawable);
+
+        return TRUE;
+}]]></programlisting>
+   </example>
+
+   <para>
+    After the <classname>GtkDrawingArea</classname> has been shown on the
+    screen (after the ... signal has been received), we can set up our
+    initial GL settings (e.g. a call to
+    <function>glOrtho</function> or setting up lighting). The GL viewport
+    should be updated on <function>configure-event</function>. No actual
+    drawing should be done except in <function>expose-event</function>.
+   </para>
+
+   <warning id="warning.gtkdrawingarea.opengl.wrapcalls">
+    <title>Wrap Calls to OpenGL in begin/end Block</title>
+    <para>
+     All calls to OpenGL subroutines must be wrapped by the subroutines
+     <function>gdk_gl_drawable_gl_begin</function> and
+     <function>gdk_gl_drawable_gl_end</function>. See
+     <xref linkend="example.gtkdrawingarea.opengl.setup2"/> for an example.
+    </para>
+   </warning>
   </sect2>
 
  </sect1>

Added: trunk/gtk-drawing/examples/example.gtkdrawingarea.opengl.c
==============================================================================
--- (empty file)
+++ trunk/gtk-drawing/examples/example.gtkdrawingarea.opengl.c	Sat Sep 27 08:04:37 2008
@@ -0,0 +1,101 @@
+#include <gtk/gtk.h>
+#include <gtk/gtkgl.h>
+
+#include <GL/gl.h>
+
+static gboolean
+configure_callback (GtkWidget *da, GdkEventConfigure *event, gpointer user_data)
+{
+	g_print ("Configure\n");
+	GdkGLContext *glcontext = gtk_widget_get_gl_context (da);
+	GdkGLDrawable *gldrawable = gtk_widget_get_gl_drawable (da);
+
+	if (!gdk_gl_drawable_gl_begin (gldrawable, glcontext))
+	{
+		g_assert_not_reached ();
+	}
+
+	/* set the OpenGL Viewport */
+
+	gdk_gl_drawable_gl_end (gldrawable);
+
+	return TRUE;
+}
+
+static gboolean
+expose_callback (GtkWidget *da, GdkEventExpose *event, gpointer user_data)
+{
+	g_print ("Expose\n");
+	GdkGLContext *glcontext = gtk_widget_get_gl_context (da);
+	GdkGLDrawable *gldrawable = gtk_widget_get_gl_drawable (da);
+
+	if (!gdk_gl_drawable_gl_begin (gldrawable, glcontext))
+	{
+		g_assert_not_reached ();
+	}
+
+	/* clear */
+	glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
+
+	/* drawing code goes here */
+
+	/* flush */
+	if (gdk_gl_drawable_is_double_buffered (gldrawable))
+		gdk_gl_drawable_swap_buffers (gldrawable);
+	else
+		glFlush ();
+
+	gdk_gl_drawable_gl_end (gldrawable);
+
+	return TRUE;
+}
+
+int
+main (int argc, char **argv)
+{
+	gtk_init (&argc, &argv);
+
+	GtkWidget *window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
+	GtkWidget *da = gtk_drawing_area_new ();
+
+	gtk_container_add (GTK_CONTAINER (window), da);
+
+	g_signal_connect_swapped (window, "delete-event",
+			G_CALLBACK (gtk_main_quit), NULL);
+
+	GdkGLConfig *glconfig = gdk_gl_config_new_by_mode (
+			GDK_GL_MODE_RGB |
+			GDK_GL_MODE_DEPTH |
+			GDK_GL_MODE_DOUBLE);
+
+	if (!glconfig) g_assert_not_reached ();
+
+	if (!gtk_widget_set_gl_capability (da, glconfig, NULL, TRUE,
+				GDK_GL_RGBA_TYPE))
+	{
+		g_assert_not_reached ();
+	}
+
+	g_signal_connect (da, "configure-event",
+			G_CALLBACK (configure_callback), NULL);
+	g_signal_connect (da, "expose-event",
+			G_CALLBACK (expose_callback), NULL);
+
+	/* the window must be shown before we can do anything with GL */
+	gtk_widget_show_all (window);
+
+	g_print ("Setup\n");
+	GdkGLContext *glcontext = gtk_widget_get_gl_context (da);
+	GdkGLDrawable *gldrawable = gtk_widget_get_gl_drawable (da);
+
+	if (!gdk_gl_drawable_gl_begin (gldrawable, glcontext))
+	{
+		g_assert_not_reached ();
+	}
+
+	/* setup fixed items for OpenGL */
+
+	gdk_gl_drawable_gl_end (gldrawable);
+
+	gtk_main ();
+}