From 1c537b0cfd300e2976e2a5bd50a08bcdcccd30a0 Mon Sep 17 00:00:00 2001 From: lloyd konneker Date: Tue, 4 May 2021 11:54:31 -0400 Subject: [PATCH] Add devel doc --- .../porting_scriptfu_scripts.md | 158 ++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 devel-docs/GIMP3-plug-in-porting-guide/porting_scriptfu_scripts.md diff --git a/devel-docs/GIMP3-plug-in-porting-guide/porting_scriptfu_scripts.md b/devel-docs/GIMP3-plug-in-porting-guide/porting_scriptfu_scripts.md new file mode 100644 index 0000000000..8907059784 --- /dev/null +++ b/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.