cogl: declare experimental symbols consistently
authorRobert Bragg <robert@linux.intel.com>
Wed, 30 Jun 2010 17:06:04 +0000 (18:06 +0100)
committerRobert Bragg <robert@linux.intel.com>
Wed, 30 Jun 2010 17:51:31 +0000 (18:51 +0100)
We had several different ways of exposing experimental API, in one case
the symbols had no special suffix, in two other ways the symbols were
given an _EXP suffix but in different ways.

This makes all experimental API have an _EXP suffix which is handled
using #defines in the header so the prototypes in the .c and .h files
don't have the suffix.

The documented reason for the suffix is so that anyone watching Cogl for
ABI changes who sees symbols disappear will hopefully understand what's
going on.

clutter/cogl/cogl/cogl-buffer.c
clutter/cogl/cogl/cogl-buffer.h
clutter/cogl/cogl/cogl-pixel-buffer.c
clutter/cogl/cogl/cogl-pixel-buffer.h
clutter/cogl/cogl/cogl-vector.h
clutter/cogl/cogl/winsys/cogl-texture-pixmap-x11.h

index a3ede8f..89c5132 100644 (file)
 
 #endif
 
-void cogl_buffer_unmap_EXP (CoglBuffer *buffer);
-
 gboolean
-cogl_is_buffer_EXP (const void *object)
+cogl_is_buffer (const void *object)
 {
   CoglObject *obj = (CoglObject *)object;
 
@@ -177,7 +175,7 @@ _cogl_buffer_bind (CoglBuffer *buffer,
 }
 
 unsigned int
-cogl_buffer_get_size_EXP (CoglBuffer *buffer)
+cogl_buffer_get_size (CoglBuffer *buffer)
 {
   if (!cogl_is_buffer (buffer))
     return 0;
@@ -186,8 +184,8 @@ cogl_buffer_get_size_EXP (CoglBuffer *buffer)
 }
 
 void
-cogl_buffer_set_usage_hint_EXP (CoglBuffer *buffer,
-                                CoglBufferUsageHint hint)
+cogl_buffer_set_usage_hint (CoglBuffer *buffer,
+                            CoglBufferUsageHint hint)
 {
   if (!cogl_is_buffer (buffer))
     return;
@@ -199,7 +197,7 @@ cogl_buffer_set_usage_hint_EXP (CoglBuffer *buffer,
 }
 
 CoglBufferUsageHint
-cogl_buffer_get_usage_hint_EXP (CoglBuffer *buffer)
+cogl_buffer_get_usage_hint (CoglBuffer *buffer)
 {
   if (!cogl_is_buffer (buffer))
     return FALSE;
@@ -208,8 +206,8 @@ cogl_buffer_get_usage_hint_EXP (CoglBuffer *buffer)
 }
 
 void
-cogl_buffer_set_update_hint_EXP (CoglBuffer *buffer,
-                                 CoglBufferUpdateHint hint)
+cogl_buffer_set_update_hint (CoglBuffer *buffer,
+                             CoglBufferUpdateHint hint)
 {
   if (!cogl_is_buffer (buffer))
     return;
@@ -221,7 +219,7 @@ cogl_buffer_set_update_hint_EXP (CoglBuffer *buffer,
 }
 
 CoglBufferUpdateHint
-cogl_buffer_get_update_hint_EXP (CoglBuffer *buffer)
+cogl_buffer_get_update_hint (CoglBuffer *buffer)
 {
   if (!cogl_is_buffer (buffer))
     return FALSE;
@@ -230,8 +228,8 @@ cogl_buffer_get_update_hint_EXP (CoglBuffer *buffer)
 }
 
 guint8 *
-cogl_buffer_map_EXP (CoglBuffer      *buffer,
-                     CoglBufferAccess access)
+cogl_buffer_map (CoglBuffer      *buffer,
+                 CoglBufferAccess access)
 {
   if (!cogl_is_buffer (buffer))
     return NULL;
@@ -244,7 +242,7 @@ cogl_buffer_map_EXP (CoglBuffer      *buffer,
 }
 
 void
-cogl_buffer_unmap_EXP (CoglBuffer *buffer)
+cogl_buffer_unmap (CoglBuffer *buffer)
 {
   if (!cogl_is_buffer (buffer))
     return;
@@ -256,10 +254,10 @@ cogl_buffer_unmap_EXP (CoglBuffer *buffer)
 }
 
 gboolean
-cogl_buffer_set_data_EXP (CoglBuffer   *buffer,
-                          gsize         offset,
-                          const guint8 *data,
-                          gsize         size)
+cogl_buffer_set_data (CoglBuffer   *buffer,
+                      gsize         offset,
+                      const guint8 *data,
+                      gsize         size)
 {
   if (!cogl_is_buffer (buffer))
     return FALSE;
index 8cdf3dd..8406ba8 100644 (file)
@@ -45,11 +45,26 @@ G_BEGIN_DECLS
  * OpenGL implementation allows it, COGL will use Pixel Buffer Objects.
  */
 
+/* All of the cogl-buffer API is currently experimental so we suffix
+ * the actual symbols with _EXP so if somone is monitoring for ABI
+ * changes it will hopefully be clearer to them what's going on if any
+ * of the symbols dissapear at a later date.
+ */
+#define cogl_is_buffer  cogl_is_buffer_EXP
+#define cogl_buffer_get_size cogl_buffer_get_size_EXP
+#define cogl_buffer_set_usage_hint cogl_buffer_set_usage_hint_EXP
+#define cogl_buffer_get_usage_hint cogl_buffer_get_usage_hint_EXP
+#define cogl_buffer_set_update_hint cogl_buffer_set_update_hint_EXP
+#define cogl_buffer_get_update_hint cogl_buffer_get_update_hint_EXP
+#define cogl_buffer_map cogl_buffer_map_EXP
+#define cogl_buffer_unmap cogl_buffer_unmap_EXP
+#define cogl_buffer_set_data cogl_buffer_set_data_EXP
+
 typedef struct _CoglBuffer CoglBuffer;
 
 /**
  * cogl_is_buffer:
- * @handle: a #CoglHandle to test
+ * @buffer: a buffer object
  *
  * Checks whether @buffer is a buffer object.
  *
@@ -59,7 +74,7 @@ typedef struct _CoglBuffer CoglBuffer;
  * Stability: Unstable
  */
 gboolean
-cogl_is_buffer (CoglHandle handle);
+cogl_is_buffer (const void *object);
 
 /**
  * cogl_buffer_get_size:
@@ -236,54 +251,6 @@ cogl_buffer_set_data (CoglBuffer  *buffer,
                       const guint8 *data,
                       gsize        size);
 
-/* the functions above are experimental, the actual symbols are suffixed by
- * _EXP so we can ensure ABI compatibility and leave the cogl_buffer namespace
- * free for future use. A bunch of defines translates the symbols documented
- * above into the real symbols */
-
-gboolean
-cogl_is_buffer_EXP (const void *object);
-
-unsigned int
-cogl_buffer_get_size_EXP (CoglBuffer *buffer);
-
-void
-cogl_buffer_set_usage_hint_EXP (CoglBuffer         *buffer,
-                                CoglBufferUsageHint hint);
-
-CoglBufferUsageHint
-cogl_buffer_get_usage_hint_EXP (CoglBuffer *buffer);
-
-void
-cogl_buffer_set_update_hint_EXP (CoglBuffer          *buffer,
-                                 CoglBufferUpdateHint hint);
-
-CoglBufferUpdateHint
-cogl_buffer_get_update_hint_EXP (CoglBuffer *buffer);
-
-guint8 *
-cogl_buffer_map_EXP (CoglBuffer      *buffer,
-                     CoglBufferAccess access);
-
-void
-cogl_buffer_unmap_EXP (CoglBuffer *buffer);
-
-gboolean
-cogl_buffer_set_data_EXP (CoglBuffer   *buffer,
-                          gsize         offset,
-                          const guint8 *data,
-                          gsize         size);
-
-#define cogl_is_buffer  cogl_is_buffer_EXP
-#define cogl_buffer_get_size cogl_buffer_get_size_EXP
-#define cogl_buffer_set_usage_hint cogl_buffer_set_usage_hint_EXP
-#define cogl_buffer_get_usage_hint cogl_buffer_get_usage_hint_EXP
-#define cogl_buffer_set_update_hint cogl_buffer_set_update_hint_EXP
-#define cogl_buffer_get_update_hint cogl_buffer_get_update_hint_EXP
-#define cogl_buffer_map cogl_buffer_map_EXP
-#define cogl_buffer_unmap cogl_buffer_unmap_EXP
-#define cogl_buffer_set_data cogl_buffer_set_data_EXP
-
 G_END_DECLS
 
 #endif /* __COGL_BUFFER_H__ */
index 2ad748d..00ca0b9 100644 (file)
@@ -84,62 +84,10 @@ cogl_pixel_buffer_vtable;
 static const CoglBufferVtable
 cogl_malloc_pixel_buffer_vtable;
 
-/* we don't want to use the stock COGL_HANDLE_DEFINE * for 2 reasons:
- *   - it defines already deprecated symbols
- *   - we want to suffix the public symbols by _EXP */
-
-#define COGL_HANDLE_DEFINE_EXP(TypeName, type_name)             \
-                                                               \
-static CoglHandleClass _cogl_##type_name##_class;               \
-                                                               \
-GQuark                                                          \
-_cogl_handle_##type_name##_get_type (void)                      \
-{                                                               \
-  static GQuark type = 0;                                       \
-  if (!type)                                                    \
-    type = g_quark_from_static_string ("Cogl"#TypeName);        \
-  return type;                                                  \
-}                                                               \
-                                                               \
-static CoglHandle                                              \
-_cogl_##type_name##_handle_new (Cogl##TypeName *new_obj)       \
-{                                                              \
-  CoglHandleObject *obj = (CoglHandleObject *)&new_obj->_parent;\
-  obj->ref_count = 1;                                           \
-                                                               \
-  obj->klass = &_cogl_##type_name##_class;                      \
-  if (!obj->klass->type)                                        \
-    {                                                           \
-      obj->klass->type = _cogl_handle_##type_name##_get_type ();\
-      obj->klass->virt_free = _cogl_##type_name##_free;         \
-    }                                                           \
-                                                               \
-  _COGL_HANDLE_DEBUG_NEW (TypeName, obj);                       \
-  return (CoglHandle) new_obj;                                 \
-}                                                              \
-                                                               \
-Cogl##TypeName *                                               \
-_cogl_##type_name##_pointer_from_handle (CoglHandle handle)    \
-{                                                              \
-  return (Cogl##TypeName *) handle;                            \
-}                                                              \
-                                                               \
-gboolean                                                       \
-cogl_is_##type_name##_EXP (CoglHandle handle)                  \
-{                                                               \
-  CoglHandleObject *obj = (CoglHandleObject *)handle;           \
-                                                                \
-  if (handle == COGL_INVALID_HANDLE)                            \
-    return FALSE;                                               \
-                                                                \
-  return (obj->klass->type ==                                   \
-          _cogl_handle_##type_name##_get_type ());              \
-}
-
-COGL_HANDLE_DEFINE_EXP(PixelBuffer, pixel_buffer)
+COGL_HANDLE_DEFINE (PixelBuffer, pixel_buffer)
 
 CoglHandle
-cogl_pixel_buffer_new_EXP (unsigned int size)
+cogl_pixel_buffer_new (unsigned int size)
 {
   CoglPixelBuffer *pixel_buffer = g_slice_new0 (CoglPixelBuffer);
   CoglBuffer *buffer = COGL_BUFFER (pixel_buffer);
@@ -180,10 +128,10 @@ cogl_pixel_buffer_new_EXP (unsigned int size)
 }
 
 CoglHandle
-cogl_pixel_buffer_new_for_size_EXP (unsigned int    width,
-                                    unsigned int    height,
-                                    CoglPixelFormat format,
-                                    unsigned int   *rowstride)
+cogl_pixel_buffer_new_for_size (unsigned int    width,
+                                unsigned int    height,
+                                CoglPixelFormat format,
+                                unsigned int   *rowstride)
 {
   CoglHandle buffer;
   CoglPixelBuffer *pixel_buffer;
@@ -193,13 +141,13 @@ cogl_pixel_buffer_new_for_size_EXP (unsigned int    width,
   if (G_UNLIKELY (format == COGL_PIXEL_FORMAT_ANY))
     return COGL_INVALID_HANDLE;
 
-  /* for now we fallback to cogl_pixel_buffer_new_EXP, later, we could ask
+  /* for now we fallback to cogl_pixel_buffer_new, later, we could ask
    * libdrm a tiled buffer for instance */
   stride = width * _cogl_get_format_bpp (format);
   if (rowstride)
     *rowstride = stride;
 
-  buffer = cogl_pixel_buffer_new_EXP (height * stride);
+  buffer = cogl_pixel_buffer_new (height * stride);
   if (G_UNLIKELY (buffer == COGL_INVALID_HANDLE))
     return COGL_INVALID_HANDLE;
 
@@ -316,13 +264,13 @@ _cogl_pixel_buffer_set_data (CoglBuffer   *buffer,
 
 #if 0
 gboolean
-cogl_pixel_buffer_set_region_EXP (CoglHandle   buffer,
-                                  guint8      *data,
-                                  unsigned int src_width,
-                                  unsigned int src_height,
-                                  unsigned int src_rowstride,
-                                  unsigned int dst_x,
-                                  unsigned int dst_y)
+cogl_pixel_buffer_set_region (CoglHandle   buffer,
+                              guint8      *data,
+                              unsigned int src_width,
+                              unsigned int src_height,
+                              unsigned int src_rowstride,
+                              unsigned int dst_x,
+                              unsigned int dst_y)
 {
   if (!cogl_is_pixel_buffer (buffer))
     return FALSE;
index 3dd416f..7e648f7 100644 (file)
 
 G_BEGIN_DECLS
 
+/* All of the cogl-pixel-buffer API is currently experimental so we
+ * suffix the actual symbols with _EXP so if somone is monitoring for
+ * ABI changes it will hopefully be clearer to them what's going on if
+ * any of the symbols dissapear at a later date.
+ */
+
+#define cogl_pixel_buffer_new cogl_pixel_buffer_new_EXP
+#define cogl_pixel_buffer_new_for_size cogl_pixel_buffer_new_for_size_EXP
+#define cogl_is_pixel_buffer cogl_is_pixel_buffer_EXP
+#if 0
+#define cogl_pixel_buffer_set_region cogl_pixel_buffer_set_region_EXP
+#endif
+
 /**
  * cogl_pixel_buffer_new:
  * @size: size of the buffer in bytes
@@ -126,40 +139,6 @@ cogl_pixel_buffer_set_region (CoglHandle    buffer,
                               unsigned int  dst_y);
 #endif
 
-/* the functions above are experimental, the actual symbols are suffixed by
- * _EXP so we can ensure ABI compatibility and leave the cogl_buffer namespace
- * free for future use. A bunch of defines translates the symbols documented
- * above into the real symbols */
-
-CoglHandle
-cogl_pixel_buffer_new_EXP (unsigned int size);
-
-CoglHandle
-cogl_pixel_buffer_new_for_size_EXP (unsigned int    width,
-                                    unsigned int    height,
-                                    CoglPixelFormat format,
-                                    unsigned int   *stride);
-gboolean
-cogl_is_pixel_buffer_EXP (CoglHandle handle);
-
-#if 0
-gboolean
-cogl_pixel_buffer_set_region_EXP (CoglHandle   buffer,
-                                  guint8      *data,
-                                  unsigned int src_width,
-                                  unsigned int src_height,
-                                  unsigned int src_rowstride,
-                                  unsigned int dst_x,
-                                  unsigned int dst_y);
-#endif
-
-#define cogl_pixel_buffer_new cogl_pixel_buffer_new_EXP
-#define cogl_pixel_buffer_new_for_size cogl_pixel_buffer_new_for_size_EXP
-#define cogl_is_pixel_buffer cogl_is_pixel_buffer_EXP
-#if 0
-#define cogl_pixel_buffer_set_region cogl_pixel_buffer_set_region_EXP
-#endif
-
 G_END_DECLS
 
 #endif /* __COGL_PIXEL_BUFFER_H__ */
index dfc5dfb..22307c5 100644 (file)
@@ -44,6 +44,28 @@ G_BEGIN_DECLS
  * component float vectors.
  */
 
+/* All of the cogl-vector API is currently experimental so we
+ * suffix the actual symbols with _EXP so if somone is monitoring for
+ * ABI changes it will hopefully be clearer to them what's going on if
+ * any of the symbols dissapear at a later date.
+ */
+#define cogl_vector3_init cogl_vector3_init_EXP
+#define cogl_vector3_init_zero cogl_vector3_init_zero_EXP
+#define cogl_vector3_equal cogl_vector3_equal_EXP
+#define cogl_vector3_equal_with_epsilon cogl_vector3_equal_with_epsilon_EXP
+#define cogl_vector3_copy cogl_vector3_copy_EXP
+#define cogl_vector3_free cogl_vector3_free_EXP
+#define cogl_vector3_invert cogl_vector3_invert_EXP
+#define cogl_vector3_add cogl_vector3_add_EXP
+#define cogl_vector3_subtract cogl_vector3_subtract_EXP
+#define cogl_vector3_multiply_scalar cogl_vector3_multiply_scalar_EXP
+#define cogl_vector3_divide_scalar cogl_vector3_divide_scalar_EXP
+#define cogl_vector3_normalize cogl_vector3_normalize_EXP
+#define cogl_vector3_magnitude cogl_vector3_magnitude_EXP
+#define cogl_vector3_cross_product cogl_vector3_cross_product_EXP
+#define cogl_vector3_dot_product cogl_vector3_dot_product_EXP
+#define cogl_vector3_distance cogl_vector3_distance_EXP
+
 typedef struct
 {
   /* FIXME: add sse alignment constraint? */
index c7ca2fb..e380bb8 100644 (file)
 
 #ifdef COGL_ENABLE_EXPERIMENTAL_API
 
+/* All of the cogl-texture-pixmap-x11 API is currently experimental so
+ * we suffix the actual symbols with _EXP so if somone is monitoring
+ * for ABI changes it will hopefully be clearer to them what's going
+ * on if any of the symbols dissapear at a later date.
+ */
+#define cogl_texture_pixmap_x11_new cogl_texture_pixmap_x11_new_EXP
+#define cogl_texture_pixmap_x11_update_area \
+  cogl_texture_pixmap_x11_update_area_EXP
+#define cogl_texture_pixmap_x11_is_using_tfp_extension \
+  cogl_texture_pixmap_x11_is_using_tfp_extension_EXP
+#define cogl_texture_pixmap_x11_set_damage_object \
+  cogl_texture_pixmap_x11_set_damage_object_EXP
+#define cogl_is_texture_pixmap_x11 cogl_is_texture_pixmap_x11_EXP
+
 typedef enum
 {
   COGL_TEXTURE_PIXMAP_X11_DAMAGE_RAW_RECTANGLES,
@@ -129,48 +143,6 @@ cogl_texture_pixmap_x11_set_damage_object (CoglHandle handle,
 gboolean
 cogl_is_texture_pixmap_x11 (CoglHandle handle);
 
-/* All of the cogl-texture-pixmap-x11 API is currently experimental so
-   we suffix the actual symbols with _EXP to ensure ABI
-   compatibility. A bunch of defines translates the symbols documented
-   above into the real symbols */
-
-CoglHandle
-cogl_texture_pixmap_x11_new_EXP (guint32 pixmap,
-                                 gboolean automatic_updates);
-
-#define cogl_texture_pixmap_x11_new cogl_texture_pixmap_x11_new_EXP
-
-void
-cogl_texture_pixmap_x11_update_area_EXP (CoglHandle handle,
-                                         int x,
-                                         int y,
-                                         int width,
-                                         int height);
-
-#define cogl_texture_pixmap_x11_update_area \
-  cogl_texture_pixmap_x11_update_area_EXP
-
-gboolean
-cogl_texture_pixmap_x11_is_using_tfp_extension_EXP (CoglHandle handle);
-
-#define cogl_texture_pixmap_x11_is_using_tfp_extension \
-  cogl_texture_pixmap_x11_is_using_tfp_extension_EXP
-
-gboolean
-cogl_is_texture_pixmap_x11_EXP (CoglHandle handle);
-
-#define cogl_is_texture_pixmap_x11 \
-  cogl_is_texture_pixmap_x11_EXP
-
-void
-cogl_texture_pixmap_x11_set_damage_object_EXP (CoglHandle handle,
-                                               guint32 damage,
-                                               CoglTexturePixmapX11ReportLevel
-                                                                  report_level);
-
-#define cogl_texture_pixmap_x11_set_damage_object \
-  cogl_texture_pixmap_x11_set_damage_object_EXP
-
 #endif /* COGL_ENABLE_EXPERIMENTAL_API */
 
 #endif /* __COGL_TEXTURE_PIXMAP_X11_H */