As promised here is my API proposal for a plug-in preview widget. You can find it at http://refocus.sourceforge.net/preview.

Please examine it critically, this should be a preview that should be usable for a very wide range of plug-ins.

Because I would like to reuse this proposal (or what is left of it after the discussion) for the final documentation I also welcome minor comments such as spelling mistakes, grammar corrections, coding errors and such.

greetings,

Ernst Lippe

On Mon, 31 Mar 2003 19:58:29 +0200 Sven Neumann wrote:

Hi,

Ernst Lippe writes:

As promised here is my API proposal for a plug-in preview widget. You can find it at http://refocus.sourceforge.net/preview.

Please examine it critically, this should be a preview that should be usable for a very wide range of plug-ins.

Because I would like to reuse this proposal (or what is left of it after the discussion) for the final documentation I also welcome minor comments such as spelling mistakes, grammar corrections, coding errors and such.

one thing that I noted at first glance is the namespace. It is absolutely unacceptable to have any types or function names in the GIMP API that don't have a GIMP prefix. I'd even prefer to have everything that is related to this widget be under the same namespace. Unfortunately GimpPreview is already taken, so we either need to change the name of the core object or find a new one for the plug-in preview.

I fully agree that the names must be changed.

The problem is how? Maurits suggested GimpEffectPreview, which is not a bad name, but I don't really like having to preview every function with gimp_effect_preview_ . I know it is a bit old-fashioned but I still think that source code should be readable on a tty with 80 characters.

greetings,

Ernst Lippe

P.S. Of course the most logical solution is to change the name of the core widget. My widget is derived from Shawn Amundson's GimpPreview widget that was written in 1998, and that was long before some GIMP developer tried to claim that name. It is clear that this is an obvious infringement of our trademark.

On Mon, 31 Mar 2003 11:21:06 -0800 (PST) Nathan Carl Summers wrote:

On 31 Mar 2003, Sven Neumann wrote:

I'd even prefer to have everything that is related to this widget be under the same namespace. Unfortunately GimpPreview is already taken, so we either need to change the name of the core object or find a new one for the plug-in preview.

(off-the-cuff) Perhaps GimpThumbnail?

It is a nice short name, but I have the impression that a thumbnail is a reduced size version of the original image, and for most plug-ins I would expect that the preview normally shows a small part of the image at its real size.

greetings,

Ernst Lippe

On Mon, 31 Mar 2003 20:17:51 +0200 Sven Neumann wrote:

Hi,

Ernst Lippe writes:

As promised here is my API proposal for a plug-in preview widget. You can find it at http://refocus.sourceforge.net/preview.

In the section "Design" in "Calling the render function" you state:

A somewhat smarter version of this preview used a different approach. The rendering function had to call back to the GTK main loop, so it could process new events.

I wouldn't call this a smart version since this is something that you better not try to implement. Why do you want to drive the GTK+ main loop yourself? This only leads to really complicated behaviour (as you seem to have experienced yourself). The easiest approach to this problem seems to be to split the rendering function into small chunks. Instead of calling some function that processes events, the render function returns after computing a small tile of the preview image. The standard GTK+ main loop takes back control, user events are processed and if it ever becomes idle again, the list of invalid tiles is examined and the render function is called with the next area to update. Did you consider this approach?

Yes, and I did not like it.

One of the goals for this preview was that it should be easy to use the same function for rendering to the preview and to the final image.
In many cases it is not too difficult to convert an existing rendering algorithm so that it will only render a specific area of the final result.
But many plugin algorithms have a considerable setup time, which means that there is a lot of overhead when you call the rendering function for each output tile.

The only way to avoid this overhead is to make interface more complicated, analogous to the GimpPixelRegions, there should be an _init interface that the preview uses to inform the plug-in about the total area that it wants, and a _render_tile interface that tells the plug-in that it should render a specific tile. If you want to rewrite an existing rendering function to this new interface you will have to make major changes. (Essentially this is very similar to the steps that you have to make when you want to change a recursive function into an iterative function. It is always possible, but the results are generally completely unreadable.) Basically, what you will have to do is to record local variables in functions in some global structure, and to retrieve these values when you have to compute the next tile.

To summarize, if the preview should ask the plug-in to render individual tiles (and when the preview is zoomed out or when the preview is large there can be a large number of tiles that must be rendered) it will either be inefficient for some plug-ins or plug-in authors will have to implement a complicated interface.

As a plug-in author, I believe that my proposed interface is very natural. I have already converted a few plug-ins and that was fairly straight-forward. I definitely would not like having to rewrite those plug-ins in such a way that they could efficiently compute individual tiles.

Also I must say that I am a bit disappointed that calling the GTK main loop is so expensive (or that there apparently is no other way to process new GUI events). Giving control to the main event loop at regular intervals during computations is a standard solution to avoid freezing of the GUI in cooperative multi-tasking systems.

greetings,

Ernst Lippe

On Mon, 31 Mar 2003 22:50:00 +0200 Sven Neumann wrote:

Hi,

Ernst Lippe writes:

P.S. Of course the most logical solution is to change the name of the core widget. My widget is derived from Shawn Amundson's GimpPreview widget that was written in 1998, and that was long before some GIMP developer tried to claim that name. It is clear that this is an obvious infringement of our trademark.

I quick grep through the sources shows that we'd have to change more than 150 files and I doubt that this could safely be done by a naive search-and-replace operation. So this is probably not a reasonable option.

Irony is always difficult on a written medium like e-mail. (I should have included some smileys) Of course, I know that this was not a very realistic option, but perhaps it might trigger the core developers to think about a good name for this preview :)

greetings,

Ernst Lippe

On Tue, 01 Apr 2003 13:59:21 +0200 Sven Neumann wrote:

Hi,

Ernst Lippe writes:

The only way to avoid this overhead is to make interface more complicated, analogous to the GimpPixelRegions, there should be an _init interface that the preview uses to inform the plug-in about the total area that it wants, and a _render_tile interface that tells the plug-in that it should render a specific tile.

I don't think the GimpPixelRgn API is overly complicated.

I didn't say it was, I only claimed that my current interface is simpler.

Of course an
iterative API as I propose it needs an iterator structure but I don't see how this approach would be overly complicated.

Because you force the developer to write his rendering function as a finite state machine. FSM's are difficult to read and maintain. For really simple plug-ins this is not a big problem, but for algorithms that make several passes over the data this will soon become a mess. (I don't know if there are any plug-ins that use recursive functions but converting those into FSM's is not very pretty because they will have to maintain their own stacks explicitely.)

Also when you discover at some later stage that a certain function your program is taking to much time you will have to completely rewrite plus all the functions that directly or indirectly call it. In my API this is much easier, you simply add the ProgressUpdater as an extra argument and call it at the right places.

What I expect is that most plug-in developers simply don't want to go through all this trouble. The final result is that these plug-ins will regularily freeze the GUI. This is really terribly frustrating, because you have to wait until the computer is finished with computing something that you don't want.

If you want to rewrite an existing rendering function to this new interface you will have to make major changes. (Essentially this is very similar to the steps that you have to make when you want to change a recursive function into an iterative function. It is always possible, but the results are generally completely unreadable.) Basically, what you will have to do is to record local variables in functions in some global structure, and to retrieve these values when you have to compute the next tile.

Exactly. This is something every good plug-in should do anyway. Most plug-ins already render on a tile-by-tile basis or at least do it row-by-row. Shouldn't it be relatively easy to make this a function which is called from the main-loop?

That depends on the amount of book-keeping that that function has to do. All local variables must be moved into global structs, all loops must be broken into separate pieces, the code becomes less localized because related item get scattered everywhere, etc.

Also I must say that I am a bit disappointed that calling the GTK main loop is so expensive (or that there apparently is no other way to process new GUI events). Giving control to the main event loop at regular intervals during computations is a standard solution to avoid freezing of the GUI in cooperative multi-tasking systems.

sure, but it is usually done by returning to the main event loop, not by driving it manually.

As far as I can tell that is the only way that I can get GTK to process new user actions. If that is not allowed, programmers are forced to write all computing intensive operations as FSM's, which I would find completely unacceptable for a GUI toolkit.

If you do the latter, you introduce the need to write reentrant functions. This is usually not necessary in a single-threaded environment and I don't think we should put that burden on the plug-in developers. As you said in your document, using global variables is a bad habit but since you looked at some plug-ins you know that it is rather common. I agree that your API may look natural (after a much needed cleanup) but I fear that most plug-in authors will not understand the implications of the design.

I really did not think that re-entrancy would be a real problem. Anyhow, it can be eliminated by a little more bookkeeping in the preview, in such a way that at all times there is at most one instance of the rendering function active. This will slightly reduce the responsiveness of the preview, but otherwise I don't see any problems with this.

greetings,

Ernst

On Tue, 01 Apr 2003 12:54:18 +0200 "David Necas (Yeti)" wrote:

What about something like GimpProofView? - it't not longer than GimpThumbnail - it resembles GimpPreview
- "proof" is a relatively good word (though mostly used in printing only, in this sense)
- the "view" is just a tag, but "proof" alone is strange

It's quite easy to invent new words and phrases for me, thanks to my miserable English ;-) but "proof view" seems to be already invented, according to Google.

I can't find it in my Webster's, but proof does have the right connotation, after all the preview is a preliminary version of the final results.

greetings,

Ernst Lippe

On Wed, 02 Apr 2003 15:30:04 +0200 usr352@wanadoo.es wrote:

Sven Neumann wrote:

anyway. Now if only we could come up with a good name for the core widget ...

May I suggest "GimpMiniview"?

Yes, you may :)
But it sounds like something tiny. Actually when you zoom in and use a large preview it can be much bigger than the original image.

greetings,

Ernst Lippe

Even though I fully agree that the only serious problem in my API proposal is the name of the widget, I'd really like to get more input from more people about my API proposal.

Especially, I would like to hear remarks from other plug-in developers, because they are after all the intended audience for this widget. (I somehow have the feeling that Sven is not really an average plug-in developer:).
So for all average (and especially the below-average) plug-in developers: * Do you miss any features?
* Is the documentation sufficient?
* Would you use it?

Of course I would also like some inputs about the discussion about using iterators in the rendering function.

greetings,

Ernst

P.S. I just modified my preview so that the re-entrancy problem has been eliminated.

On Thu, 03 Apr 2003 02:15:42 +0200 "David Necas (Yeti)" wrote:

On Thu, Apr 03, 2003 at 01:15:31AM +0200, Ernst Lippe wrote:

P.S. I just modified my preview so that the re-entrancy problem has been eliminated.

Excuse me, but which reentrancy problem has been eliminated? Does it mean the render function no longer needs to be reentrant?

Yes, just added some book-keeping to preview, and it seems to work.

Regards,

Yeti

P.S.: Regarding the name, when I've seen the last suggestions, GimpWWAAN (Widget Without Any Acceptable Name) seem to be the most accurate... :-)

On the contrary, there appear to be lots of acceptable names.
I am suprised that nobody has suggested YetAnotherGimpPreview :)

greetings,

Ernst