Converting the API doc to Python (original) (raw)

Posts: 6,694
Threads: 291
Joined: Oct 2016

Reputation:

590

Gimp version:

• 2.10
• 3.0

Operating system(s): Linux

04-03-2025, 09:11 AM (This post was last modified: 04-20-2025, 11:39 AM by Ofnuts.)

A little bit of C.

In C you have two kinds of data types.

• The "native" ones: int and floats of various lengths, and pointers (memory addresses)
• The "complex" ones (anything else, "structs" or arrays)

When you call a function:

• native types are passed "by value": their value is copied in the call stack
• complex types are passed "by reference": a pointer to them is copied in the calls stack. The fact that this is a pointer is indicated by *
• the function can only "return" a single native type
• the function can also update memory locations to which a pointer has been passed, this is how extra return values can be used

In addition:

• Except for constructors, in the C description the first argument of a class method is an object of the class
• When used with Python object syntax, this first argument becomes the object on which the method is called (with of course, one less argument).
• So for instance the method described in the doc as do_something(SomeClass, arg1, arg2) is called in Python as instance_of_SomeClass.do_something(arg1,arg2)

For instance with this "C" prototype from the Gimp.Drawable description:

Code:

gboolean gimp_drawable_get_offsets ( GimpDrawable* drawable, gint* offset_x, gint* offset_y )

Where GimpDrawable is a "complex" type, and gboolean and gint are "native" type (just names for machine-size integers).

* the function returns a boolean
* the first argument is a pointer/reference to GimpDrawable. Since GimpDrawable is a complex type it is a simple "input" argument.
* as stated above, since this is a method on Gimp.Drawable in python it will be called on the object which is the first argument.
* offset_x and offset_y are references to native types, and so are outputs to the function. In Python your inputs are immutable, so this is converted to extra return values, and the method returns a tuple.

So this would be called as:

boolean_success, offset_x,offset_y= get_offsets(layer: Gimp.Drawable)

But since the first argument is of the type described, in Python this method call on a Gimp.Drawable object, so it is passed implicitly when calling the method.

boolean_success, offset_x,offset_y= layer.get_offsets()

The returned boolean here is a bit artificial. This is probably because the method has to use output arguments to return X and Y, so this is the only way to check that the memory locations passed for the offsets have been updated. This can still be ignored in the vast majority of cases by writing:

_, offset_x,offset_y= layer.get_offsets()

where _ is the Python convention to indicate that you don't really care about this value.

Slightly harder:

Code:

GimpLayer* gimp_image_get_layer_by_name ( GimpImage* image, const gchar* name )

• The function takes a reference to a GimpImage, so in this case this is the implicit reference to the object on which the method is called.
• The function takes a reference to gchar. This isn't an output for a single char, this is a reference to an array of characterss (arrays and pointer are equivalent in C, an array is defined by the address of its first element). And an array of gchar is... a string. What also indicates that this is an input-only argument is the const modifier.
• The call returns a pointer to a GimpLayer, so in Python, a plain Gimp.Layer

So this defines a Gimp.Image method that would be type-hinted as:

def get_layer_by_name(name: str) -> Gimp.Layer

Raising the bar:

Code:

GimpLayer ** gimp_image_get_selected_layers ( GimpImage* image )

Here the call return a pointer to a pointer to GimpLayer... this is really a pointer to an array of GimpLayer, so for Python just a list of Gimp.Layer. So this is just:

def get_selected_layers() -> list[Gimp.Layer]

Gotcha:

Note that some calls are defined as functions and not as object methods. For instance:

Code:

gboolean gimp_file_save ( GimpRunMode run_mode, GimpImage* image, GFile* file, GimpExportOptions* options )

This is a plain function in the Gimp namespace that takes 4 explicit arguments.