diff --git a/cogl/cogl-bitmap.h b/cogl/cogl-bitmap.h index 958327d78..fed0a02b3 100644 --- a/cogl/cogl-bitmap.h +++ b/cogl/cogl-bitmap.h @@ -65,7 +65,6 @@ cogl_bitmap_new_from_file (const char *filename, #if defined (COGL_ENABLE_EXPERIMENTAL_API) -#define cogl_bitmap_new_from_buffer cogl_bitmap_new_from_buffer_EXP /** * cogl_bitmap_new_from_buffer: * @buffer: A #CoglBuffer containing image data diff --git a/cogl/cogl-buffer.h b/cogl/cogl-buffer.h index 800702e89..4c4576f32 100644 --- a/cogl/cogl-buffer.h +++ b/cogl/cogl-buffer.h @@ -40,7 +40,7 @@ G_BEGIN_DECLS /** * SECTION:cogl-buffer * @short_description: Common buffer functions, including data upload APIs - * @stability: Unstable + * @stability: unstable * * The CoglBuffer API provides a common interface to manipulate * buffers that have been allocated either via cogl_pixel_buffer_new() @@ -59,21 +59,6 @@ G_BEGIN_DECLS * without blocking other Cogl operations. */ -/* 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 - #define COGL_BUFFER(buffer) ((CoglBuffer *)(buffer)) typedef struct _CoglBuffer CoglBuffer; @@ -87,7 +72,7 @@ typedef struct _CoglBuffer CoglBuffer; * Return value: %TRUE if the handle is a CoglBuffer, and %FALSE otherwise * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ gboolean cogl_is_buffer (const void *object); @@ -101,7 +86,7 @@ cogl_is_buffer (const void *object); * Return value: the size of the buffer in bytes * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ unsigned int cogl_buffer_get_size (CoglBuffer *buffer); @@ -117,7 +102,7 @@ cogl_buffer_get_size (CoglBuffer *buffer); * the buffer data is going to be updated. * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/ COGL_BUFFER_UPDATE_HINT_STATIC, @@ -134,7 +119,7 @@ typedef enum { /*< prefix=COGL_BUFFER_UPDATE_HINT >*/ * of the available hints. * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ void cogl_buffer_set_update_hint (CoglBuffer *buffer, @@ -149,7 +134,7 @@ cogl_buffer_set_update_hint (CoglBuffer *buffer, * Return value: the #CoglBufferUpdateHint currently used by the buffer * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ CoglBufferUpdateHint cogl_buffer_get_update_hint (CoglBuffer *buffer); @@ -164,7 +149,7 @@ cogl_buffer_get_update_hint (CoglBuffer *buffer); * The access hints for cogl_buffer_set_update_hint() * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ typedef enum { /*< prefix=COGL_BUFFER_ACCESS >*/ COGL_BUFFER_ACCESS_READ = 1 << 0, @@ -182,7 +167,7 @@ typedef enum { /*< prefix=COGL_BUFFER_ACCESS >*/ * is mapped. * * Since: 1.4 - * Stability: Unstable + * Stability: unstable */ typedef enum { /*< prefix=COGL_BUFFER_MAP_HINT >*/ COGL_BUFFER_MAP_HINT_DISCARD = 1 << 0 @@ -211,7 +196,7 @@ typedef enum { /*< prefix=COGL_BUFFER_MAP_HINT >*/ * Return value: A pointer to the mapped memory or %NULL is the call fails * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ void * cogl_buffer_map (CoglBuffer *buffer, @@ -225,7 +210,7 @@ cogl_buffer_map (CoglBuffer *buffer, * Unmaps a buffer previously mapped by cogl_buffer_map(). * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ void cogl_buffer_unmap (CoglBuffer *buffer); @@ -244,7 +229,7 @@ cogl_buffer_unmap (CoglBuffer *buffer); * Return value: %TRUE is the operation succeeded, %FALSE otherwise * * Since: 1.2 - * Stability: Unstable + * Stability: unstable */ gboolean cogl_buffer_set_data (CoglBuffer *buffer, diff --git a/cogl/cogl-context.h b/cogl/cogl-context.h index 5d2913083..75c0702ce 100644 --- a/cogl/cogl-context.h +++ b/cogl/cogl-context.h @@ -43,36 +43,94 @@ G_BEGIN_DECLS * SECTION:cogl-context * @short_description: The top level application context. * - * A CoglContext is the topmost sandbox of Cogl state for an - * application or toolkit. Its main purpose is to bind together the - * key state objects at any one time; with the most significant being - * the current framebuffer being drawn too (See #CoglFramebuffer for - * more details) and the current GPU pipeline configuration (See - * #CoglPipeline for more details). + * A #CoglContext is the top most sandbox of Cogl state for an + * application or toolkit. Its main purpose is to act as a sandbox + * for the memory management of state objects. Normally an application + * will only create a single context since there is no way to share + * resources between contexts. + * + * For those familiar with OpenGL or perhaps Cairo it should be + * understood that unlike these APIs a Cogl context isn't a rendering + * context as such. In other words Cogl doesn't aim to provide a state + * machine style model for configuring rendering parameters. Most + * rendering state in Cogl is directly associated with user managed + * objects called pipelines and geometry is drawn with a specific + * pipeline object to a framebuffer object and those 3 things fully + * define the state for drawing. This is an important part of Cogl's + * design since it helps you write orthogonal rendering components + * that can all access the same GPU without having to worry about + * what state other components have left you with. */ typedef struct _CoglContext CoglContext; #define COGL_CONTEXT(OBJECT) ((CoglContext *)OBJECT) -#define cogl_context_new cogl_context_new_EXP - +/** + * cogl_context_new: + * @display: A #CoglDisplay pointer + * @error: A GError return location. + * + * Creates a new #CoglContext which acts as an application sandbox + * for any state objects that are allocated. + * + * Return value: (transfer full): A newly allocated #CoglContext + * Since: 1.8 + * Stability: unstable + */ CoglContext * cogl_context_new (CoglDisplay *display, GError **error); -#define cogl_context_get_display cogl_context_get_display_EXP +/** + * cogl_context_get_display: + * @context: A #CoglContext pointer + * + * Retrieves the #CoglDisplay that is internally associated with the + * given @context. This will return the same #CoglDisplay that was + * passed to cogl_context_new() or if %NULL was passed to + * cogl_context_new() then this function returns a pointer to the + * display that was automatically setup internally. + * + * Return value: (transfer none): The #CoglDisplay associated with the + * given @context. + * Since: 1.8 + * Stability: unstable + */ CoglDisplay * cogl_context_get_display (CoglContext *context); #ifdef COGL_HAS_EGL_SUPPORT -#define cogl_egl_context_get_egl_display cogl_egl_context_get_egl_display_EXP +/** + * cogl_egl_context_get_egl_display: + * @context: A #CoglContext pointer + * + * If you have done a runtime check to determine that Cogl is using + * EGL internally then this API can be used to retrieve the EGLDisplay + * handle that was setup internally. The result is undefined if Cogl + * is not using EGL. + * + * Return value: The internally setup EGLDisplay handle. + * Since: 1.8 + * Stability: unstable + */ EGLDisplay cogl_egl_context_get_egl_display (CoglContext *context); #endif #ifdef COGL_HAS_EGL_PLATFORM_ANDROID_SUPPORT -#define cogl_android_set_native_window cogl_android_set_native_window_EXP +/** + * cogl_android_set_native_window: + * @window: A native Android window + * + * Allows Android applications to inform Cogl of the native window + * that they have been given which Cogl can render too. On Android + * this API must be used before creating a #CoglRenderer, #CoglDisplay + * and #CoglContext. + * + * Since: 1.8 + * Stability: unstable + */ void cogl_android_set_native_window (ANativeWindow *window); #endif diff --git a/cogl/cogl-texture-2d-sliced.h b/cogl/cogl-texture-2d-sliced.h index ea8c2a3da..b0e3136aa 100644 --- a/cogl/cogl-texture-2d-sliced.h +++ b/cogl/cogl-texture-2d-sliced.h @@ -66,8 +66,6 @@ typedef struct _CoglTexture2DSliced CoglTexture2DSliced; #define COGL_TEXTURE_2D_SLICED(X) ((CoglTexture2DSliced *)X) -#define cogl_texture_2d_sliced_new_with_size \ - cogl_texture_2d_sliced_new_with_size_EXP /** * cogl_texture_2d_sliced_new_with_size: * @ctx: A #CoglContext