cogl-color: add cogl_color_init_from_xyz funcs

This is to try and improve API consistency. Simple cogl structures that
don't derive from CoglObject and which can be allocated on the stack,
such as CoglColor and CoglMatrix should all have  "_init" or
"_init_from" functions to initialize all the structure members. (As
opposed to a cogl_xyz_new() function for CoglObjects). CoglColor
previously used the naming scheme "_set_from" for these initializers but
"_set" is typically reserved for setting individual properties of a
structure/object.

This adds three _init functions:
cogl_color_init_from_4ub
cogl_color_init_from_4f
cogl_color_init_from_4fv

The _set_from functions are now deprecated but only with a gtk-doc
annotation for now. This is because the cogl_color_set_from API is quite
widely used already and so were giving a grace period before enabling a
GCC deprecated warning just because otherwise the MX maintainers will
complain to me that I've made their build logs look messy.

cogl/cogl-color.c

@@ -53,6 +53,22 @@ cogl_color_free (CoglColor *color)
     g_slice_free (CoglColor, color);
 }
 
+void
+cogl_color_init_from_4ub (CoglColor *color,
+                          guint8     red,
+                          guint8     green,
+                          guint8     blue,
+                          guint8     alpha)
+{
+  g_return_if_fail (color != NULL);
+
+  color->red   = red;
+  color->green = green;
+  color->blue  = blue;
+  color->alpha = alpha;
+}
+
+/* XXX: deprecated, use cogl_color_init_from_4ub */
 void
 cogl_color_set_from_4ub (CoglColor *dest,
                          guint8     red,
@@ -60,27 +76,45 @@ cogl_color_set_from_4ub (CoglColor *dest,
                          guint8     blue,
                          guint8     alpha)
 {
-  g_return_if_fail (dest != NULL);
+  cogl_color_init_from_4ub (dest, red, green, blue, alpha);
-
-  dest->red   = red;
-  dest->green = green;
-  dest->blue  = blue;
-  dest->alpha = alpha;
 }
 
 void
-cogl_color_set_from_4f (CoglColor *dest,
+cogl_color_init_from_4f (CoglColor *color,
-                        float  red,
+                         float      red,
-                        float  green,
+                         float      green,
-                        float  blue,
+                         float      blue,
-                        float  alpha)
+                         float      alpha)
 {
-  g_return_if_fail (dest != NULL);
+  g_return_if_fail (color != NULL);
 
-  dest->red   =  (red * 255);
+  color->red   =  (red * 255);
-  dest->green =  (green * 255);
+  color->green =  (green * 255);
-  dest->blue  =  (blue * 255);
+  color->blue  =  (blue * 255);
-  dest->alpha =  (alpha * 255);
+  color->alpha =  (alpha * 255);
+}
+
+/* XXX: deprecated, use cogl_color_init_from_4f */
+void
+cogl_color_set_from_4f (CoglColor *color,
+                        float      red,
+                        float      green,
+                        float      blue,
+                        float      alpha)
+{
+  cogl_color_init_from_4f (color, red, green, blue, alpha);
+}
+
+void
+cogl_color_init_from_4fv (CoglColor *color,
+                          float *color_array)
+{
+  g_return_if_fail (color != NULL);
+
+  color->red   =  (color_array[0] * 255);
+  color->green =  (color_array[1] * 255);
+  color->blue  =  (color_array[2] * 255);
+  color->alpha =  (color_array[3] * 255);
 }
 
 unsigned char

cogl/cogl-color.h

@@ -80,9 +80,28 @@ cogl_color_copy (const CoglColor *color);
 void
 cogl_color_free (CoglColor *color);
 
+/**
+ * cogl_color_init_from_4ub:
+ * @color: A pointer to a #CoglColor to initialize
+ * @red: value of the red channel, between 0 and 255
+ * @green: value of the green channel, between 0 and 255
+ * @blue: value of the blue channel, between 0 and 255
+ * @alpha: value of the alpha channel, between 0 and 255
+ *
+ * Sets the values of the passed channels into a #CoglColor.
+ *
+ * Since: 1.4
+ */
+void
+cogl_color_init_from_4ub (CoglColor *color,
+                          guint8 red,
+                          guint8 green,
+                          guint8 blue,
+                          guint8 alpha);
+
 /**
  * cogl_color_set_from_4ub:
- * @dest: return location for a #CoglColor
+ * @color: A pointer to a #CoglColor to initialize
  * @red: value of the red channel, between 0 and 255
  * @green: value of the green channel, between 0 and 255
  * @blue: value of the blue channel, between 0 and 255
@@ -91,17 +110,37 @@ cogl_color_free (CoglColor *color);
  * Sets the values of the passed channels into a #CoglColor.
  *
  * Since: 1.0
+ * Deprecated: 1.4: Use cogl_color_init_from_4ub instead.
  */
 void
-cogl_color_set_from_4ub (CoglColor *dest,
+cogl_color_set_from_4ub (CoglColor *color,
                          guint8 red,
                          guint8 green,
                          guint8 blue,
                          guint8 alpha);
 
+/**
+ * cogl_color_init_from_4f:
+ * @color: A pointer to a #CoglColor to initialize
+ * @red: value of the red channel, between 0 and %1.0
+ * @green: value of the green channel, between 0 and %1.0
+ * @blue: value of the blue channel, between 0 and %1.0
+ * @alpha: value of the alpha channel, between 0 and %1.0
+ *
+ * Sets the values of the passed channels into a #CoglColor
+ *
+ * Since: 1.4
+ */
+void
+cogl_color_init_from_4f (CoglColor *color,
+                         float red,
+                         float green,
+                         float blue,
+                         float alpha);
+
 /**
  * cogl_color_set_from_4f:
- * @dest: return location for a #CoglColor
+ * @color: A pointer to a #CoglColor to initialize
  * @red: value of the red channel, between 0 and %1.0
  * @green: value of the green channel, between 0 and %1.0
  * @blue: value of the blue channel, between 0 and %1.0
@@ -110,14 +149,28 @@ cogl_color_set_from_4ub (CoglColor *dest,
  * Sets the values of the passed channels into a #CoglColor
  *
  * Since: 1.0
+ * Deprecated: 1.4: Use cogl_color_init_from_4f instead.
  */
 void
-cogl_color_set_from_4f (CoglColor *dest,
+cogl_color_set_from_4f (CoglColor *color,
                         float red,
                         float green,
                         float blue,
                         float alpha);
 
+/**
+ * cogl_color_init_from_4fv:
+ * @color: A pointer to a #CoglColor to initialize
+ * @color_array: a pointer to an array of 4 float color components
+ *
+ * Sets the values of the passed channels into a #CoglColor
+ *
+ * Since: 1.4
+ */
+void
+cogl_color_init_from_4fv (CoglColor *color,
+                          float *color_array);
+
 /**
  * cogl_color_get_red_byte:
  * @color: a #CoglColor