[Cogl] Renames cogl_paint_init to cogl_clear and adds a cogl_disable_fog function

cogl_paint_init was a bit too miscellaneous; it mainly cleared the color, depth
and stencil buffers but arbitrarily it also disabled fogging and lighting.

It no longer disables lighting, since we know Cogl never enables lighting and
disabling of fog is now handled with a seperate function.

Since I noticed cogl_set_fog was taking a density argument documented as
"Ignored" I've also added a mode argument to cogl_set_fog which exposes the
exponential fog modes which can make use of the density.

README

@@ -279,6 +279,13 @@ Release Notes for Clutter 1.0
 * cogl_clip_set* and cogl_clip_unset have been renamed to cogl_clip_push and
   cogl_clip_pop respectively so they self document their stacking semantics.
 
+* cogl_paint_init was renamed to cogl_clear and no longer disables lighting
+  and fogging.
+
+* cogl_fog_set was renamed to cogl_set_fog and it now takes a mode argument
+  giving control over the fogging blend factor equation, so that the
+  density argument isn't just ignored. A cogl_disable_fog function was
+  also added.
 
 Release Notes for Clutter 0.8
 -------------------------------

clutter/clutter-main.c

@@ -367,7 +367,8 @@ _clutter_do_pick (ClutterStage   *stage,
   _clutter_stage_maybe_setup_viewport (stage);
 
   cogl_color_set_from_4ub (&white, 255, 255, 255, 255);
-  cogl_paint_init (&white);
+  cogl_disable_fog ();
+  cogl_clear (&white);
 
   /* Disable dithering (if any) when doing the painting in pick mode */
   dither_was_on = glIsEnabled (GL_DITHER);

clutter/clutter-stage.c

@@ -222,15 +222,18 @@ clutter_stage_paint (ClutterActor *self)
                            priv->color.green,
                            priv->color.blue,
                            priv->color.alpha);
-  cogl_paint_init (&stage_color);
+  cogl_clear (&stage_color);
 
   if (priv->use_fog)
     {
       cogl_set_fog (&stage_color,
+                    COGL_FOG_MODE_LINEAR,
                     priv->fog.density,
                     priv->fog.z_near,
                     priv->fog.z_far);
     }
+  else
+    cogl_disable_fog ();
 
   CLUTTER_NOTE (PAINT, "Proxying the paint to the stage implementation");
   clutter_actor_paint (priv->impl);

clutter/clutter-texture.c

@@ -556,9 +556,10 @@ clutter_texture_paint (ClutterActor *self)
 								NULL);
 	}
 
-      /* cogl_paint_init is called to clear the buffers */
+      /* cogl_clear is called to clear the buffers */
       cogl_color_set_from_4ub (&transparent_col, 0, 0, 0, 0);
-      cogl_paint_init (&transparent_col);
+      cogl_clear (&transparent_col);
+      cogl_disable_fog ();
 
       /* Clear the clipping stack so that if the FBO actor is being
 	 clipped then it won't affect drawing the source */

clutter/cogl/cogl.h.in

@@ -295,94 +295,6 @@ void            cogl_get_projection_matrix    (float        m[16]);
  */
 void            cogl_get_viewport             (float        v[4]);
 
-/**
- * cogl_clip_push:
- * @x_offset: left edge of the clip rectangle
- * @y_offset: top edge of the clip rectangle
- * @width: width of the clip rectangle
- * @height: height of the clip rectangle
- *
- * Specifies a rectangular clipping area for all subsequent drawing
- * operations. Any drawing commands that extend outside the rectangle
- * will be clipped so that only the portion inside the rectangle will
- * be displayed. The rectangle dimensions are transformed by the
- * current model-view matrix.
- *
- * The rectangle is intersected with the current clip region. To undo
- * the effect of this function, call cogl_clip_pop().
- */
-void            cogl_clip_push                (float        x_offset,
-                                               float        y_offset,
-                                               float        width,
-                                               float        height);
-
-/**
- * cogl_clip_push_from_path:
- *
- * Sets a new clipping area using the current path. The current path
- * is then cleared. The clipping area is intersected with the previous
- * clipping area. To restore the previous clipping area, call
- * cogl_clip_pop().
- *
- * Since: 1.0
- */
-void            cogl_clip_push_from_path       (void);
-
-/**
- * cogl_clip_push_from_path_preserve:
- *
- * Sets a new clipping area using the current path. The current path
- * is then cleared. The clipping area is intersected with the previous
- * clipping area. To restore the previous clipping area, call
- * cogl_clip_pop().
- *
- * Since: 1.0
- */
-void            cogl_clip_push_from_path_preserve (void);
-
-/**
- * cogl_clip_pop:
- *
- * Reverts the clipping region to the state before the last call to
- * cogl_clip_push().
- */
-void            cogl_clip_pop               (void);
-
-/**
- * cogl_clip_ensure:
- *
- * Ensures that the current clipping region has been set in GL. This
- * will automatically be called before any Cogl primitives but it
- * maybe be neccessary to call if you are using raw GL calls with
- * clipping.
- *
- * Since: 1.0
- */
-void            cogl_clip_ensure              (void);
-
-/**
- * cogl_clip_stack_save:
- *
- * Save the entire state of the clipping stack and then clear all
- * clipping. The previous state can be returned to with
- * cogl_clip_stack_restore(). Each call to cogl_clip_push() after this
- * must be matched by a call to cogl_clip_pop() before calling
- * cogl_clip_stack_restore().
- *
- * Since: 0.8.2
- */
-void            cogl_clip_stack_save          (void);
-
-/**
- * cogl_clip_stack_restore:
- *
- * Restore the state of the clipping stack that was previously saved
- * by cogl_clip_stack_save().
- *
- * Since: 0.8.2
- */
-void            cogl_clip_stack_restore       (void);
-
 /**
  * cogl_enable_depth_test:
  * @setting: %TRUE to enable depth testing or %FALSE to disable.
@@ -407,33 +319,77 @@ void            cogl_enable_depth_test        (gboolean            setting);
  */
 void            cogl_enable_backface_culling  (gboolean            setting);
 
+/**
+ * CoglFogMode:
+ * @COGL_FOG_MODE_LINEAR: Calculates the fog blend factor as:
+ * <programlisting>
+ * f = end - eye_distance / end - start
+ * </programlisting>
+ * @COGL_FOG_MODE_EXPONENTIAL: Calculates the fog blend factor as:
+ * <programlisting>
+ * f = e ^ -(density * eye_distance)
+ * </programlisting>
+ * @COGL_FOG_MODE_EXPONENTIAL_SQUARED: Calculates the fog blend factor as:
+ * <programlisting>
+ * f = e ^ -(density * eye_distance)^2
+ * </programlisting>
+ *
+ * The fog mode determines the equation used to calculate the fogging blend
+ * factor while fogging is enabled. The simplest COGL_FOG_MODE_LINEAR mode
+ * determines f as:
+ * <programlisting>
+ * f = end - eye_distance / end - start
+ * </programlisting>
+ * Where eye_distance is the distance of the current fragment in eye
+ * coordinates from the origin.
+ */
+typedef enum _CoglFogMode
+{
+  COGL_FOG_MODE_LINEAR,
+  COGL_FOG_MODE_EXPONENTIAL,
+  COGL_FOG_MODE_EXPONENTIAL_SQUARED,
+} CoglFogMode;
+
 /**
  * cogl_set_fog:
  * @fog_color: The color of the fog
- * @density: Ignored
+ * @mode: A CoglFogMode that determines the equation used to calculate the
+ *        fogging blend factor.
+ * @density: Used by the EXPONENTIAL and EXPONENTIAL_SQUARED CoglFogMode
+ *           equations.
  * @z_near: Position along z-axis where no fogging should be applied
  * @z_far: Position along z-axes where full fogging should be applied
  *
  * Enables fogging. Fogging causes vertices that are further away from
- * the eye to be rendered with a different color. The color is
+ * the eye to be rendered with a different color. The color is determined
+ * according to the chosen fog mode; at it's simplest the color is
  * linearly interpolated so that vertices at @z_near are drawn fully
  * with their original color and vertices at @z_far are drawn fully
- * with @fog_color. Fogging will remain enabled until the next call to
+ * with @fog_color. Fogging will remain enabled until you call
- * cogl_paint_init().
+ * cogl_disable_fog().
  */
 void            cogl_set_fog                  (const CoglColor *fog_color,
+                                               CoglFogMode      mode,
                                                float            density,
                                                float            z_near,
                                                float            z_far);
 
 /**
- * cogl_paint_init:
+ * cogl_disable_fog:
+ *
+ * This function disables fogging, so primitives drawn afterwards will not be
+ * blended with any previously set fog color.
+ */
+void            cogl_disable_fog              (void);
+
+/**
+ * cogl_clear:
  * @color: Background color to clear to
  *
  * Clears the color buffer to @color. The depth buffer and stencil
- * buffers are also cleared and fogging and lighting are disabled.
+ * buffers are also cleared.
  */
-void            cogl_paint_init               (const CoglColor *color);
+void            cogl_clear                    (const CoglColor *color);
 
 /**
  * cogl_set_source:
@@ -529,6 +485,105 @@ void            cogl_set_source_color4f       (float red,
  */
 void            cogl_set_source_texture       (CoglHandle texture_handle);
 
+/**
+ * SECTION:cogl-clipping
+ * @short_description: Fuctions for manipulating a stack of clipping regions
+ *
+ * To support clipping your geometry to rectangles or paths Cogl exposes a
+ * stack based API whereby each clip region you push onto the stack is
+ * intersected with the previous region.
+ */
+
+/**
+ * cogl_clip_push:
+ * @x_offset: left edge of the clip rectangle
+ * @y_offset: top edge of the clip rectangle
+ * @width: width of the clip rectangle
+ * @height: height of the clip rectangle
+ *
+ * Specifies a rectangular clipping area for all subsequent drawing
+ * operations. Any drawing commands that extend outside the rectangle
+ * will be clipped so that only the portion inside the rectangle will
+ * be displayed. The rectangle dimensions are transformed by the
+ * current model-view matrix.
+ *
+ * The rectangle is intersected with the current clip region. To undo
+ * the effect of this function, call cogl_clip_pop().
+ */
+void            cogl_clip_push                (float        x_offset,
+                                               float        y_offset,
+                                               float        width,
+                                               float        height);
+
+/**
+ * cogl_clip_push_from_path:
+ *
+ * Sets a new clipping area using the current path. The current path
+ * is then cleared. The clipping area is intersected with the previous
+ * clipping area. To restore the previous clipping area, call
+ * cogl_clip_pop().
+ *
+ * Since: 1.0
+ */
+void            cogl_clip_push_from_path       (void);
+
+/**
+ * cogl_clip_push_from_path_preserve:
+ *
+ * Sets a new clipping area using the current path. The current path
+ * is then cleared. The clipping area is intersected with the previous
+ * clipping area. To restore the previous clipping area, call
+ * cogl_clip_pop().
+ *
+ * Since: 1.0
+ */
+void            cogl_clip_push_from_path_preserve (void);
+
+/**
+ * cogl_clip_pop:
+ *
+ * Reverts the clipping region to the state before the last call to
+ * cogl_clip_push().
+ */
+void            cogl_clip_pop               (void);
+
+/**
+ * cogl_clip_ensure:
+ *
+ * Ensures that the current clipping region has been set in GL. This
+ * will automatically be called before any Cogl primitives but it
+ * maybe be neccessary to call if you are using raw GL calls with
+ * clipping.
+ *
+ * Since: 1.0
+ */
+void            cogl_clip_ensure              (void);
+
+/**
+ * cogl_clip_stack_save:
+ *
+ * Save the entire state of the clipping stack and then clear all
+ * clipping. The previous state can be returned to with
+ * cogl_clip_stack_restore(). Each call to cogl_clip_push() after this
+ * must be matched by a call to cogl_clip_pop() before calling
+ * cogl_clip_stack_restore().
+ *
+ * Since: 0.8.2
+ */
+void            cogl_clip_stack_save          (void);
+
+/**
+ * cogl_clip_stack_restore:
+ *
+ * Restore the state of the clipping stack that was previously saved
+ * by cogl_clip_stack_save().
+ *
+ * Since: 0.8.2
+ */
+void            cogl_clip_stack_restore       (void);
+
+
+
 G_END_DECLS
 
 #undef __COGL_H_INSIDE__

clutter/cogl/gl/cogl.c

@@ -173,7 +173,7 @@ cogl_check_extension (const gchar *name, const gchar *ext)
 }
 
 void
-cogl_paint_init (const CoglColor *color)
+cogl_clear (const CoglColor *color)
 {
 #if COGL_DEBUG
   fprintf(stderr, "\n ============== Paint Start ================ \n");
@@ -185,8 +185,6 @@ cogl_paint_init (const CoglColor *color)
                     0.0) );
 
   glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT);
-  glDisable (GL_LIGHTING);
-  glDisable (GL_FOG);
 
   /*
    *  Disable the depth test for now as has some strange side effects,
@@ -1180,11 +1178,13 @@ cogl_get_bitmasks (gint *red, gint *green, gint *blue, gint *alpha)
 
 void
 cogl_set_fog (const CoglColor *fog_color,
+              CoglFogMode      mode,
               float            density,
               float            z_near,
               float            z_far)
 {
   GLfloat fogColor[4];
+  GLenum gl_mode;
 
   fogColor[0] = cogl_color_get_red_float (fog_color);
   fogColor[1] = cogl_color_get_green_float (fog_color);
@@ -1195,8 +1195,21 @@ cogl_set_fog (const CoglColor *fog_color,
 
   glFogfv (GL_FOG_COLOR, fogColor);
 
+  switch (mode)
+    {
+    case COGL_FOG_MODE_LINEAR:
+      gl_mode = GL_LINEAR;
+      break;
+    case COGL_FOG_MODE_EXPONENTIAL:
+      gl_mode = GL_EXP;
+      break;
+    case COGL_FOG_MODE_EXPONENTIAL_SQUARED:
+      gl_mode = GL_EXP2;
+      break;
+    }
+
   /* NB: GLES doesn't have glFogi */
-  glFogf (GL_FOG_MODE, GL_LINEAR);
+  glFogf (GL_FOG_MODE, gl_mode);
   glHint (GL_FOG_HINT, GL_NICEST);
 
   glFogf (GL_FOG_DENSITY, (GLfloat) density);
@@ -1204,3 +1217,9 @@ cogl_set_fog (const CoglColor *fog_color,
   glFogf (GL_FOG_END, (GLfloat) z_far);
 }
 
+void
+cogl_disable_fog (void)
+{
+  glDisable (GL_FOG);
+}
+

clutter/cogl/gles/cogl.c

@@ -96,7 +96,7 @@ cogl_check_extension (const gchar *name, const gchar *ext)
 }
 
 void
-cogl_paint_init (const CoglColor *color)
+cogl_clear (const CoglColor *color)
 {
 #if COGL_DEBUG
   fprintf(stderr, "\n ============== Paint Start ================ \n");
@@ -108,8 +108,6 @@ cogl_paint_init (const CoglColor *color)
                     0.0) );
 
   glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT | GL_STENCIL_BUFFER_BIT);
-  glDisable (GL_LIGHTING);
-  glDisable (GL_FOG);
 
   /*
    *  Disable the depth test for now as has some strange side effects,
@@ -737,11 +735,13 @@ cogl_get_bitmasks (gint *red, gint *green, gint *blue, gint *alpha)
 
 void
 cogl_set_fog (const CoglColor *fog_color,
+              CoglFogMode      mode,
               float            density,
               float            z_near,
               float            z_far)
 {
   GLfloat fogColor[4];
+  GLenum  gl_mode;
 
   fogColor[0] = cogl_color_get_red_float (fog_color);
   fogColor[1] = cogl_color_get_green_float (fog_color);
@@ -750,10 +750,28 @@ cogl_set_fog (const CoglColor *fog_color,
 
   glEnable (GL_FOG);
 
+#if HAVE_COGL_GLES
+  switch (mode)
+    {
+    case COGL_FOG_MODE_LINEAR:
+      gl_mode = GL_LINEAR;
+      break;
+    case COGL_FOG_MODE_EXPONENTIAL:
+      gl_mode = GL_EXP;
+      break;
+    case COGL_FOG_MODE_EXPONENTIAL_SQUARED:
+      gl_mode = GL_EXP2;
+      break;
+    }
+#else
+  /* TODO: support other modes for GLES2 */
+  gl_mode = GL_LINEAR;
+#endif
+
   glFogfv (GL_FOG_COLOR, fogColor);
 
   /* NB: GLES doesn't have glFogi */
-  glFogf (GL_FOG_MODE, GL_LINEAR);
+  glFogf (GL_FOG_MODE, gl_mode);
   glHint (GL_FOG_HINT, GL_NICEST);
 
   glFogf (GL_FOG_DENSITY, (GLfloat) density);
@@ -761,3 +779,9 @@ cogl_set_fog (const CoglColor *fog_color,
   glFogf (GL_FOG_END, (GLfloat) z_far);
 }
 
+void
+cogl_disable_fog (void)
+{
+  glDisable (GL_FOG);
+}
+

doc/reference/cogl/cogl-sections.txt

@@ -38,21 +38,14 @@ cogl_scale
 cogl_translate
 cogl_rotate
 <SUBSECTION>
+cogl_clear
 cogl_get_bitmasks
-cogl_paint_init
-<SUBSECTION>
-CoglClipStackState
-cogl_clip_push
-cogl_clip_push_from_path
-cogl_clip_push_from_path_preserve
-cogl_clip_pop
-cogl_clip_stack_save
-cogl_clip_stack_restore
-cogl_clip_ensure
-<SUBSECTION>
 cogl_enable_depth_test
 cogl_enable_backface_culling
-cogl_fog_set
+<SUBSECTION>
+CoglFogMode
+cogl_set_fog
+cogl_disable_fog
 <SUBSECTION>
 cogl_set_source
 cogl_set_source_color
@@ -63,6 +56,18 @@ cogl_set_source_texture
 cogl_util_next_p2
 </SECTION>
 
+<SECTION>
+<FILE>cogl-clipping</FILE>
+CoglClipStackState
+cogl_clip_push
+cogl_clip_push_from_path
+cogl_clip_push_from_path_preserve
+cogl_clip_pop
+cogl_clip_stack_save
+cogl_clip_stack_restore
+cogl_clip_ensure
+<SECTION>
+
 <SECTION>
 <FILE>cogl-primitives</FILE>
 <TITLE>Primitives</TITLE>