After going through gegl.h and hello-world.c, these are my opinions.

1. The order of the parameters to gegl_node_connect should be reversed, that is, it should be

gboolean *gegl_node_connect* (GeglNode *source, *const* gchar *output_pad_name, GeglNode *sink, *const* gchar *input_pad_name);

This is the order used in gegl_node_link, and personally I prefer to write 'from to' rather than 'to from'. In any case, the order of the parameters should be the same throughout the API. 2. The term "bounding box" is clearer than "defined region". So

*gegl_node_get_bounding_box *

would be better than

gegl_node_get_defined_rect

- Martin Nordholts

The host facing GEGL API is getting closer to a stage where it should be scrutinized before an initial tarball release. The API that is getting stable is the host facing API, which is the portions of the GEGL library exposed in gegl.h[1]. Usage of this API is illustrated in the hello world example[2] in the documentation.

1: http://cvs.gnome.org/viewcvs/gegl/gegl/gegl.h?view=markup 2: http://cvs.gnome.org/viewcvs/gegl/docs/hello-world.c?view=markup

Comments and requests for renaming/clarification of this API would be most welcome, the API to write plug-ins as well as the XML serialization format are still not ready to be stabilized. But the public API should be possible to keep largely unchanged whilst adding optimizations internally in the GEGL engine.

Right now I think there is two issues that needs resolving, the most important one is probably exposing introspection of meta data/properties for operations. The
current function GSList * gegl_operation_list_operations (void); which returns a static list of operation names is not good enough. To discover the parameters a temporary GeglNode needs to be instantiated and it's list of properties must be examined. I want to avoid exposing the GObject internals of GEGL in the public API.

The other issue is hit detection, this is a more minor issue, and I think introducing API to do this can be postponed until later, but most probably adding a function similar to the following would work:

GeglNode *gegl_node_hit_test (GeglNode *node, gint x, gint y, gdouble alpha_threshold);

As part of exercising the API some additional GUI integration code has also been written, most importantly GeglProjection a cache/queue for rendered output from a node (which probably will be reused internally in GEGL for caching) and GeglView a GtkWidget for viewing/requesting renderings from a projection. GeglView together with some other convenience code for using GEGL from GTK+ will probably be wrapped up in a helper GUI library.

/Øyvind K.

Øyvind Kolås skrev:

On 12/2/06, Martin Nordholts wrote:

After going through gegl.h and hello-world.c, these are my opinions.

1. The order of the parameters to gegl_node_connect should be reversed, that is, it should be

gboolean *gegl_node_connect* (GeglNode *source, *const* gchar *output_pad_name,
GeglNode *sink, *const* gchar *input_pad_name);

This is the order used in gegl_node_link, and personally I prefer to write 'from to' rather than 'to from'. In any case, the order of the parameters should be the same throughout the API.

I agree that all of them should behave the same. The gegl_node_link (_many) functions are syntactic sugar on top of this one, and should maybe be removed.

Maybe the verb should be changed as well, the rationale for the current name is that you connect to the input pad of the object being modified (and it feels natural that the first object is the one being modified.)

perhaps gegl_node_connect_to (source_node, source_pad, destination_node, destination_pad) or some other name could be used.

Ah yes, you are right, it makes much more sense to pass 'self' first, instead of 'from to'. This aspect completely slipped my mind. A node class method for connecting must be in the public API.

Wouldn't connect_from be a more logical name than connect_to? In code, you would write "the input pad of this (self) node should be connected *from* the output pad of the other (source) node'.

If the syntactic sugar functions are kept, I don't think they should start with gegl_node_, since that implies that they are class methods and hence one expects that 'self' should be passed as the first argument.

However, the need for these helper functions can indeed be questioned. For hard-coded demonstration programs they are useful, but I find it difficult to imagine when they would be useful in, say, the next GIMP. There you would have some algorithm that dynamically link nodes together based on the current structure of the layers and their blend modes etc in an image.

2. The term "bounding box" is clearer than "defined region". So

gegl_node_get_bounding_box

I also agree that this needs changing, and the suggested name is a lot better than the current one.

The names of the concept internally, and a decision externally might be propagated to the inside as well. Another option might be gegl_node_get_bounds , or with a naming choice more similar to the ones used by cairo, gegl_node_get_extents.

/Øyvind K.

I think _get_extents is a feasible alternative to _get_defined_region, but I prefer 'bounding box', probably because that is the term I am more familiar with.

- Martin Nordholts

On 12/4/06, Øyvind Kolås wrote:

2. The term "bounding box" is clearer than "defined region". > *gegl_node_get_bounding_box

The names of the concept internally, and a decision externally might be propagated to the inside as well. Another option might be gegl_node_get_bounds , or with a naming choice more similar to the ones used by cairo, gegl_node_get_extents.

I've renamed this one to gegl_node_get_bounding_box for now, I think gegl_node_get_dirty_rect should be renamed to be more similar to gegl_node_get_bounding_box.

I like

gegl_node_get_bounding_box gegl_node_get_bounding_box_of_dirt
gegl_node_clear_dirt

the most.

I think dirt is a good word, at least better than uncomputed. It both makes sense and is easier to write.

- Martin N.

Just a note, I think the public gegl.h should contain no abbreviations, for instance would

gegl_node_blit_bufffer

be better than

gegl_node_blit_buf,

and 'roi' should be changed to 'region_of_interest'.

- Martin N.

On 12/4/06, Martin Nordholts wrote:

perhaps gegl_node_connect_to (source_node, source_pad, destination_node, destination_pad) or some other name could be used.

Ah yes, you are right, it makes much more sense to pass 'self' first, instead of 'from to'. This aspect completely slipped my mind. A node class method for connecting must be in the public API.

Wouldn't connect_from be a more logical name than connect_to? In code, you would write "the input pad of this (self) node should be connected *from* the output pad of the other (source) node'.

I still want the behavior you initially wanted, perhaps gegl_node_attach_to
is a good name for a class method with that behavior.

gegl_node_connect_to is much better. Why would we want to have two terms for the same thing? The code for it would be

gboolean gegl_node_connect_to (GeglNode *self, const gchar *source_pad_name, GeglNode *sink, const gchar *sink_pad_name) {
return gegl_node_connect_from (sink, sink_pad_name, self, source_pad_name);
}

If the syntactic sugar functions are kept, I don't think they should start with gegl_node_, since that implies that they are class methods and hence one expects that 'self' should be passed as the first argument.

This is not a problem, one creates a linked chain starting from "self" and onwards.

Ah yes, silly me.

However, the need for these helper functions can indeed be questioned. For hard-coded demonstration programs they are useful, but I find it difficult to imagine when they would be useful in, say, the next GIMP. There you would have some algorithm that dynamically link nodes together based on the current structure of the layers and their blend modes etc in an image.

Most probably not dynamically, but keeping a graph in sync with the other data structures. And encouraging such functions existence in python|ruby etc variations of the bindings will make coding with GEGL a bit more pleasant.

Ah yes, good point.

- Martin N.

On 12/4/06, Martin Nordholts wrote:

for instance would

gegl_node_blit_bufffer

be better than

gegl_node_blit_buf,

What's wrong with gegl_node_blit?

Rockwalrus

On Mon, Dec 04, 2006 at 12:23:07AM +0100, ?yvind Kol?s wrote:

On 12/2/06, Martin Nordholts wrote:

This is the order used in gegl_node_link, and personally I prefer to write 'from to' rather than 'to from'.

That was even a coding standard in VAX/VMS.

In any case, the order
of the parameters should be the same throughout the API.

It matched the assembly language and machin architecture. It's kind of opposite to the convention in some object-oriented languages that take the first argument as the one representing to object -- which can be modified.

-- hendrik