Add some new files to the GIMP3-plug-in-porting-guide, including a README

devel-docs/GIMP3-plug-in-porting-guide/README.md

@@ -0,0 +1,15 @@
+Here you'll find documentation useful for porting older GIMP
+plug-ins, especially Python ones, to the GIMP 3.0 APIs.
+
+Files:
+
+- [classes.md:](classes.md)
+  A list of some of the important classes and modules in GIMP 3.0.
+
+- [pdb-calls.md:](pdb-calls.md)
+  An incomplete list of old PDB functions and their equivalents,
+  using Python classes.
+
+- [removed_functions.md:](removed_functions.md)
+  Functions that have been removed from GIMP, and their replacements.
+

devel-docs/GIMP3-plug-in-porting-guide/classes.md

@@ -0,0 +1,100 @@
+# Useful Modules/Classes in GIMP 3.0+
+
+Here's a guide to the modules you're likely to need.
+It's a work in progress: feel free to add to it.
+
+Eventually we'll have online documentation for these classes.
+In the meantime, you can generate your own:
+```
+HTMLDOCDIR=/path/to/doc/dir
+g-ir-doc-tool -I /path/to/share/gir-1.0/ --language=Python -o $HTMLDOCDIR Gimp-3.0.gir
+```
+Then browse $HTMLDOCDIR with yelp, or generate HTML from it:
+```
+cd $HTMLDOCDIR
+yelp-build cache *.page
+yelp-build html .
+
+```
+
+You can also get some information in GIMP's Python console with
+*help(module)* or *help(object)*, and you can get a list of functions
+with *dir(object)*.
+
+## Gimp
+
+The base module: almost everything is under Gimp.
+
+## Gimp.Image
+
+The image object.
+
+Some operations that used to be PDB calls, like
+```
+pdb.gimp_selection_layer_alpha(layer)
+```
+are now in the Image object, e.g.
+```
+img.select_item(Gimp.ChannelOps.REPLACE, layer)
+```
+
+## Gimp.Layer
+
+The layer object.
+
+```
+fog = Gimp.Layer.new(image, name,
+                     drawable.width(), drawable.height(), type, opacity,
+                     Gimp.LayerMode.NORMAL)
+```
+
+## Gimp.Selection
+
+Selection operations that used to be in the PDB, e.g.
+```
+pdb.gimp_selection_none(img)
+```
+are now in the Gimp.Selection module, e.g.
+```
+Gimp.Selection.none(img)
+```
+
+## Gimp.ImageType
+
+A home for image types like RGBA, GRAY, etc:
+```
+Gimp.ImageType.RGBA_IMAGE
+```
+
+## Gimp.FillType
+
+e.g. Gimp.FillType.TRANSPARENT, Gimp.FillType.BACKGROUND
+
+## Gimp.ChannelOps
+
+The old channel op definitions in the gimpfu module, like
+```
+CHANNEL_OP_REPLACE
+```
+are now in their own module:
+
+```
+Gimp.ChannelOps.REPLACE
+```
+
+## Gimp.RGB
+
+In legacy plug-ins you could pass a simple list of integers, like (0, 0, 0).
+In 3.0+, create a Gimp.RGB object:
+
+```
+    c = Gimp.RGB()
+    c.set(240.0, 180.0, 70.0)
+```
+or
+```
+    c.r = 0
+    c.g = 0
+    c.b = 0
+    c.a = 1
+```

devel-docs/GIMP3-plug-in-porting-guide/pdb-calls.md

@@ -0,0 +1,76 @@
+# PDB equivalence
+
+A table of old PDB calls, and their equivalents in the GIMP 3.0+ world.
+
+This document is a work in progress. Feel free to add to it.
+
+## Undo/Context
+
+| Removed function                 | Replacement                   |
+| -------------------------------- | ----------------------------
+| gimp_undo_push_group_start       | image.undo_group_start() |
+| gimp_undo_push_group_end         | image.undo_group_end() |
+| gimp.context_push()              | Gimp.context_push()   |
+| gimp.context_push()              | Gimp.context_push()   |
+| gimp_context_get_background      | Gimp.context_get_background
+| gimp_context_set_background      | Gimp.context_set_background
+
+## File load/save
+
+| Removed function                 | Replacement                   |
+| -------------------------------- | ----------------------------
+| gimp_file_load                   | Gimp.file_load |
+| gimp_file_save                   | Gimp.file_save |
+
+## Selection operations
+
+Selection operations are now in the Gimp.Selection class (except
+a few in the Image class). E.g.
+
+| Removed function                 | Replacement                   |
+| -------------------------------- | ----------------------------
+| pdb.gimp_selection_invert(img)   | Gimp.Selection.invert(img) |
+| pdb.gimp_selection_none(img)     | Gimp.Selection.none(img) |
+| pdb.gimp_selection_layer_alpha(layer) | img.select_item(Gimp.ChannelOps.REPLACE, layer) |
+| gimp_image_select_item           | img.select_item(channel_op, layer) |
+
+## Filling and Masks
+
+| Removed function                 | Replacement                   |
+| -------------------------------- | ----------------------------
+| Gimp.drawable_fill()             | layer.fill() |
+| pdb.gimp_edit_fill(FILL_BACKGROUND)  | layer.edit_fill(Gimp.FillType.BACKGROUND) |
+| gimp_layer_add_mask              | layer.add_mask
+| gimp_layer_remove_mask           | layer.remove_mask
+
+## Miscellaneous and Non-PDB Calls
+
+| Removed function                 | Replacement                   |
+| -------------------------------- | ----------------------------
+| gimp_displays_flush              | Gimp.displays_flush
+| gimp_image_insert_layer          | image.insert_layer
+
+
+## Plug-ins
+
+Calling other plug-ins is trickier than before. The old
+```
+pdb.script_fu_drop_shadow(img, layer, -3, -3, blur,
+                              (0, 0, 0), 80.0, False)
+```
+becomes
+```
+        c = Gimp.RGB()
+        c.set(240.0, 180.0, 70.0)
+        Gimp.get_pdb().run_procedure('script-fu-drop-shadow',
+                                     [ Gimp.RunMode.NONINTERACTIVE,
+                                       GObject.Value(Gimp.Image, img),
+                                       GObject.Value(Gimp.Drawable, layer),
+                                       GObject.Value(GObject.TYPE_DOUBLE, -3),
+                                       GObject.Value(GObject.TYPE_DOUBLE, -3),
+                                       GObject.Value(GObject.TYPE_DOUBLE,blur),
+                                       c,
+                                       GObject.Value(GObject.TYPE_DOUBLE, 80.0),
+                                       GObject.Value(GObject.TYPE_BOOLEAN, False)
+                                     ])
+```