brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

cogl: declare experimental symbols consistently

Browse Source 
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.
This commit is contained in:
Robert Bragg 2010-06-30 18:06:04 +01:00
parent a0a06f0342
commit 1000c80444
6 changed files with 96 additions and 210 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
cogl/cogl-buffer.c
View File

@ -68,10 +68,8 @@
#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,7 +184,7 @@ cogl_buffer_get_size_EXP (CoglBuffer *buffer)
}
void
cogl_buffer_set_usage_hint_EXP (CoglBuffer *buffer,
cogl_buffer_set_usage_hint (CoglBuffer *buffer,
CoglBufferUsageHint hint)
{
if (!cogl_is_buffer (buffer))
@ -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,7 +206,7 @@ cogl_buffer_get_usage_hint_EXP (CoglBuffer *buffer)
}
void
cogl_buffer_set_update_hint_EXP (CoglBuffer *buffer,
cogl_buffer_set_update_hint (CoglBuffer *buffer,
CoglBufferUpdateHint hint)
{
if (!cogl_is_buffer (buffer))
@ -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,7 +228,7 @@ cogl_buffer_get_update_hint_EXP (CoglBuffer *buffer)
}
guint8 *
cogl_buffer_map_EXP (CoglBuffer *buffer,
cogl_buffer_map (CoglBuffer *buffer,
CoglBufferAccess access)
{
if (!cogl_is_buffer (buffer))
@ -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,7 +254,7 @@ cogl_buffer_unmap_EXP (CoglBuffer *buffer)
}
gboolean
cogl_buffer_set_data_EXP (CoglBuffer *buffer,
cogl_buffer_set_data (CoglBuffer *buffer,
gsize offset,
const guint8 *data,
gsize size)

67
cogl/cogl-buffer.h
View 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__ */

64
cogl/cogl-pixel-buffer.c
View 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,7 +128,7 @@ cogl_pixel_buffer_new_EXP (unsigned int size)
}
CoglHandle
cogl_pixel_buffer_new_for_size_EXP (unsigned int width,
cogl_pixel_buffer_new_for_size (unsigned int width,
unsigned int height,
CoglPixelFormat format,
unsigned int *rowstride)
@ -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,7 +264,7 @@ _cogl_pixel_buffer_set_data (CoglBuffer *buffer,
#if 0
gboolean
cogl_pixel_buffer_set_region_EXP (CoglHandle buffer,
cogl_pixel_buffer_set_region (CoglHandle buffer,
guint8 *data,
unsigned int src_width,
unsigned int src_height,

47
cogl/cogl-pixel-buffer.h
View File

@ -36,6 +36,19 @@
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__ */

22
cogl/cogl-vector.h
View 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? */

56
cogl/winsys/cogl-texture-pixmap-x11.h
View File

@ -28,6 +28,20 @@
#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 */