Bug 1164 - Implements the proposed Mesh API

* clutter/cogl/cogl-mesh.h
	* clutter/cogl/cogl-types.h
	* clutter/cogl/cogl.h.in
	* clutter/cogl/common/Makefile.am
	* clutter/cogl/common/cogl-mesh-private.h
	* clutter/cogl/common/cogl-mesh.c
	* clutter/cogl/gl/cogl-context.c
	* clutter/cogl/gl/cogl-context.h
	* clutter/cogl/gl/cogl-defines.h.in
	* clutter/cogl/gl/cogl.c
	* clutter/cogl/gles/cogl-context.c
	* clutter/cogl/gles/cogl-context.h
	* doc/reference/cogl/cogl-docs.sgml
	* doc/reference/cogl/cogl-sections.txt:
	The Mesh API provides a means for submitting an extensible number of
	per vertex attributes to OpenGL in a way that doesn't require format
	conversions and so that the data can be mapped into the GPU (in vertex
	buffer objects) for - hopefully - fast re-use.

	There are a number of things we can potentially use this API for, but
	right now this just provides a foundation to build on. Please read
	the extensive list of TODO items in cogl-mesh.c for examples.

	Please refer to the cogl-mesh section in the reference manual for
	documentation of the API.

	* tests/conform/Makefile.am
	* tests/conform/test-conform-main.c
	* tests/conform/test-mesh-contiguous.c
	* tests/conform/test-mesh-interleved.c
	* tests/conform/test-mesh-mutability.c:
	Privides basic coverage testing for the mesh API.

tests/conform/Makefile.am

@@ -10,6 +10,9 @@ test_conformance_SOURCES = \
 	test-timeline-rewind.c \
 	test-timeline-smoothness.c \
 	test-timeline.c \
+	test-mesh-contiguous.c \
+	test-mesh-interleved.c \
+	test-mesh-mutability.c \
 	test-pick.c \
 	test-label-cache.c \
 	test-clutter-entry.c \

tests/conform/test-conform-main.c

@@ -51,7 +51,7 @@ main (int argc, char **argv)
       TEST_CONFORM_SIMPLE ("/timeline", test_timeline_rewind);
       TEST_CONFORM_SIMPLE ("/timeline", test_timeline_smoothness);
     }
-
+  
   TEST_CONFORM_SIMPLE ("/picking", test_pick);
 
   TEST_CONFORM_SIMPLE ("/label", test_label_cache);
@@ -75,12 +75,16 @@ main (int argc, char **argv)
   TEST_CONFORM_SIMPLE ("/rectangle", test_rect_set_color);
 
   TEST_CONFORM_SIMPLE ("/fixed", test_fixed_constants);
-
+  
   TEST_CONFORM_SIMPLE ("/invariants", test_initial_state);
   TEST_CONFORM_SIMPLE ("/invatiants", test_realized);
   TEST_CONFORM_SIMPLE ("/invariants", test_mapped);
   TEST_CONFORM_SIMPLE ("/invariants", test_show_on_set_parent);
 
+  TEST_CONFORM_SIMPLE ("/mesh", test_mesh_contiguous);
+  TEST_CONFORM_SIMPLE ("/mesh", test_mesh_interleved);
+  TEST_CONFORM_SIMPLE ("/mesh", test_mesh_mutability);
+
   g_test_run ();
   return EXIT_SUCCESS;
 }

tests/conform/test-mesh-contiguous.c

@@ -0,0 +1,183 @@
+
+#include <clutter/clutter.h>
+#include <cogl/cogl.h>
+
+#include "test-conform-common.h"
+
+/* This test verifies that the simplest usage of the mesh API, where we add
+ * contiguous (x,y) GLfloat vertices, and RGBA GLubyte color attributes to a
+ * mesh object, submit, and draw.
+ *
+ * It also tries to verify that the enable/disable attribute APIs are working
+ * too.
+ *
+ * If you want visual feedback of what this test paints for debugging purposes,
+ * then remove the call to clutter_main_quit() in validate_result.
+ */
+
+typedef struct _TestState
+{
+  CoglHandle mesh;
+  ClutterGeometry stage_geom;
+  guint frame;
+} TestState;
+
+static void
+validate_result (TestState *state)
+{
+  GLubyte pixel[4];
+  GLint y_off = state->stage_geom.height - 90;
+  /* NB: glReadPixels is done in GL screen space so y = 0 is at the bottom */
+  g_print ("y_off = %d\n", y_off);
+  /* NB: We ignore the alpha, since we don't know if our render target is
+   * RGB or RGBA */
+
+#define RED 0
+#define GREEN 1
+#define BLUE 2
+
+  /* Should see a blue pixel */
+  glReadPixels (10, y_off, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, &pixel);
+  g_print ("pixel 0 = %x, %x, %x\n", pixel[RED], pixel[GREEN], pixel[BLUE]);
+  g_assert (pixel[RED] == 0 && pixel[GREEN] == 0 && pixel[BLUE] != 0);
+  
+  /* Should see a red pixel */
+  glReadPixels (110, y_off, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, &pixel);
+  g_print ("pixel 1 = %x, %x, %x\n", pixel[RED], pixel[GREEN], pixel[BLUE]);
+  g_assert (pixel[RED] != 0 && pixel[GREEN] == 0 && pixel[BLUE] == 0);
+
+  /* Should see a blue pixel */
+  glReadPixels (210, y_off, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, &pixel);
+  g_print ("pixel 2 = %x, %x, %x\n", pixel[RED], pixel[GREEN], pixel[BLUE]);
+  g_assert (pixel[RED] == 0 && pixel[GREEN] == 0 && pixel[BLUE] != 0);
+  
+#undef RED
+#undef GREEN
+#undef BLUE
+  
+  /* Comment this out if you want visual feedback of what this test
+   * paints.
+   */
+  clutter_main_quit ();
+}
+
+static void
+on_paint (ClutterActor *actor, TestState *state)
+{
+  /* Draw a faded blue triangle */
+  cogl_mesh_enable_attribute (state->mesh, "gl_Color::blue");
+  glColor4ub (0xff, 0x00, 0x00, 0xff);
+  cogl_mesh_draw_arrays (state->mesh,
+			 GL_TRIANGLE_STRIP, /* mode */
+			 0, /* first */
+			 3); /* count */
+  
+  /* Draw a red triangle */
+  /* Here we are testing that the disable attribute works; if it doesn't
+   * the triangle will remain faded blue */
+  cogl_translate (100, 0, 0);
+  cogl_mesh_disable_attribute (state->mesh, "gl_Color::blue");
+  glColor4ub (0xff, 0x00, 0x00, 0xff);
+  cogl_mesh_draw_arrays (state->mesh,
+			 GL_TRIANGLE_STRIP, /* mode */
+			 0, /* first */
+			 3); /* count */
+
+  /* Draw a faded blue triangle */
+  /* Here we are testing that the re-enable works; if it doesn't
+   * the triangle will remain red */
+  cogl_translate (100, 0, 0);
+  cogl_mesh_enable_attribute (state->mesh, "gl_Color::blue");
+  glColor4ub (0xff, 0x00, 0x00, 0xff);
+  cogl_mesh_draw_arrays (state->mesh,
+			 GL_TRIANGLE_STRIP, /* mode */
+			 0, /* first */
+			 3); /* count */
+  
+  /* XXX: Experiments have shown that for some buggy drivers, when using
+   * glReadPixels there is some kind of race, so we delay our test for a
+   * few frames and a few seconds:
+   */
+  if (state->frame >= 2)
+    validate_result (state);
+  else
+    sleep (1);
+  
+  state->frame++;
+}
+
+static gboolean
+queue_redraw (gpointer stage)
+{
+  clutter_actor_queue_redraw (CLUTTER_ACTOR (stage));
+}
+
+void
+test_mesh_contiguous (TestConformSimpleFixture *fixture,
+		      gconstpointer data)
+{
+  TestState state;
+  ClutterActor *stage;
+  ClutterColor stage_clr = {0x0, 0x0, 0x0, 0xff};
+  ClutterActor *group;
+
+  state.frame = 0;
+
+  stage = clutter_stage_get_default ();
+
+  clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_clr);
+  clutter_actor_get_geometry (stage, &state.stage_geom);
+
+  group = clutter_group_new ();
+  clutter_actor_set_size (group,
+			  state.stage_geom.width,
+			  state.stage_geom.height);
+  clutter_container_add_actor (CLUTTER_CONTAINER (stage), group);
+
+  /* We force continuous redrawing of the stage, since we need to skip
+   * the first few frames, and we wont be doing anything else that
+   * will trigger redrawing. */
+  g_idle_add (queue_redraw, stage);
+
+  g_signal_connect (group, "paint", G_CALLBACK (on_paint), &state);
+  
+  {
+    GLfloat triangle_verts[3][2] =
+      {
+	{0.0,	0.0},
+	{100.0, 100.0},
+	{0.0,	100.0}
+      };
+    GLbyte triangle_colors[3][4] =
+      {
+	{0x00, 0x00, 0xff, 0xff}, /* blue */
+	{0x00, 0x00, 0xff, 0x00}, /* transparent blue */
+	{0x00, 0x00, 0xff, 0x00}  /* transparent blue */
+      };
+    state.mesh = cogl_mesh_new (3 /* n vertices */);
+    cogl_mesh_add_attribute (state.mesh,
+			     "gl_Vertex",
+			     2, /* n components */
+			     GL_FLOAT,
+			     FALSE, /* normalized */
+			     0, /* stride */
+			     triangle_verts);
+    cogl_mesh_add_attribute (state.mesh,
+			     "gl_Color::blue",
+			     4, /* n components */
+			     GL_UNSIGNED_BYTE,
+			     FALSE, /* normalized */
+			     0, /* stride */
+			     triangle_colors);
+    cogl_mesh_submit (state.mesh);
+  }
+
+  clutter_actor_show_all (stage);
+
+  clutter_main ();
+
+  cogl_mesh_unref (state.mesh);
+
+  g_print ("OK\n");
+}
+

tests/conform/test-mesh-interleved.c

@@ -0,0 +1,165 @@
+
+#include <clutter/clutter.h>
+#include <cogl/cogl.h>
+
+#include "test-conform-common.h"
+
+/* This test verifies that interleved attributes work with the mesh API.
+ * We add (x,y) GLfloat vertices, interleved with RGBA GLubyte color
+ * attributes to a mesh object, submit and draw.
+ *
+ * If you want visual feedback of what this test paints for debugging purposes,
+ * then remove the call to clutter_main_quit() in validate_result.
+ */
+
+typedef struct _TestState
+{
+  CoglHandle mesh;
+  ClutterGeometry stage_geom;
+  guint frame;
+} TestState;
+
+typedef struct _InterlevedVertex
+{
+  GLfloat x;
+  GLfloat y;
+
+  GLubyte r;
+  GLubyte g;
+  GLubyte b;
+  GLubyte a;
+} InterlevedVertex;
+
+
+static void
+validate_result (TestState *state)
+{
+  GLubyte pixel[4];
+  GLint y_off = state->stage_geom.height - 90;
+  /* NB: glReadPixels is done in GL screen space so y = 0 is at the bottom */
+
+  /* NB: We ignore the alpha, since we don't know if our render target is
+   * RGB or RGBA */
+
+#define RED 0
+#define GREEN 1
+#define BLUE 2
+
+  /* Should see a blue pixel */
+  glReadPixels (10, y_off, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, &pixel);
+  g_print ("pixel 0 = %x, %x, %x\n", pixel[RED], pixel[GREEN], pixel[BLUE]);
+  g_assert (pixel[RED] == 0 && pixel[GREEN] == 0 && pixel[BLUE] != 0);
+   
+#undef RED
+#undef GREEN
+#undef BLUE
+  
+  /* Comment this out if you want visual feedback of what this test
+   * paints.
+   */
+  clutter_main_quit ();
+}
+
+static void
+on_paint (ClutterActor *actor, TestState *state)
+{
+  /* Draw a faded blue triangle */
+  cogl_mesh_draw_arrays (state->mesh,
+			 GL_TRIANGLE_STRIP, /* mode */
+			 0, /* first */
+			 3); /* count */
+
+  /* XXX: Experiments have shown that for some buggy drivers, when using
+   * glReadPixels there is some kind of race, so we delay our test for a
+   * few frames and a few seconds:
+   */
+  if (state->frame >= 2)
+    validate_result (state);
+  else
+    sleep (1);
+  
+  state->frame++;
+}
+
+static gboolean
+queue_redraw (gpointer stage)
+{
+  clutter_actor_queue_redraw (CLUTTER_ACTOR (stage));
+}
+
+void
+test_mesh_interleved (TestConformSimpleFixture *fixture,
+		      gconstpointer data)
+{
+  TestState state;
+  ClutterActor *stage;
+  ClutterColor stage_clr = {0x0, 0x0, 0x0, 0xff};
+  ClutterActor *group;
+
+  state.frame = 0;
+
+  stage = clutter_stage_get_default ();
+
+  clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_clr);
+  clutter_actor_get_geometry (stage, &state.stage_geom);
+
+  group = clutter_group_new ();
+  clutter_actor_set_size (group,
+			  state.stage_geom.width,
+			  state.stage_geom.height);
+  clutter_container_add_actor (CLUTTER_CONTAINER (stage), group);
+
+  /* We force continuous redrawing of the stage, since we need to skip
+   * the first few frames, and we wont be doing anything else that
+   * will trigger redrawing. */
+  g_idle_add (queue_redraw, stage);
+
+  g_signal_connect (group, "paint", G_CALLBACK (on_paint), &state);
+  
+  {
+    InterlevedVertex verts[3] =
+      {
+	{ /* .x = */ 0.0, /* .y = */ 0.0,
+	  /* blue */
+	  /* .r = */ 0x00, /* .g = */ 0x00, /* .b = */ 0xff, /* .a = */ 0xff },
+
+	{ /* .x = */ 100.0, /* .y = */ 100.0,
+	  /* transparent blue */
+	  /* .r = */ 0x00, /* .g = */ 0x00, /* .b = */ 0xff, /* .a = */ 0x00 },
+
+	{ /* .x = */ 0.0, /* .y = */ 100.0,
+	  /* transparent blue */
+	  /* .r = */ 0x00, /* .g = */ 0x00, /* .b = */ 0xff, /* .a = */ 0x00 },
+      };
+
+    /* We assume the compiler is doing no funny struct padding for this test:
+     */
+    g_assert (sizeof (InterlevedVertex) == 12);
+
+    state.mesh = cogl_mesh_new (3 /* n vertices */);
+    cogl_mesh_add_attribute (state.mesh,
+			     "gl_Vertex",
+			     2, /* n components */
+			     GL_FLOAT,
+			     FALSE, /* normalized */
+			     12, /* stride */
+			     &verts[0].x);
+    cogl_mesh_add_attribute (state.mesh,
+			     "gl_Color",
+			     4, /* n components */
+			     GL_UNSIGNED_BYTE,
+			     FALSE, /* normalized */
+			     12, /* stride */
+			     &verts[0].r);
+    cogl_mesh_submit (state.mesh);
+  }
+
+  clutter_actor_show_all (stage);
+
+  clutter_main ();
+
+  cogl_mesh_unref (state.mesh);
+
+  g_print ("OK\n");
+}
+

tests/conform/test-mesh-mutability.c

@@ -0,0 +1,198 @@
+
+#include <clutter/clutter.h>
+#include <cogl/cogl.h>
+
+#include "test-conform-common.h"
+
+/* This test verifies that modifying mesh objects works, by updating
+ * vertex positions, and deleting and re-adding different color attributes.
+ *
+ * If you want visual feedback of what this test paints for debugging purposes,
+ * then remove the call to clutter_main_quit() in validate_result.
+ */
+
+typedef struct _TestState
+{
+  CoglHandle mesh;
+  ClutterGeometry stage_geom;
+  guint frame;
+} TestState;
+
+static void
+validate_result (TestState *state)
+{
+  GLubyte pixel[4];
+  GLint y_off = state->stage_geom.height - 90;
+  /* NB: glReadPixels is done in GL screen space so y = 0 is at the bottom */
+
+  /* NB: We ignore the alpha, since we don't know if our render target is
+   * RGB or RGBA */
+
+#define RED 0
+#define GREEN 1
+#define BLUE 2
+
+  /* Should see a red pixel */
+  glReadPixels (110, y_off, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, &pixel);
+  g_print ("pixel 0 = %x, %x, %x\n", pixel[RED], pixel[GREEN], pixel[BLUE]);
+  g_assert (pixel[RED] != 0 && pixel[GREEN] == 0 && pixel[BLUE] == 0);
+
+  /* Should see a green pixel */
+  glReadPixels (210, y_off, 1, 1, GL_RGBA, GL_UNSIGNED_BYTE, &pixel);
+  g_print ("pixel 1 = %x, %x, %x\n", pixel[RED], pixel[GREEN], pixel[BLUE]);
+  g_assert (pixel[RED] == 0 && pixel[GREEN] != 0 && pixel[BLUE] == 0);
+
+#undef RED
+#undef GREEN
+#undef BLUE
+  
+  /* Comment this out if you want visual feedback of what this test
+   * paints.
+   */
+  clutter_main_quit ();
+}
+
+static void
+on_paint (ClutterActor *actor, TestState *state)
+{
+  GLfloat triangle_verts[3][2] =
+    {
+      {100.0, 0.0},
+      {200.0, 100.0},
+      {100.0, 100.0}
+    };
+  GLbyte triangle_colors[3][4] =
+    {
+      {0x00, 0xff, 0x00, 0xff}, /* blue */
+      {0x00, 0xff, 0x00, 0x00}, /* transparent blue */
+      {0x00, 0xff, 0x00, 0x00}  /* transparent blue */
+    };
+
+  /*
+   * Draw a red triangle
+   */
+
+  glColor4ub (0xff, 0x00, 0x00, 0xff);
+
+  cogl_mesh_add_attribute (state->mesh,
+			   "gl_Vertex",
+			   2, /* n components */
+			   GL_FLOAT,
+			   FALSE, /* normalized */
+			   0, /* stride */
+			   triangle_verts);
+  cogl_mesh_delete_attribute (state->mesh, "gl_Color");
+  cogl_mesh_submit (state->mesh);
+  
+  cogl_mesh_draw_arrays (state->mesh,
+			 GL_TRIANGLE_STRIP, /* mode */
+			 0, /* first */
+			 3); /* count */
+  
+  /*
+   * Draw a faded green triangle
+   */
+
+  cogl_mesh_add_attribute (state->mesh,
+			   "gl_Color",
+			   4, /* n components */
+			   GL_UNSIGNED_BYTE,
+			   FALSE, /* normalized */
+			   0, /* stride */
+			   triangle_colors);
+  cogl_mesh_submit (state->mesh);
+
+  cogl_translate (100, 0, 0);
+  cogl_mesh_draw_arrays (state->mesh,
+			 GL_TRIANGLE_STRIP, /* mode */
+			 0, /* first */
+			 3); /* count */
+
+  
+  /* XXX: Experiments have shown that for some buggy drivers, when using
+   * glReadPixels there is some kind of race, so we delay our test for a
+   * few frames and a few seconds:
+   */
+  if (state->frame >= 2)
+    validate_result (state);
+  else
+    sleep (1);
+  
+  state->frame++;
+}
+
+static gboolean
+queue_redraw (gpointer stage)
+{
+  clutter_actor_queue_redraw (CLUTTER_ACTOR (stage));
+}
+
+void
+test_mesh_mutability (TestConformSimpleFixture *fixture,
+		      gconstpointer data)
+{
+  TestState state;
+  ClutterActor *stage;
+  ClutterColor stage_clr = {0x0, 0x0, 0x0, 0xff};
+  ClutterActor *group;
+
+  state.frame = 0;
+
+  stage = clutter_stage_get_default ();
+
+  clutter_stage_set_color (CLUTTER_STAGE (stage), &stage_clr);
+  clutter_actor_get_geometry (stage, &state.stage_geom);
+
+  group = clutter_group_new ();
+  clutter_actor_set_size (group,
+			  state.stage_geom.width,
+			  state.stage_geom.height);
+  clutter_container_add_actor (CLUTTER_CONTAINER (stage), group);
+
+  /* We force continuous redrawing of the stage, since we need to skip
+   * the first few frames, and we wont be doing anything else that
+   * will trigger redrawing. */
+  g_idle_add (queue_redraw, stage);
+
+  g_signal_connect (group, "paint", G_CALLBACK (on_paint), &state);
+  
+  {
+    GLfloat triangle_verts[3][2] =
+      {
+	{0.0,	0.0},
+	{100.0, 100.0},
+	{0.0,	100.0}
+      };
+    GLbyte triangle_colors[3][4] =
+      {
+	{0x00, 0x00, 0xff, 0xff}, /* blue */
+	{0x00, 0x00, 0xff, 0x00}, /* transparent blue */
+	{0x00, 0x00, 0xff, 0x00}  /* transparent blue */
+      };
+    state.mesh = cogl_mesh_new (3 /* n vertices */);
+    cogl_mesh_add_attribute (state.mesh,
+			     "gl_Vertex",
+			     2, /* n components */
+			     GL_FLOAT,
+			     FALSE, /* normalized */
+			     0, /* stride */
+			     triangle_verts);
+    cogl_mesh_add_attribute (state.mesh,
+			     "gl_Color",
+			     4, /* n components */
+			     GL_UNSIGNED_BYTE,
+			     FALSE, /* normalized */
+			     0, /* stride */
+			     triangle_colors);
+    cogl_mesh_submit (state.mesh);
+  }
+
+  clutter_actor_show_all (stage);
+
+  clutter_main ();
+
+  cogl_mesh_unref (state.mesh);
+
+  g_print ("OK\n");
+}
+