GNOME.org
 

[cogl/fosdem-2012: 2/17] stash: start removing _EXP defines and improving docs

commit 4420b43496a764c97568c14a2d6c8d2a831bc98d
Author: Robert Bragg <robert linux intel com>
Date:   Fri Dec 16 15:07:25 2011 +0000

    stash: start removing _EXP defines and improving docs

 cogl/cogl-bitmap.h            |    1 -
 cogl/cogl-buffer.h            |   37 ++++++-------------
 cogl/cogl-context.h           |   80 +++++++++++++++++++++++++++++++++++------
 cogl/cogl-texture-2d-sliced.h |    2 -
 4 files changed, 80 insertions(+), 40 deletions(-)
---
diff --git a/cogl/cogl-bitmap.h b/cogl/cogl-bitmap.h
index 958327d..fed0a02 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 800702e..4c4576f 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 9c616d3..56f3b1d 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 an 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 ea8c2a3..b0e3136 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
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]