[gegl/abyss: 13/22] docs: added a short explanation of abyss policy

[Ville Sokk <villesokk src gnome org>]

commit 23851e30f53a58dc61fe59f7402c0642a4f1b035
Author: Ville Sokk <ville sokk gmail com>
Date:   Fri Jun 29 12:45:01 2012 +0300

    docs: added a short explanation of abyss policy

 docs/abyss_policy.txt |   23 +++++++++++++++++++++++
 1 files changed, 23 insertions(+), 0 deletions(-)
---
diff --git a/docs/abyss_policy.txt b/docs/abyss_policy.txt
new file mode 100644
index 0000000..e1e862b
--- /dev/null
+++ b/docs/abyss_policy.txt
@@ -0,0 +1,23 @@
+gegl_buffer_get and gegl_buffer_set are the functions to read and
+write pixels in a GeglBuffer. They both take an array of pixels and
+write/read data from tiles according to the region of interest.
+
+Abyss is a rectangle that defines what area of the buffer is
+readable. Abyss policy determines how to read pixels when the
+requested region of interest (or pixel) is not contained within the
+abyss. Abyss policy only affects reading and not writing of pixels and
+does so when gegl_buffer_get is called. Each policy has a separate
+iterator function that reads data to the array. If the region of
+interest is inside the abyss rectangle a simple read function is used
+to avoid the overhead of dealing with abyss. Abyss policy also affects
+samplers since they use gegl_bufer_get.
+
+There are 5 abyss policies represented by the following enums
+GEGL_ABYSS_NONE - abyss pixels are zeroed
+GEGL_ABYSS_WHITE - abyss pixels are white
+GEGL_ABYSS_BLACK - abyss pixels are black
+GEGL_ABYSS_CLAMP - each pixel's coordinates are clamped to the abyss
+rectangle
+GEGL_ABYSS_LOOP - each pixel's coordinates wrap when exceeding the
+abyss rectangle (the buffer is essentially tiled)
+