This is the new version of the plug-in preview requirements. Compared with the preview version a few requirements have been dropped (which is something that does not happen too often in requirements discussions).

One of the other results of the discussion was that we decided to split the preview into two widgets: * a "convenience" preview widget with bells and whistles, such as zoom buttons, progress-bar and scroll-bars (yes, even those). * a bare bones preview image widget that shows the actual preview and has support for scaling and zooming.

At the moment we have an implementation that supports all the requirements in the list (writing requirements after you've implemented a system is a perfect way to satisfy all system requirements).

At the moment we are still working on it, but we hope to publish the API real soon now.

greetings,

Ernst Lippe

Requirements for a GIMP plug-in preview widget V1.1 ===================================================

INTRODUCTION

This document gives a possible list of requirements for a preview widget that can be used by GIMP plug-ins.

This document was written by Maurits Rijk and Ernst Lippe .

HISTORY

This version reflects the results of the discussion on the Gimp-developer mailing list in February 2003.

All requirements about signals, that should be emitted when the user when the user scrolls or zooms with the GUI, have been dropped for the moment.

REQUIREMENTS

REQUIREMENT 1: A plug-in author must be able to write a single version of the rendering function that can both be used for rendering to the plug-in and for rendering to the final drawable.

Far too many plug-ins that have a preview contain two different versions of the rendering algorithm: one for the preview and another one for the final result. For plug-ins that don't have a preview yet it is very desirable that the interface for generating a rendered image for the preview is very similar to the interface for generating the final results.

REQUIREMENT 2: The preview must support a GUI for scrolling through the image.

There are two possible GUI styles: dragging in the preview and using scrollbars. These can also be combined.

REQUIREMENT 3: When dragging can be used to scroll the preview it should show a "move" cursor in the preview image.

This gives visual feedback to the user that the image can be scrolled.

REQUIREMENT 4: During scrolling the preview should optionally show a (possibly scaled) version of the original image.

In many cases rendering algorithms are too slow to support real-time scrolling. It must be possible to turn this feature off. This would be better when the rendering algorithm is fast and when the rendered result bears little resemblance to the original image.

REQUIREMENT 5: The preview must support zooming.

Viewing a rendered image at different scales is very useful for a wide range of plug-ins.

REQUIREMENT 6: The preview must contain an optional GUI for zooming.

A standard GUI for zooming the preview increases the uniformity of plug-ins and makes life easier for plug-in writers. It must be possible to hide the zooming GUI for previews that either don't support zooming or use a different interface.

REQUIREMENT 7: The preview must be able to handle both scaled and unscaled rendered data.

In some cases the rendering algorithm may be able to produce a scaled version of its outputs. In many cases the rendering algorithm cannot easily produce scaled data and then the preview should do the scaling.

REQUIREMENT 8: The scaling algorithm must be stable under scrolling.

The user must have the impression of scrolling through a fixed scaled version of the image. When the scaling algorithm is not stable, the preview will flicker during the scroll, which is highly annoying. In most cases this is caused by rounding errors. It is surprisingly difficult to write a good scaling algorithm due to these numerical problems.

REQUIREMENT 9: During zooming the preview should attempt to keep the center of the previewed image at the same position.

This is similar to the visual behaviour of zooming with a camera.

REQUIREMENT 10: The preview must support an API to scroll the preview and change the magnification.

This functionality is needed to synchronize multiple previews.

REQUIREMENT 11: The preview must be able to halt the rendering algorithm.

Frequently, the user will perform actions like scrolling or zooming that makes the image, that is being rendered by the rendering function, obsolete. There must be some way for the preview to inform the rendering function that it can stop.

REQUIREMENT 12: The user must be able to continue scrolling and zooming even when the rendering function is still rendering a new image.

With slow rendering algorithms it is intolerable when the widget "locks up" during rendering. When the user scrolls or zooms the preview, the image that is currently being rendered becomes obsolete.

REQUIREMENT 13: The preview must supply a mechanism that prevents showing obsolete rendered images.

It is possible that the rendering function will attempt to display image data in the preview that already has been obsoleted because the preview was scrolled or zoomed. The preview should ignore such obsolete drawing requests.

REQUIREMENT 14: The preview must have an optional progress bar to indicate the progress of the rendering function.

With slow rendering functions it is not obvious to the user when the rendering function has updated the display. It must be possible to hide the progress bar.

REQUIREMENT 15: The preview must be resizable at run-time.

In some cases users would like to enlarge the preview to get a better overview of the results. On the other hand large previews take more time to render and may clutter up the display. A resizable preview allows the user to select an optimal size. This requirement does not imply that the preview should offer a GUI for resizing, but only that it should respond when Gtk has allocated a new size for the preview.

REQUIREMENT 16: The preview must handle alpha by showing a checkerboard pattern.

The GIMP GUI always handles alpha in this way.

LOW PRIORITY REQUIREMENTS

The following point is not a formal requirement.

NICE TO HAVE 1: The preview must support incremental updates of rendered image data.

With slow rendering algorithms it may be desirable to update the preview as soon as new parts of the image have been rendered.

This requirement comes from the GIMP TODO list. It is not clear how this should be implemented.

NON-REQUIREMENTS

The following points have been mentioned in discussions about the preview widget. They are listed here because we explicitely don't want to support them.

NON-REQUIREMENT 1: Preview the rendered results in the original image window.

The rendered image should be shown in the original image window.

Comment: This is one of the suggestions from the GUAD3C meeting. It does not seem relevant for the preview widget.

NON-REQUIREMENT 2: Split preview window with before and after version of the image.

The user must be able to split the preview into two parts, one part showing the original image and the other part showing the rendered image.

Open issue: How should the preview be split? Suggestions have been left/right, top/bottom and even diagonally.

Comment: This is one of the suggestions from the GUAD3C meeting. It is not clear what the GUI for splitting/unsplitting should be. Also it seems much more useful to show before/after versions of the same area and not only for adjoining areas (which was the proposal, if I understood it correctly). Another disadvantage is that it makes the preview-code more complicated. When you really want to show both before and after it seems much easier to have two different previews that are synchronized with each other.

On 19 Mar 2003 18:47:11 +0100
Sven Neumann wrote:

Hi,

Ernst Lippe writes:

At the moment we have an implementation that supports all the requirements in the list (writing requirements after you've implemented a system is a perfect way to satisfy all system requirements).

At the moment we are still working on it, but we hope to publish the API real soon now.

It would be really nice to see something in CVS soon. This would avoid that already written code is lost due to hardware problems (this has happened before). It would also assure that the preview makes it into the next version and isn't hold off by the feature freeze that is coming really soon now.

Maurits fully agrees with you.

But at the moment my distribution already contains multiple files: * Two widgets
* Two support modules
* Gtk-doc documentation files for the previous. * A plug-in test bed for the preview. * Three example plug-ins that use the preview. Maurits has written some additional code that I would like to include as well, but I believe it will need some modifications. Also, I would really like to include some sort of tutorial and a simple example (no, these are not written yet). At the moment my development environment is nicely organized for my own developments, I've got a standard Gnu distribution with autoconf, automake, gtk-doc. Altogether I've got 44 files in CVS just for this project. I can't imagine that you would be very pleased to add all of them to Gnome CVS.

Another point is that the current name of the widget is GimpPreview and for some reason I don't think that you will like that name (even though my widget is a direct descendant of Shawn's widget that was written somewhere in 1998). In my experience renaming or reorganizing files after you've added them to CVS is something you should generally try to avoid.

Another issue is that I can't compile the current CVS version of the GIMP anymore, because you've upgraded to the most recent version (2.2) of glib etc. Yes, I know that this sounds lame, but over the years I've grown increasingly tired of always trying to use the latest and greatest version of everything, because in most cases, I had to spend a lot of effort to upgrade a myriad of libraries after which I had to conclude that the whole thing would not work on my system anyway. I think that several other plug-in developers are in the same position, so I don't believe that they would mind if they could get a preview that was not yet in the official CVS.

Also I don't think that you have to worry about hardware failures too much, I just sent Maurits a full distribution of my stuff. Earthquakes are very rare in the Netherlands, we are generally more afraid of floods and AFAIK I live sufficiently high above sea-level.

All this does not mean that I would not like to see my preview in the GIMP CVS ASAP. I'd really like to have the preview and at least a few of the plug-ins in the official 1.4 distribution. (BTW is there already a new deadline? I believe that it was originally scheduled for the end of last year).

So, the bottom-line is, that I really would like to see the widget in the CVS but that it would not be wise to do so before other people have commented on it.

Also, like Nick Lamb remarked today, it is not very useful to put brilliant new stuff in CVS, when there is no real support and follow-up.

greetings,

Ernst

P.S. Don't worry too much. I have been working on this preview for about four years and I believe that its code is much better shape than e.g. most of the GIMP plug-ins. Previews are very important for a nice GUI but developers will only use them when they are easy to use and well-documented. After my discussions with Maurits and the Gimp-developer list I made some drastic modifications such as splitting the original widget into two different widgets. I'd like to keep that freedom for a little while.
When there is enough support for its API, I could have it ready for CVS in a few days. The code compiles cleanly with GTK+-2.0 and GIMP 1.3.12 and it has decent gtk-doc documentation.

On Thu, 20 Mar 2003 10:55:49 +0100 Sven Neumann wrote:

Ernst Lippe writes:

Another point is that the current name of the widget is GimpPreview and for some reason I don't think that you will like that name (even though my widget is a direct descendant of Shawn's widget that was written somewhere in 1998).

we should discuss this. Generally GimpPreview is perfectly acceptable as a name but since we use it in the core already we should consider to look for another name to avoid confusion.

Maurits has suggested to use GimpEffectPreview, which sounds OK, but other suggestions are welcome.

All this does not mean that I would not like to see my preview in the GIMP CVS ASAP. I'd really like to have the preview and at least a few of the plug-ins in the official 1.4 distribution. (BTW is there already a new deadline? I believe that it was originally scheduled for the end of last year).

I don't think it has ever been scheduled with a fixed date. It's ready when it's ready but we are now trying to push things a bit. I'm putting some pressure on you just to let you know that we'd rather like to see a working-yet-not-perfect plug-in preview widget than no plug-in preview widget at all.

Of course I am flattered by your interest.

At the moment both the API and the internal architecture are not fixed as far as I am concerned. I want the preview to be both both flexible and easy to use for plug-in developers. There have been other attempts to develop a preview widget in the past. Shawn wrote his GimpPreview widget ages ago, but even though it had a lot of nice features, I know only one plug-in (yep, that's mine) that really used it. I am not really certain why it failed: too complicated, not flexible enough, not enough documentation or publicity? I'd really like to avoid the same trap and that's why I am trying to follow the slow and sometimes boring path through requirements, design and implementation.

We'll publish the API for comments as soon as Maurits has finished reviewing the most recent version.

As soon as there is sufficient support for the API (I don't expect a real concensus, but I'll really try to incorporate good suggestions) the API will be frozen, and you could probably get a first, probably not fully functional, version within a week.

greetings,

Ernst