A preview widget for plug-ins is one of these items that has been
on the Gimp todo list for a long time. 

In order to get some feedback from other developers we have compiled a
list of requirements for a preview widget. The list is based on our own
experiences and previous discussions on this mailing list. Our goal is a
preview widget that could be used by most plug-ins.

We would like to hear your opinions on the following points: 
* Is the list complete?
* Are the requirements sufficiently clear?
* Are there any unnecessary requirements?

We are currently working on the API and a prototype implementation.
Our current implementation is based on Shawn Amundson's GimpPreview
widget. It covers most of the requirements in this list, but is still
mainly alpha code. 

When there are no major additions to these requirements we hope to publish
an API proposal in the next weeks.


Maurits Rijk <[EMAIL PROTECTED]>

Requirements for a GIMP plug-in preview widget

This document gives a possible list of requirements for a preview
widget that can be used by GIMP plug-ins.  This is the version 1.0.
This document was written by Maurits Rijk <[EMAIL PROTECTED]>
and Ernst Lippe <[EMAIL PROTECTED]>.

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 could also be combined.

Open issue: Scrollbars make the widget visually bigger and makes its
internal structure more complicated.  The alternative of giving the
preview widget two GtkAdjustments, that can be used by the developer to
"wrap" the widget with scroll-bars, does not work when the preview
widget has a visible scroll-bar and/or zoom controls.  Scroll-bars
will not be supported in the first release of the preview widget.

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.

Open issue: Should the preview accept arbitrary floating point numbers
as scale factors or should it only accept a more limited set of
different magnifications, e.g. of the form 1/n and n, where n is an
integer.  The latter approach can be more efficient in the
implementation.  It would even be more efficient when the preview only
accepted only a limited set of magnifications, e.g 1/16, 1/15,
... 1/2, 1, 2, ... 16, because specialized code could be written for
each magnification.

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.

Open issue: What should the GUI look like? A commonly used approach is
to have a "+" and "-" button and a label to show the current scale.
Another suggestion was to use spin-buttons.  Because it seems most
desirable that the scaling factors are more or less exponential the
standard Gtk spinbuttons are not very useful.  The first release of
the preview widget will use "+" and "-" buttons.

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

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 emit a signal when the user has
scrolled or zoomed the preview.

This signal can be used to synchronize multiple previews (e.g. see
Filter Pack).  This signal should contain information about the new
position and/or scale.  This signal will be emitted before the preview
attempts to update the rendered image.  The signal will only be
emitted when the preview was scrolled by the user via the GUI. The
signal will not be emitted when scrolling or zooming through the API.

Open issue: In principle the signal handler could be used to veto the
scrolling or zooming. This will be included in the first release.  Is
this desirable?

Requirement 11. The preview should have an option to emit signals
about the scrolling position while the user is still scrolling the

For efficiency reasons it is in general desirable that the scrolling
signal is only emitted when the user has stopped scrolling.  However,
when the plug-in developer wants to synchronize scrolling multiple
previews this signal must also be emitted during the scroll.

Requirement 12. The preview must support an API to scroll the preview
and change the magnification.

This functionality is needed to synchronize multiple previews.

Requirement 13. The preview must be able to halt the rendering

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.

Comment (el): I currently implemented this with an extension of the
gimp_progress_bar.  Any decent rendering function should already have
some mechanism to indicate its progress. The gimp_progress_bar_update
function returns false when the user has canceled the plug-in with the
cancel button on the window that contains the original image, so it
seems natural to use a similar approach for the preview.

Requirement 14. The user must be able to continue scrolling and
zooming even when the rendering function is still rendering a new

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 15. 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 16. 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 17. 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 18. 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.

Comment (el): This requirement comes from the GIMP TODO list.  So far
I have not been able to implement this because Gtk only executes draws
in an idle function with a low priority. So in my implementation the
preview will only be redrawn when the rendering function has finished.

Requirement 19. The preview must handle alpha by showing a
checkerboard pattern.

The GIMP GUI always handles alpha in this way.

Open issue: Must the checkerboarding pattern scroll with the image or
remain static.  The latter approach seems better with images that
contain gray areas that are adjacent to transparent areas, but it is
different from the conventions in other parts of the GIMP.

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

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

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.

Gimp-developer mailing list

Reply via email to