gegl r2517 - in trunk: . gegl/buffer tests/buffer

[ok svn gnome org]

Author: ok
Date: Tue Jul  1 19:12:43 2008
New Revision: 2517
URL: http://svn.gnome.org/viewvc/gegl?rev=2517&view=rev

Log:
Made the linear buffer access API of GeglBuffer public.
* gegl/buffer/gegl-buffer-linear.h: removed.
* gegl/buffer/Makefile.am: updated.
* gegl/buffer/gegl-buffer-private.h: removed include of
gegl-buffer-linear.h
* gegl/buffer/gegl-buffer.h: moved definitions of linear buffer API
here.
* tests/buffer/buffer-test.c: do not directly include the
gegl-buffer-linear.h header from the GEGL sourcetree anymore.


Removed:
   trunk/gegl/buffer/gegl-buffer-linear.h
Modified:
   trunk/ChangeLog
   trunk/gegl/buffer/Makefile.am
   trunk/gegl/buffer/gegl-buffer-private.h
   trunk/gegl/buffer/gegl-buffer.h
   trunk/tests/buffer/buffer-test.c

Modified: trunk/gegl/buffer/Makefile.am
==============================================================================
--- trunk/gegl/buffer/Makefile.am	(original)
+++ trunk/gegl/buffer/Makefile.am	Tue Jul  1 19:12:43 2008
@@ -41,7 +41,6 @@
     gegl-buffer.h		\
     gegl-buffer-private.h	\
     gegl-buffer-iterator.h	\
-    gegl-buffer-linear.h	\
     gegl-buffer-load.h		\
     gegl-buffer-save.h		\
     gegl-buffer-types.h		\

Modified: trunk/gegl/buffer/gegl-buffer-private.h
==============================================================================
--- trunk/gegl/buffer/gegl-buffer-private.h	(original)
+++ trunk/gegl/buffer/gegl-buffer-private.h	Tue Jul  1 19:12:43 2008
@@ -24,7 +24,6 @@
 #include "gegl-sampler.h"
 #include "gegl-tile-handler.h"
 #include "gegl-buffer-iterator.h"
-#include "gegl-buffer-linear.h"
 
 #define GEGL_BUFFER_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass),  GEGL_TYPE_BUFFER, GeglBufferClass))
 #define GEGL_IS_BUFFER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GEGL_TYPE_BUFFER))

Modified: trunk/gegl/buffer/gegl-buffer.h
==============================================================================
--- trunk/gegl/buffer/gegl-buffer.h	(original)
+++ trunk/gegl/buffer/gegl-buffer.h	Tue Jul  1 19:12:43 2008
@@ -237,6 +237,15 @@
                                                gint                 rowstride);
 
 
+/**
+ * gegl_buffer_get_format:
+ * @buffer: a #GeglBuffer
+ *
+ * Get the native babl format of the buffer.
+ *
+ * Returns: the babl format used for storing pixels in the buffer.
+ * 
+ */
 const Babl    *gegl_buffer_get_format        (GeglBuffer           *buffer);
 
 /**
@@ -299,13 +308,12 @@
  * @interpolation: the interpolation behavior to use, currently only nearest
  * neighbour is implemented for this API, bilinear, bicubic and lanczos needs
  * to be ported from working code. Valid values: GEGL_INTERPOLATION_NEAREST and
- * GEGL_INTERPOLATION_LINEAR, CUBIC and LANCZOS will become available for now they
- * fall back to linear.
+ * GEGL_INTERPOLATION_LINEAR, GEGL_INTERPOLATON_CUBIC and
+ * GEGL_INTERPOLATION_LANCZOS.
  *
- * Resample the buffer at some given coordinates using a specified format. For
- * some operations this might be sufficient, but it might be considered
- * prototyping convenience that needs to be optimized away from algorithms
- * using it later.
+ * Query interpolate pixel values at a given coordinate using a specified form
+ * of interpolation. The samplers used cache for a small neighbourhood of the
+ * buffer for more efficient access.
  */
 void            gegl_buffer_sample            (GeglBuffer       *buffer,
                                                gdouble           x,
@@ -337,6 +345,78 @@
 GeglInterpolation gegl_buffer_interpolation_from_string (const gchar *string);
 
 
+
+/**
+ * gegl_buffer_linear_new:
+ * @extent: dimensions of buffer.
+ * @format: desired pixel format.
+ *
+ * Creates a GeglBuffer backed by a linear memory buffer, of the given
+ * @extent in the specified @format. babl_format ("R'G'B'A u8") for instance
+ * to make a normal 8bit buffer.
+ *
+ * Returns: a GeglBuffer that can be used as any other GeglBuffer.
+ */
+GeglBuffer *gegl_buffer_linear_new           (const GeglRectangle *extent,
+                                              const Babl          *format);
+
+/**
+ * gegl_buffer_linear_new_from_data:
+ * @data: a pointer to a linear buffer in memory.
+ * @format: the format of the data in memory
+ * @extent: the dimensions (and upper left coordinates) of linear buffer.
+ * @rowstride: the number of bytes between rowstarts in memory (or 0 to
+ *             autodetect)
+ * @destory_fn: function to call to free data or NULL if memory should not be
+ *              freed.
+ * @destroy_fn_data: extra argument to be passed to void destroy(ptr, data) type
+ *              function.
+ *
+ * Creates a GeglBuffer backed by a linear memory buffer that already exists,
+ * of the given @extent in the specified @format. babl_format ("R'G'B'A u8")
+ * for instance to make a normal 8bit buffer. 
+ *
+ * Returns: a GeglBuffer that can be used as any other GeglBuffer.
+ */
+GeglBuffer * gegl_buffer_linear_new_from_data (const gpointer       data,
+                                                const Babl          *format,
+                                                const GeglRectangle *extent,
+                                                gint                 rowstride,
+                                                GCallback            destroy_fn,
+                                                gpointer             destroy_fn_data);
+
+/**
+ * gegl_buffer_linear_open:
+ * @buffer: a #GeglBuffer.
+ * @extent: region to open, pass NULL for entire buffer.
+ * @rowstride: return location for rowstride.
+ * @format: desired format or NULL to use buffers format.
+ *
+ * Raw direct random access to the full data of a buffer in linear memory.
+ *
+ * Returns: a pointer to a linear memory region describing the buffer, if the
+ * request is compatible with the underlying data storage direct access
+ * to the underlying data is provided.
+ */
+gpointer       *gegl_buffer_linear_open      (GeglBuffer          *buffer,
+                                              const GeglRectangle *extent,
+                                              gint                *rowstride,
+                                              const Babl          *format);
+
+/**
+ * gegl_buffer_linear_close:
+ * @buffer: a #GeglBuffer.
+ * @linear: a previously returned buffer.
+ *
+ * This function makes sure GeglBuffer and underlying code is aware of changes
+ * being made to the linear buffer. If the request was not a compatible one
+ * it is written back to the buffer. Multiple concurrent users can be handed
+ * the same buffer (both raw access and converted).
+ */
+void            gegl_buffer_linear_close     (GeglBuffer    *buffer,
+                                              gpointer       linear);
+
+
 /**
  */
 #endif

Modified: trunk/tests/buffer/buffer-test.c
==============================================================================
--- trunk/tests/buffer/buffer-test.c	(original)
+++ trunk/tests/buffer/buffer-test.c	Tue Jul  1 19:12:43 2008
@@ -13,7 +13,6 @@
  */
 
 #include "../../gegl/buffer/gegl-buffer-iterator.h"
-#include "../../gegl/buffer/gegl-buffer-linear.h"