[gimp] libgimp: document which context settings affect the new transform API

[Michael Natterer <mitch src gnome org>]

commit b33076bea51ce0503f33c2723259b7e1fa082e10
Author: Michael Natterer <mitch gimp org>
Date:   Fri Feb 11 21:15:31 2011 +0100

    libgimp: document which context settings affect the new transform API

 app/pdb/item-transform-cmds.c       |   18 ++++++------
 libgimp/gimpitemtransform_pdb.c     |   49 ++++++++++++++++++++++++++++------
 tools/pdbgen/pdb/item_transform.pdb |   34 ++++++++++++++++++++++++
 3 files changed, 83 insertions(+), 18 deletions(-)
---
diff --git a/app/pdb/item-transform-cmds.c b/app/pdb/item-transform-cmds.c
index 65badea..0ab4992 100644
--- a/app/pdb/item-transform-cmds.c
+++ b/app/pdb/item-transform-cmds.c
@@ -851,7 +851,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-flip-simple",
                                      "Flip the specified item either vertically or horizontally.",
-                                     "This procedure flips the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then flipped. If auto_center is set to TRUE, the flip is around the selection's center. Otherwise, the coordinate of the axis needs to be specified. The return value is the ID of the flipped item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and flipped drawable.",
+                                     "This procedure flips the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then flipped. If auto_center is set to TRUE, the flip is around the selection's center. Otherwise, the coordinate of the axis needs to be specified. The return value is the ID of the flipped item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and flipped drawable. This prodecure is affected by the following context setters: 'gimp-context-set-transform-resize'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2004",
@@ -901,7 +901,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-flip",
                                      "Flip the specified item around a given line.",
-                                     "This procedure flips the specified item. If a selection exists and the item is a drawable , the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then flipped. The axis to flip around is specified by specifying two points from that line. The return value is the ID of the flipped item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and flipped drawable.",
+                                     "This procedure flips the specified item. If a selection exists and the item is a drawable , the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then flipped. The axis to flip around is specified by specifying two points from that line. The return value is the ID of the flipped item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and flipped drawable. This prodecure is affected by the following context setters: 'gimp-context-set-interpolation', 'gimp-context-set-transform-direction', 'gimp-context-set-transform-resize', 'gimp-context-set-transform-recursion'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
@@ -955,7 +955,7 @@ register_item_transform_procs (GimpPDB *pdb)
                                      "gimp-item-transform-perspective",
                                      "Perform a possibly non-affine transformation on the specified item.",
                                      "This procedure performs a possibly non-affine transformation on the specified item by allowing the corners of the original bounding box to be arbitrarily remapped to any values. The specified item is remapped if no selection exists or it is not a drawable. However, if a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then remapped as specified. The return value is the ID of the remapped item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and remapped drawable. The 4 coordinates specify the new locations of each corner of the original bounding box. By specifying these values, any affine transformation (rotation, scaling, translation) can be affected. Additionally, these values can be specified such that the resu
 lting transformed item will appear to have"
-  "been projected via a perspective transform.",
+  "been projected via a perspective transform. This prodecure is affected by the following context setters: 'gimp-context-set-interpolation', 'gimp-context-set-transform-direction', 'gimp-context-set-transform-resize', 'gimp-context-set-transform-recursion'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
@@ -1032,7 +1032,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-rotate-simple",
                                      "Rotate the specified item about given coordinates through the specified angle.",
-                                     "This function rotates the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then rotated by the specified amount. The return value is the ID of the rotated item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and rotated drawable.",
+                                     "This function rotates the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then rotated by the specified amount. The return value is the ID of the rotated item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and rotated drawable. This prodecure is affected by the following context setters: 'gimp-context-set-transform-resize'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
@@ -1086,7 +1086,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-rotate",
                                      "Rotate the specified item about given coordinates through the specified angle.",
-                                     "This function rotates the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then rotated by the specified amount. The return value is the ID of the rotated item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and rotated drawable.",
+                                     "This function rotates the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then rotated by the specified amount. The return value is the ID of the rotated item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and rotated drawable. This prodecure is affected by the following context setters: 'gimp-context-set-interpolation', 'gimp-context-set-transform-direction', 'gimp-context-set-transform-resize', 'gimp-context-set-transform-recursion'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
@@ -1139,7 +1139,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-scale",
                                      "Scale the specified item.",
-                                     "This procedure scales the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then scaled by the specified amount. The return value is the ID of the scaled item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and scaled drawable.",
+                                     "This procedure scales the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then scaled by the specified amount. The return value is the ID of the scaled item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and scaled drawable. This prodecure is affected by the following context setters: 'gimp-context-set-interpolation', 'gimp-context-set-transform-direction', 'gimp-context-set-transform-resize', 'gimp-context-set-transform-recursion'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
@@ -1192,7 +1192,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-shear",
                                      "Shear the specified item about its center by the specified magnitude.",
-                                     "This procedure shears the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then sheard by the specified amount. The return value is the ID of the sheard item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and sheard drawable. The shear type parameter indicates whether the shear will be applied horizontally or vertically. The magnitude can be either positive or negative and indicates the extent (in pixels) to shear by.",
+                                     "This procedure shears the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then sheard by the specified amount. The return value is the ID of the sheard item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and sheard drawable. The shear type parameter indicates whether the shear will be applied horizontally or vertically. The magnitude can be either positive or negative and indicates the extent (in pixels) to shear by. This prodecure is affected by the following context setters: 'gimp-context-set-interpolation', 'gimp-context-set-transform-direction', 'gimp-context-set-transform-resize', 'gimp-context-set-transform-recursion'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
@@ -1236,7 +1236,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-2d",
                                      "Transform the specified item in 2d.",
-                                     "This procedure transforms the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then transformed. The transformation is done by scaling the image by the x and y scale factors about the point (source_x, source_y), then rotating around the same point, then translating that point to the new position (dest_x, dest_y). The return value is the ID of the rotated drawable. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and transformed drawable.",
+                                     "This procedure transforms the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then transformed. The transformation is done by scaling the image by the x and y scale factors about the point (source_x, source_y), then rotating around the same point, then translating that point to the new position (dest_x, dest_y). The return value is the ID of the rotated drawable. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and transformed drawable. This prodecure is affected by the following context setters: 'gimp-context-set-interpolation', 'gimp-context-set-transform-direction', 'gimp-context-set-transform-resize', 'gimp-context-set-transform-recursion'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
@@ -1307,7 +1307,7 @@ register_item_transform_procs (GimpPDB *pdb)
   gimp_procedure_set_static_strings (procedure,
                                      "gimp-item-transform-matrix",
                                      "Transform the specified item in 2d.",
-                                     "This procedure transforms the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then transformed. The transformation is done by assembling a 3x3 matrix from the coefficients passed. The return value is the ID of the transformed item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and transformed drawable.",
+                                     "This procedure transforms the specified item. If a selection exists and the item is a drawable, the portion of the drawable which lies under the selection is cut from the drawable and made into a floating selection which is then transformed. The transformation is done by assembling a 3x3 matrix from the coefficients passed. The return value is the ID of the transformed item. If there was no selection or the item is not a drawable, this will be equal to the item ID supplied as input. Otherwise, this will be the newly created and transformed drawable. This prodecure is affected by the following context setters: 'gimp-context-set-interpolation', 'gimp-context-set-transform-direction', 'gimp-context-set-transform-resize', 'gimp-context-set-transform-recursion'.",
                                      "Michael Natterer <mitch gimp org>",
                                      "Michael Natterer",
                                      "2010",
diff --git a/libgimp/gimpitemtransform_pdb.c b/libgimp/gimpitemtransform_pdb.c
index 4686562..a5e5bed 100644
--- a/libgimp/gimpitemtransform_pdb.c
+++ b/libgimp/gimpitemtransform_pdb.c
@@ -51,7 +51,9 @@
  * the axis needs to be specified. The return value is the ID of the
  * flipped item. If there was no selection or the item is not a
  * drawable, this will be equal to the item ID supplied as input.
- * Otherwise, this will be the newly created and flipped drawable.
+ * Otherwise, this will be the newly created and flipped drawable. This
+ * prodecure is affected by the following context setters:
+ * gimp_context_set_transform_resize().
  *
  * Returns: The flipped item.
  *
@@ -101,7 +103,11 @@ gimp_item_transform_flip_simple (gint32              item_ID,
  * is the ID of the flipped item. If there was no selection or the item
  * is not a drawable, this will be equal to the item ID supplied as
  * input. Otherwise, this will be the newly created and flipped
- * drawable.
+ * drawable. This prodecure is affected by the following context
+ * setters: gimp_context_set_interpolation(),
+ * gimp_context_set_transform_direction(),
+ * gimp_context_set_transform_resize(),
+ * gimp_context_set_transform_recursion().
  *
  * Returns: The flipped item.
  *
@@ -164,7 +170,11 @@ gimp_item_transform_flip (gint32  item_ID,
  * values, any affine transformation (rotation, scaling, translation)
  * can be affected. Additionally, these values can be specified such
  * that the resulting transformed item will appear to have been
- * projected via a perspective transform.
+ * projected via a perspective transform. This prodecure is affected by
+ * the following context setters: gimp_context_set_interpolation(),
+ * gimp_context_set_transform_direction(),
+ * gimp_context_set_transform_resize(),
+ * gimp_context_set_transform_recursion().
  *
  * Returns: The newly mapped item.
  *
@@ -224,7 +234,8 @@ gimp_item_transform_perspective (gint32  item_ID,
  * value is the ID of the rotated item. If there was no selection or
  * the item is not a drawable, this will be equal to the item ID
  * supplied as input. Otherwise, this will be the newly created and
- * rotated drawable.
+ * rotated drawable. This prodecure is affected by the following
+ * context setters: gimp_context_set_transform_resize().
  *
  * Returns: The rotated item.
  *
@@ -276,7 +287,11 @@ gimp_item_transform_rotate_simple (gint32           item_ID,
  * value is the ID of the rotated item. If there was no selection or
  * the item is not a drawable, this will be equal to the item ID
  * supplied as input. Otherwise, this will be the newly created and
- * rotated drawable.
+ * rotated drawable. This prodecure is affected by the following
+ * context setters: gimp_context_set_interpolation(),
+ * gimp_context_set_transform_direction(),
+ * gimp_context_set_transform_resize(),
+ * gimp_context_set_transform_recursion().
  *
  * Returns: The rotated item.
  *
@@ -327,7 +342,11 @@ gimp_item_transform_rotate (gint32   item_ID,
  * value is the ID of the scaled item. If there was no selection or the
  * item is not a drawable, this will be equal to the item ID supplied
  * as input. Otherwise, this will be the newly created and scaled
- * drawable.
+ * drawable. This prodecure is affected by the following context
+ * setters: gimp_context_set_interpolation(),
+ * gimp_context_set_transform_direction(),
+ * gimp_context_set_transform_resize(),
+ * gimp_context_set_transform_recursion().
  *
  * Returns: The scaled item.
  *
@@ -380,7 +399,11 @@ gimp_item_transform_scale (gint32  item_ID,
  * drawable. The shear type parameter indicates whether the shear will
  * be applied horizontally or vertically. The magnitude can be either
  * positive or negative and indicates the extent (in pixels) to shear
- * by.
+ * by. This prodecure is affected by the following context setters:
+ * gimp_context_set_interpolation(),
+ * gimp_context_set_transform_direction(),
+ * gimp_context_set_transform_resize(),
+ * gimp_context_set_transform_recursion().
  *
  * Returns: The sheared item.
  *
@@ -433,7 +456,11 @@ gimp_item_transform_shear (gint32              item_ID,
  * The return value is the ID of the rotated drawable. If there was no
  * selection or the item is not a drawable, this will be equal to the
  * item ID supplied as input. Otherwise, this will be the newly created
- * and transformed drawable.
+ * and transformed drawable. This prodecure is affected by the
+ * following context setters: gimp_context_set_interpolation(),
+ * gimp_context_set_transform_direction(),
+ * gimp_context_set_transform_resize(),
+ * gimp_context_set_transform_recursion().
  *
  * Returns: The transformed item.
  *
@@ -496,7 +523,11 @@ gimp_item_transform_2d (gint32  item_ID,
  * return value is the ID of the transformed item. If there was no
  * selection or the item is not a drawable, this will be equal to the
  * item ID supplied as input. Otherwise, this will be the newly created
- * and transformed drawable.
+ * and transformed drawable. This prodecure is affected by the
+ * following context setters: gimp_context_set_interpolation(),
+ * gimp_context_set_transform_direction(),
+ * gimp_context_set_transform_resize(),
+ * gimp_context_set_transform_recursion().
  *
  * Returns: The transformed item.
  *
diff --git a/tools/pdbgen/pdb/item_transform.pdb b/tools/pdbgen/pdb/item_transform.pdb
index 831436d..20ec691 100644
--- a/tools/pdbgen/pdb/item_transform.pdb
+++ b/tools/pdbgen/pdb/item_transform.pdb
@@ -104,6 +104,9 @@ needs to be specified. The return value is the ID of the flipped
 item. If there was no selection or the item is not a drawable, this
 will be equal to the item ID supplied as input.  Otherwise, this will
 be the newly created and flipped drawable.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_transform_resize().
 HELP
 
     &mitch_pdb_misc('2004', '2.2');
@@ -185,6 +188,10 @@ specifying two points from that line. The return value is the ID of
 the flipped item. If there was no selection or the item is not a
 drawable, this will be equal to the item ID supplied as input.
 Otherwise, this will be the newly created and flipped drawable.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_interpolation(), gimp_context_set_transform_direction(),
+gimp_context_set_transform_resize(), gimp_context_set_transform_recursion().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');
@@ -236,6 +243,10 @@ these values, any affine transformation (rotation, scaling,
 translation) can be affected. Additionally, these values can be
 specified such that the resulting transformed item will appear to
 have been projected via a perspective transform.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_interpolation(), gimp_context_set_transform_direction(),
+gimp_context_set_transform_resize(), gimp_context_set_transform_recursion().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');
@@ -297,6 +308,9 @@ selection which is then rotated by the specified amount. The return
 value is the ID of the rotated item. If there was no selection or the
 item is not a drawable, this will be equal to the item ID supplied as
 input. Otherwise, this will be the newly created and rotated drawable.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_transform_resize().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');
@@ -382,6 +396,10 @@ selection which is then rotated by the specified amount. The return
 value is the ID of the rotated item. If there was no selection or the
 item is not a drawable, this will be equal to the item ID supplied as
 input. Otherwise, this will be the newly created and rotated drawable.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_interpolation(), gimp_context_set_transform_direction(),
+gimp_context_set_transform_resize(), gimp_context_set_transform_recursion().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');
@@ -427,6 +445,10 @@ selection which is then scaled by the specified amount. The return
 value is the ID of the scaled item. If there was no selection or the
 item is not a drawable, this will be equal to the item ID supplied as
 input. Otherwise, this will be the newly created and scaled drawable.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_interpolation(), gimp_context_set_transform_direction(),
+gimp_context_set_transform_resize(), gimp_context_set_transform_recursion().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');
@@ -478,6 +500,10 @@ input. Otherwise, this will be the newly created and sheard
 drawable. The shear type parameter indicates whether the shear will be
 applied horizontally or vertically. The magnitude can be either
 positive or negative and indicates the extent (in pixels) to shear by.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_interpolation(), gimp_context_set_transform_direction(),
+gimp_context_set_transform_resize(), gimp_context_set_transform_recursion().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');
@@ -521,6 +547,10 @@ return value is the ID of the rotated drawable. If there was no
 selection or the item is not a drawable, this will be equal to the
 item ID supplied as input. Otherwise, this will be the newly created
 and transformed drawable.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_interpolation(), gimp_context_set_transform_direction(),
+gimp_context_set_transform_resize(), gimp_context_set_transform_recursion().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');
@@ -572,6 +602,10 @@ value is the ID of the transformed item. If there was no selection or
 the item is not a drawable, this will be equal to the item ID supplied
 as input. Otherwise, this will be the newly created and transformed
 drawable.
+
+This prodecure is affected by the following context setters:
+gimp_context_set_interpolation(), gimp_context_set_transform_direction(),
+gimp_context_set_transform_resize(), gimp_context_set_transform_recursion().
 HELP
 
     &mitch_pdb_misc('2010', '2.8');