GimpPreview Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
struct GimpPreviewUpdateEvent; GtkWidget* gimp_preview_new (GimpDrawable *drawable); GtkWidget* gimp_preview_new_with_args (GimpDrawable *drawable, gint preview_width, gint preview_height, gdouble initial_scale, gboolean show_progressbar, gboolean show_zoom_controls, gboolean show_scroll_bars); gboolean gimp_preview_draw_scaled_drawable (GimpPreview *preview, GimpDrawable *drawable); gboolean gimp_preview_draw_unscaled_drawable (GimpPreview *preview, GimpDrawable *drawable); gboolean gimp_preview_draw_scaled_row (GimpPreview *preview, GimpImageType type, gint row, gint width, const guchar *data); gboolean gimp_preview_draw_unscaled_row (GimpPreview *preview, GimpImageType type, gint row, gint width, const guchar *data); gboolean gimp_preview_progress_set_fraction (GimpPreview *preview, gdouble fraction); void gimp_preview_update (GimpPreview *preview); void gimp_preview_set_position (GimpPreview *preview, gint x_pos, gint y_pos); void gimp_preview_get_preview_position (GimpPreview *preview, gint *prev_x_pos, gint *prev_y_pos, gint *prev_width, gint *prev_height); void gimp_preview_get_image_position (GimpPreview *preview, gint *im_x_pos, gint *im_y_pos, gint *im_width, gint *im_height); void gimp_preview_set_scale (GimpPreview *preview, gdouble scale); gdouble gimp_preview_get_scale (GimpPreview *preview); gboolean gimp_preview_get_progress_bar_visible (GimpPreview *preview); void gimp_preview_set_progress_bar_visible (GimpPreview *preview, gboolean visible); gboolean gimp_preview_get_zoom_controls_visible (GimpPreview *preview); void gimp_preview_set_zoom_controls_visible (GimpPreview *preview, gboolean visible); gboolean gimp_preview_get_scroll_bars_visible (GimpPreview *preview); void gimp_preview_set_scroll_bars_visible (GimpPreview *preview, gboolean visible); gboolean gimp_preview_get_show_original (GimpPreview *preview); void gimp_preview_set_show_original (GimpPreview *preview, gboolean show_original); void gimp_preview_set_scales (GimpPreview *preview, gint n_scales, const gdouble *scales); GtkAdjustment* gimp_preview_get_x_adjustment (GimpPreview *preview); GtkAdjustment* gimp_preview_get_y_adjustment (GimpPreview *preview); GtkAdjustment* gimp_preview_get_scale_adjustment (GimpPreview *preview); |
GObject +----GtkObject +----GtkWidget +----GtkContainer +----GtkTable +----GimpPreview |
"update-preview" void user_function (GimpPreview *gimppreview, gpointer arg1, gpointer user_data); |
The GimpPreview widget can be used by plug-ins to show the effects of the plug-in in a preview window.
The user can scroll the preview by dragging in the preview image. In most cases the rendering functions are not fast enough to produce real-time updates during scrolling. By default, the GimpPreview widget shows a (scaled) version of the original image during scrolling.
The user can zoom the preview to view the results at different magnifications. The preview has zoom controls for changing the magnification.
Computing a rendered image may take some time. The GimpPreview widget has a progress-bar that can be used to show the progress of the rendering function.
Both the progress-bar and the zoom-controls are optional and can be hidden. Note that, even when you hide the progress-bar, it is very wise to call gimp_preview_progress_set_fraction() and check its return value!
The plug-in must install a handler for the "update-preview" signal. In this handler the plug-in must render a new image and draw it on the preview.
The preview widget will generate this signal automatically when the user has scrolled or zoomed the image. You can force the widget to emit this signal by calling the gimp_preview_update function. You should probably call gimp_preview_update when the plug-in starts and when the plug-in's parameters have been changed.
There are four different ways to draw a rendered image.
Draw an unscaled GimpDrawable.
Draw a scaled GimpDrawable.
Draw a single unscaled row of pixels.
Draw a single scaled row of pixels.
When the user has scrolled or zoomed the preview, the rendered image may have become obsolete, because it uses the wrong area and/or scale. In this case, the preview will refuse to show the rendered image and the draw function will return FALSE to indicate that the current rendering has become obsolete.
When you want to draw scaled data in the preview you should read the section about scaling very carefully. It is surprisingly difficult to write a good scaling function.
The preview supports zooming to different scales. This section describe how the scaling algorithm of the preview works.
The scaling process is best described by two different coordinate systems. Every coordinate consists of two integers (x, y). The origin, that is the pixel with coordinates (0,0), is the upper leftmost pixel. The x coordinate increases to the right and the y coordinate increases to the bottom.
These are the coordinates for pixels in the original and rendered images.
These are the coordinates for pixels in the preview image. The origin, that is the pixel with coordinates (0,0), is the coordinate of the pixel that is mapped onto the origin of the unscaled image, it is not the coordinate of the upper left-most pixel of the preview.
The scaling function maps preview coordinates onto image coordinates. When the scale factor is scale the scaling algorithm maps the preview coordinates (x, y) onto the image coordinates (floor(x/scale), floor(y/scale)).
All pixels in the preview have a coordinate that is expressed in preview coordinates. The upper left-most pixel has preview coordinates (prev_x, prev_y). This pixel is mapped onto a pixel with coordinates (floor(prev_x/scale), floor(prev_y/scale)) in image coordinates.
When the size of preview image is prev_width x prev_height, the bottom right-most pixel that is shown in the preview has preview coordinates (prev_x + prev_width - 1, prev_y + prev_height - 1). This pixel is mapped onto the pixel (floor((prev_x + prev_width - 1) / scale), floor((prev_y + prev_height - 1)/scale)) in the unscaled image.
Combining the previous calculations gives the following result for the width of the original image that is needed for showing all the pixels in a single row of the preview: floor((prev_x + prev_width - 1) / scale) - floor(prev_x / scale) + 1.
The previous expression looks a bit intimidating, but it is the only correct one. When you try to use something simpler, such as floor(prev_width / scale), you'll introduce off-by-one errors that can be pretty difficult to debug. Symptoms that indicate problems in your scaling routines are "flickering" of the preview during scrolling and garbage on the borders of the image.
One very common error is to assume that scaling two numbers and adding the results is the same as first adding the numbers followed by scaling. In general this is wrong because floor(a/scale) + floor(b/scale) is not always equal to floor((a + b) / scale).
Another very common error is to assume that you can simply go from image coordinates to preview coordinates by using an expression like floor(a * scale).
The easiest solution is to let the preview handle the scaling. The only case where you might want to do scaling in the rendering function is when your rendering algorithm can more efficiently render scaled images than unscaled images. Possible candidates are rendering algorithms for which the result pixel only depends on the original image pixel, but is independent from the values of its neighbors.
struct GimpPreviewUpdateEvent { gdouble scale; /* Scale of preview */ /* Left/Top of requested unscaled data in image coordinates */ gint image_x; gint image_y; /* Width/Height of requested unscaled data in image coordinates */ gint image_width; gint image_height; /* Left/Top of preview in preview coordinates */ gint preview_x; gint preview_y; /* Width/Height of the preview */ gint preview_width; gint preview_height; }; |
This event will be sent with the "update-preview" signal, that is emitted by the preview when the rendering function should render a new image for the preview.
gdouble scale | Current scale of the preview. |
gint image_x | Left of requested unscaled data in image-coordinates. |
gint image_y | Top of requested unscaled data in image-coordinates. |
gint image_width | Width of requested unscaled data in image-coordinates. |
gint image_height | Height of requested unscaled data in image-coordinates. |
gint preview_x | Left of preview in preview-coordinates. |
gint preview_y | Top of preview in preview-coordinates. |
gint preview_width | Width of the preview. |
gint preview_height | Height of the preview. |
GtkWidget* gimp_preview_new (GimpDrawable *drawable); |
Create a new GimpPreview widget. This call creates a widget with a default size, initial scale = 1 and with a visible progress-bar zoom controls, and invisible scroll-bars.
GtkWidget* gimp_preview_new_with_args (GimpDrawable *drawable, gint preview_width, gint preview_height, gdouble initial_scale, gboolean show_progressbar, gboolean show_zoom_controls, gboolean show_scroll_bars); |
Create a new GimpPreview widget.
drawable : | The original drawable that will be shown when the user is scrolling. |
preview_width : | Width of the preview image in pixels. When it is < 0 a default width is used. |
preview_height : | Heigth of the preview image in pixels. When it is < 0 a default heigth is used. |
initial_scale : | Initial scale of the preview. |
show_progressbar : | Is the progress-bar visible. |
show_zoom_controls : | Are the zoom controls visible. |
show_scroll_bars : | Are scroll-bars visible. |
Returns : | The new GimpPreview widget. |
gboolean gimp_preview_draw_scaled_drawable (GimpPreview *preview, GimpDrawable *drawable); |
Draw a scaled drawable in the preview.
It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.
preview : | a GimpPreview. |
drawable : | A GimpDrawable that contains the scaled rendered image. |
Returns : | TRUE when the drawing on the preview is allowed. When this function returns FALSE the rendering should halt immediately. |
gboolean gimp_preview_draw_unscaled_drawable (GimpPreview *preview, GimpDrawable *drawable); |
Draw an unscaled drawable in the preview.
It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.
preview : | a GimpPreview. |
drawable : | A GimpDrawable that contains the unscaled rendered image. |
Returns : | TRUE when the drawing on the preview is allowed. When this function returns FALSE the rendering should halt immediately. |
gboolean gimp_preview_draw_scaled_row (GimpPreview *preview, GimpImageType type, gint row, gint width, const guchar *data); |
Draw one scaled row of data in the preview. This function handles conversion to RGB and checkerboarding of transparent areas.
It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.
preview : | the GimpPreview |
type : | the format of the data (e.g. GIMP_RGBA_IMAGE). |
row : | the relative number of the row within the preview. The top row of the preview is number 0. |
width : | the number of pixels in this row. |
data : | pixels for the preview. It must have a length of width pixels |
Returns : | TRUE when the drawing on the preview is allowed. When this function returns FALSE the rendering should halt immediately. |
gboolean gimp_preview_draw_unscaled_row (GimpPreview *preview, GimpImageType type, gint row, gint width, const guchar *data); |
Draw one unscaled row of data in the preview. This function handles scaling, conversion to RGB and checkerboarding of transparent areas. A nice feature is that this function will draw several lines of the preview when scale > 1.
It is only possible to draw from within an "update-preview" signal handler when the user has not scrolled or zoomed after the invocation of this signal handler. In all other cases drawing on the preview is not allowed and all drawing requests are ignored. Rendering functions should halt immediately when this function returns FALSE, because the results of this rendering function will be ignored by the preview.
preview : | the GimpPreview |
type : | the format of the data (e.g. GIMP_RGBA_IMAGE). |
row : | row is the relative position of the row w.r.t. preview_event->image_y. The top row has number 0. |
width : | the number of pixels in this row. |
data : | pixels for the preview. The first pixel in data has x-coordinate preview_event->image_x in the image. data must have a length of width pixels. |
Returns : | TRUE when the drawing on the preview is allowed. When this function returns FALSE the rendering should halt immediately. |
gboolean gimp_preview_progress_set_fraction (GimpPreview *preview, gdouble fraction); |
Set the progress bar of the preview to fraction completed.
This function is very useful even when the preview has no visible progress-bar because its return value tells the plug-in whether it should continue its computations. When the user has scrolled or zoomed, the image that is currently being computed by the rendering function has become obsolete.
When this is the case the rendering function can halt immediately because the preview will not use the result.
This function calls the GLib main loop to process new user events. If you don't call this function at regular intervals in your rendering function, the GUI will be "frozen" while the rendering function is busy. This is highly annoying.
In most cases you should consider using a GimpPreviewProgressUpdater instead of calling this function directly, because it makes it easier to write a rendering function that can be used both for the preview and for the final result.
preview : | the GimpPreview. |
fraction : | the fraction completed. |
Returns : | TRUE when the drawing on the preview is allowed. When this function returns FALSE the rendering should halt immediately. |
void gimp_preview_update (GimpPreview *preview); |
Plug-ins call this to do an update of the preview area. The preview will generate an "update-preview" signal. The plug-in's signal handler should then draw in on the preview with one of the drawing functions: gimp_preview_draw_unscaled_row(), gimp_preview_draw_unscaled_drawable(), gimp_preview_draw_scaled_row() or gimp_preview_draw_scaled_drawable().
preview : | A GimpPreview. |
void gimp_preview_set_position (GimpPreview *preview, gint x_pos, gint y_pos); |
Set the position of the area that is show in the preview.
preview : | A GimpPreview. |
x_pos : | The left side of the preview in preview-coordinates. |
y_pos : | The top side of the preview in preview-coordinates. |
void gimp_preview_get_preview_position (GimpPreview *preview, gint *prev_x_pos, gint *prev_y_pos, gint *prev_width, gint *prev_height); |
Return the size and position of the preview in preview-coordinates.
preview : | A GimpPreview. |
prev_x_pos : | Left of the preview in preview-coordinates. |
prev_y_pos : | Top of the preview in preview-coordinates. |
prev_width : | Width of the preview. |
prev_height : | Height of the preview. |
void gimp_preview_get_image_position (GimpPreview *preview, gint *im_x_pos, gint *im_y_pos, gint *im_width, gint *im_height); |
Return the size and position of the preview in image-coordinates. The preview shows a scaled version of this area of the original or rendered image.
preview : | A GimpPreview. |
im_x_pos : | Left of the preview in image-coordinates. |
im_y_pos : | Top of the preview in image-coordinates. |
im_width : | Width of the preview in image-coordinates. |
im_height : | Heigth of the preview in image-coordinates. |
void gimp_preview_set_scale (GimpPreview *preview, gdouble scale); |
Set the current scale factor for the preview.
preview : | A GimpPreview. |
scale : | The new scale factor. |
gdouble gimp_preview_get_scale (GimpPreview *preview); |
Get the current scale factor for the preview.
preview : | A GimpPreview. |
Returns : | The scale factor. |
gboolean gimp_preview_get_progress_bar_visible (GimpPreview *preview); |
Get the visibility of the progress_bar
preview : | A GimpPreview. |
Returns : | TRUE when the progress_bar is visible. |
void gimp_preview_set_progress_bar_visible (GimpPreview *preview, gboolean visible); |
Show or hide the progress_bar.
preview : | A GimpPreview. |
visible : | TRUE when the progress_bar must be visible. |
gboolean gimp_preview_get_zoom_controls_visible (GimpPreview *preview); |
Get the visibility of the zoom controls.
preview : | A GimpPreview. |
Returns : | TRUE when the zoom controls are visible. |
void gimp_preview_set_zoom_controls_visible (GimpPreview *preview, gboolean visible); |
Show or hide the zoom controls.
preview : | A GimpPreview. |
visible : | TRUE when the progress_bar must be visible. |
gboolean gimp_preview_get_scroll_bars_visible (GimpPreview *preview); |
Get the visibility of the scroll-bars.
preview : | A GimpPreview. |
Returns : | TRUE when the scroll-bars are visible. |
void gimp_preview_set_scroll_bars_visible (GimpPreview *preview, gboolean visible); |
Show or hide the scroll-bars.
preview : | A GimpPreview. |
visible : | TRUE when the scroll-bars must be visible. |
gboolean gimp_preview_get_show_original (GimpPreview *preview); |
Query the preview whether it shows the original image during scrolls.
preview : | A GimpPreview. |
Returns : | TRUE when the preview shows a scaled version of the original image during scrolls. |
void gimp_preview_set_show_original (GimpPreview *preview, gboolean show_original); |
Set whether the preview_image should show a scaled version of the original image during scrolls. When show_original is FALSE only the results of the rendering function will be shown in the display. This will only give acceptable results when the rendering function is very fast.
preview : | A GimpPreview. |
show_original : | TRUE when the preview shows a scaled version of the original image during scrolls. |
void gimp_preview_set_scales (GimpPreview *preview, gint n_scales, const gdouble *scales); |
Set the scales that are used by the zoom buttons.
preview : | A GimpPreview. |
n_scales : | Number of entries in scales array. |
scales : | Array of scale values. All values must be positive and sorted in ascending order. |
GtkAdjustment* gimp_preview_get_x_adjustment (GimpPreview *preview); |
Return the adjustment that manages the x-coordinate of the preview position. The value of this adjustment is expressed in preview-coordinates.
Applications should only change the value of the adjustment, the other properties of the adjustment are managed by the widget. When you try to set the value directly (i.e. not via a GtkScale widget) you should use gtk_adjustment_set_correct_value() (don't use gtk_adjustment_set_value() because it is buggy).
preview : | A GimpPreview. |
Returns : | The GtkAdjustment. |
GtkAdjustment* gimp_preview_get_y_adjustment (GimpPreview *preview); |
Return the adjustment that manages the y-coordinate of the preview position. The value of this adjustment is expressed in preview-coordinates.
Applications should only change the value of the adjustment, the other properties of the adjustment are managed by the widget. When you try to set the value directly (i.e. not via a GtkScale widget) you should use gtk_adjustment_set_correct_value() (don't use gtk_adjustment_set_value() because it is buggy).
preview : | A GimpPreview. |
Returns : | The GtkAdjustment. |
GtkAdjustment* gimp_preview_get_scale_adjustment (GimpPreview *preview); |
Return the adjustment that manages the scale of the preview position. The value of this adjustment is the ratio between the size of the scaled image and the size of the original image, e.g. a value of 0.5 means that the preview image is reduced by 50%.
Applications should only change the value of the adjustment, the other properties of the adjustment are managed by the widget. When you try to set the value directly (i.e. not via a GtkScale widget) you should use gtk_adjustment_set_correct_value() (don't use gtk_adjustment_set_value() because it is buggy).
preview : | A GimpPreview. |
Returns : | The GtkAdjustment. |
void user_function (GimpPreview *gimppreview, gpointer arg1, gpointer user_data); |
This signal will be emitted when the rendering function should render a new image. The preview can be forced to emit this signal by calling gimp_preview_update().
gimppreview : | The GimpPreview. |
arg1 : | A GimpPreviewUpdateEvent that describes the area that must be rendered. |
user_data : | user data set when the signal handler was connected. |