Add devel doc

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

@@ -0,0 +1,158 @@
+
+
+## About this document
+
+This describes *some* changes needed to port a Scriptfu script to GIMP 3:
+- changes in types
+- changes in PDB signatures for multi-layer support
+- changes in error messages
+- changes in logging
+
+It does *not* document:
+- PDB procedures whose names have changed (see pdb-calls.md)
+- PDB procedures that have been removed (see removed_functions.md)
+- PDB procedures that have been added
+- other changes in signature where arguments are reordered or changed in number
+
+## Changes in types of PDB signatures
+
+Calls from a script to GIMP are calls to PDB procedures.
+PDB procedures are documented in terms of C and GLib types.
+
+This table summarizes the changes:
+
+| Purpose        | Old C type            | New C type            | Old Scheme type | New Scheme type       |
+| ---------------|-----------------------|-----------------------| ----------------|-----------------------|
+| Pass file name | gchar*, gchar*        | GFile                 | string string   | string                |
+| Recv file name | gchar*                | GFile                 | string          | string                |
+| pass drawable  | GimpDrawable          | gint, GimpObjectArray | int   (an ID)   | int (a length) vector |
+| Pass obj array | gint, GimpInt32Array  | gint, GimpObjectArray | int  vector     | int vector            |
+| Recv obj array | gint, GimpInt32Array  | gint, GimpObjectArray | int  vector     | int vector            |
+
+(Where "obj" means an object of a GIMP type such as GimpDrawable or similar.)
+
+### Use one string for a filename instead of two.
+
+Formerly a PDB procedure taking a filename (usually a full path) required two strings (two gchar* .)
+Now such PDB procedures require a GFile.
+
+In Scheme, where formerly you passed two strings, now pass one string.
+
+Formerly a script passed the second string for a URI, to specify a remote file.
+Formerly, in most cases you passed an empty second string.
+Now, the single string in a script can be either a local file path or a remote URI.
+
+Example:
+
+(gimp-file-load RUN-NONINTERACTIVE "/tmp/foo" "")
+=> (gimp-file-load RUN-NONINTERACTIVE "/tmp/foo")
+
+
+### PDB procedures still return a string for a filename
+
+All PDB procedures returning a filename return a single string to Scheme scripts.
+That is unchanged.
+
+Formerly a PDB signature for a procedure returning a filename
+specifies a returned type gchar*, but now specifies a returned type GFile.
+But a Scheme script continues to receive a string.
+
+The returned string is either a local file path or a URI.
+
+
+### Use a vector of drawables for PDB procedures that now take an array of drawables
+
+Formerly, some PDB procedures took a single GimpDrawable,
+but now they take an array of GimpDrawable ( type GimpObjectArray.)
+(Formerly, no PDB procedure took an array of drawables.
+Some that formerly took a single drawable still take a single drawable.
+See the list below. )
+
+For such PDB procedures, in Scheme pass a numeric length and a vector of numeric drawable ID's.
+
+These changes support a user selecting multiple layers for an operation.
+
+Example:
+
+(gimp-edit-copy drawable)  => (gimp-edit-copy 1 (vector drawable))
+
+(gimp-edit-copy 2)  => (gimp-edit-copy 1 '#(2))
+
+### The PDB procedures which formerly took single Drawable and now take GimpObjectArray
+
+- Many of the file load/save procedures.
+- gimp-color-picker
+- gimp-edit-copy
+- gimp-edit-cut
+- gimp-edit-named-copy
+- gimp-edit-named-cut
+- gimp-file-save
+- gimp-image-pick-color
+- gimp-selection-float
+- gimp-xcf-save
+
+
+### Receiving an array of drawables
+
+Formerly a PDB procedure returning an array of drawables (or other GIMP objects)
+had a signature specifying a returned gint and GimpInt32Array.
+Now the signature specifies a returned gint and GimpObjectArray.
+A script receives an int and a vector.
+The elements of the vector are numeric ID's,
+but are opaque to scripts
+(a script can pass them around, but should not for example use arithmetic on them.)
+
+No changes are needed to a script.
+
+
+Example:
+
+(gimp-image-get-layers image)
+
+Will return a list whose first element is a length,
+and whose second element is a vector of drawables (Scheme numerics for drawable ID's)
+
+In the ScriptFu console,
+
+(gimp-image-get-layers (car (gimp-image-new 10 30 1)))
+
+would print:
+
+(0 #())
+
+Meaning a list length of zero, and an empty vector.
+(Since a new image has no layers.)
+
+
+## Changes in error messages
+
+ScriptFu is now more forgiving.
+
+Formerly, ScriptFu would not accept a call construct where the argument count was wrong,
+except for the case when you provided one argument to a PDB procedure
+that took zero arguments (sometimes called a nullary function.)
+
+Now, when a script has the wrong count of arguments to a PDB procedure:
+
+- too many actual arguments: ScriptFu will give a warning to the console
+  and call the PDB procedure with a prefix of the actual arguments.
+  This is now true no matter how many arguments the PDB procedure takes.
+  Extra arguments in the script are ignored by Scriptfu,
+  not evaluated and not passed to the PDB.
+
+- too few actual arguments: ScriptFu will give a warning to the console
+  and call the PDB procedure with the given actual arguments.
+  The warning will say the expected Scheme formal type of the first missing actual argument.
+  Usually the PDB procedure will fail and return its own error message.
+
+When you suspect errors in a script,
+it is now important to run GIMP from a console to see warnings.
+
+
+## ScriptFu logging
+
+ScriptFu now does some logging using GLib logging.
+When you define in the environment "G_MESSAGES_DEBUG=scriptfu"
+ScriptFu will print many messages to the console.
+
+This is mostly useful for GIMP developers.