Using script-fu-register-filter


I’m looking for a full example of using script-fu-register-filter and a fuller explanation of how to structure a script using it if possible. :slight_smile:

I’m trying out plug-in Script-fu in 2.99.14 and I read this…

You don’t specify the first two arguments “image” and “drawable”
as you do with script-fu-register in v2. Those arguments are implicit.
As a convenience, ScriptFu and GIMP registers those arguments in the PDB for you.
The run func that you define in your script
must have those formal arguments. For example:
(define script-fu-my-plugin (image drawables arg1 arg2) body)


and it confused me somewhat (I’m not a software engineer)
but it seems to say you don’t and must at the same time?
*what if I don’t need to pass an image and drawable? *

I tried using script-fu-register-filter as I understood the guide

#!/usr/bin/env gimp-script-fu-interpreter-3.0
(define (autosave image drawables) 
  (i 0)

 (while (< i 100)
  (usleep 1000000)
  (gimp-message "saving")
  (set! i (+ i 1))


(script-fu-register-filter "autosave"
 "saves every now and then" 
 "Mark Sweeney"
 "copyright 2022, Mark Sweeney, Under GNU GENERAL PUBLIC LICENSE Version 3"
(script-fu-menu-register "autosave" "<Image>/Script-Fu")

and the script fails…

/usr/bin/flatpak run --branch=beta --arch=x86_64 --command=gimp-2.99 --file-forwarding org.gimp.GIMP
Gtk-Message: 21:32:51.838: Failed to load module "xapp-gtk3-module"
This is a development version of GIMP.  Debug messages may appear here.

set device 'Virtual core XTEST pointer' to mode: disabled
set device 'PixArt USB Optical Mouse' to mode: disabled

(script-fu:113): LibGimp-CRITICAL **: 21:32:53.770: gimp_procedure_new: assertion 'gimp_is_canonical_identifier (name)' failed

(script-fu:113): LibGimp-CRITICAL **: 21:32:53.770: gimp_procedure_set_image_types: assertion 'GIMP_IS_PROCEDURE (procedure)' failed

(script-fu:113): LibGimp-CRITICAL **: 21:32:53.770: gimp_procedure_set_documentation: assertion 'GIMP_IS_PROCEDURE (procedure)' failed

(script-fu:113): LibGimp-CRITICAL **: 21:32:53.770: gimp_procedure_set_attribution: assertion 'GIMP_IS_PROCEDURE (procedure)' failed

(script-fu:113): LibGimp-CRITICAL **: 21:32:53.770: gimp_procedure_add_argument: assertion 'GIMP_IS_PROCEDURE (procedure)' failed

(script-fu:113): LibGimp-CRITICAL **: 21:32:53.770: gimp_plug_in_add_temp_procedure: assertion 'GIMP_IS_PROCEDURE (procedure)' failed

(script-fu:113): GLib-GObject-CRITICAL **: 21:32:53.770: g_object_unref: assertion 'G_IS_OBJECT (object)' failed

For expedience, I may ramble, but get back to you with an exact answer.

“filter” means the plugin at least declares itself as needing an open image and selected layer.
The plugin’s menu item won’t be enabled unless there is an open image and you have selected a layer.

Whether the plugin actually uses the image is entirely up to you the plugin author.
In your example, you aren’t.

Anyway, you don’t need to declare the image and drawables arguments in your register call,
that is, at registration time.
But when called at run-time, you will get those two arguments, to your defined Scheme function
that actually implements the plugin, often referred to as the “run-func.”
Thats what I mean by implicit, that is: not declared.
A programming language distinguishes between “declaration” and “definition.”
So DONT in the declaration, but DO in the definition.

I think the error is that the plugin must have a canonical name,
off the top of my head “script-fu-somthing”.
GIMP wasn’t that strict in v2, the name was just a convention, but now it is enforced?
I could be wrong.

Also, I can’t remember which of the strings in the registration is the name of your defined run-func,
and I think it can be different than the canonical name.

I think ts-helloworld.scm in the repo is a working example.

I can’t remember whether there is a way to declare an independent plugin that doesn’t want to declare itself a filter needing an image and layer.

I will get back to you if I mispoke about something or if you can’t make any progress.

After looking in the repo…

plug-ins/script-fu/scripts/ts-helloworld.scm is an example of an independent plugin script, but it is not a filter, it calls script-fu-register instead of script-fu-register-filter. That is, it is enabled even when an image is not open, and the arguments it declares are the arguments in its definition (e.g. no image argument)

test-sphere-v3.scm in the repo is an example of a filter. It also is independent plugin.

Being independent plugin is orthogonal to being a filter.
The shebang i.e. #! … in the first line makes it independent.
Being a filter depends on whether you call script-fu-register or script-fu-register-filter.
(More or less: you can still define what behaves as a filter using script-fu-register,
that is, script-fu-register-filter is just more convenient and less general.)

I misspoke about the strings in the declaration, the first string argument is both the name of your plugin
in the PDB and the name you must use as function name in your Scheme definition of the run-func,
at the top.
And I think its prefix must be “script-fu-” to avoid that error message.


This is what I’m understanding at the moment, regarding Script-fu in V3;

A script can now be a plug-in by putting it on a folder called the same name as the script.
plug-ins->myScript->myScript.scm and making the first line of the script the following

#!/usr/bin/env gimp-script-fu-interpreter-3.0

Also, the script doesn’t have to be saved as the same name as the main function anymore.
This all works, in my flatpak version. And it’s great to have a script be independent :slight_smile: thanks.

However, the old declaration of a script using script-fu-register has been deprecated, and may
not work at some point in the future.

The new method, to allow multiple layers to be selected and acted upon, is script-fu-register-filter


#!/usr/bin/env gimp-script-fu-interpreter-3.0
(define (script-fu-myPlugin image drawables) 

(script-fu-register-filter "script-fu-myPlugin"
 "saves active file automatically every 10 minutes" 
 "Mark Sweeney"
 "copyright 2022, Mark Sweeney, Under GNU GENERAL PUBLIC LICENSE Version 3"
 "*"  ;all image types
 SF-ONE-DRAWABLE  ;  v3  >>> additional argument for drawables parameter
(script-fu-menu-register "script-fu-myPlugin" "<Image>/Script-Fu")

I’m still confused about the “SF-ONE-DRAWABLE” declaration, why does it have to be done if the drawable is passed implicity into drawables?

(EDIT: Working now, I had forgotten to set the files to be executable.)

The new argument to script-fu-register-filter ( where in your example you pass SF-ONE-DRAWABLE)
is related to “multi-layer selection” feature of Gimp 3.

Since Gimp 3, a user can select many layers and the entire set is passed to a plugin in the “drawables” parameter, which is a container (a vector in Scheme, an array in C, a list in Python…)
Formerly, only one “drawable” was passed.

This new argument declares how many drawables the plugin is capable of actually using,
or wants.
Related to “pre-flighting” “sensitive” “enable” “user-friendliness” “arity” :
the menu item for the plugin is not enabled (instead greyed out and not clickable)
according to this argument.

Read devel-docs/GIMP3-plug-in-porting-guide/
(which is a DRAFT and talks about some things not implemented yet !!!)
(There is still time to comment, and affect what actually gets done, and with what priority.)

SF-ONE-DRAWABLE means the plugin menu item won’t be enabled unless one and only one layer is selected.
It still receives a vector, and the plugin must be written to take a vector (else it won’t work at all)
but the plugin can expect the vector has only one element (else GIMP is broken.)

As usual, I wrote this quickly, and could easily have misspoken.

Thanks, that’s got me sorted out.

The drawable needs a declaration, and its declaration can control how the user can activate
the plug-in, forcing a method of use on the user.

SF-ONE-DRAWABLE expects exactly one drawable

SF-ONE-OR-MORE-DRAWABLE expects and will process one or more drawables, typically means a script will filter the given drawables independently and sequentially.

expects and will process two or more drawables, typically means a script will
combine the given drawables, say into another drawable by a binary operation.

Putting my critical hat on, and knowing very little.

Couldn’t just the active/selected drawables by passed and leave it to the script to sort out
what to do? force the script to report incorrect use.

Its user friendliness. See any good Human Interface Guidelines (HIG) say the Apple one.
Or a book such as “About Face” by Cooper.
It is better to disable things rather than to yell at the user later.
That’s the theory anyway.
That kind of friendliness for Gimp plugins is still work in progress.

1 Like

This topic was automatically closed 45 days after the last reply. New replies are no longer allowed.