Next: Simple Image Processing, Previous: Supported Image Formats, Up: Part VI Images [Contents][Index]
Although the image support is designed with integration into a GUI
system in mind, it neither assumes what the GUI system is nor does it
need a GUI system to work. As a matter of fact, for the most part it
doesn’t even need an X connection to work (obviously without a
connection, you won’t be able to display images). For this reason,
some of the typical (and necessary) tasks, such as progress and error
reporting, are by default implemented only to use text output (i.e.,
to stderr
). Obviously, with a GUI in place this is not quite
adequate. Hooks are available for application program to re-define
what to do with these tasks.
The interface to the library configuration is as follows
void flimage_setup(FLIMAGE_SETUP *setup);
where the parameter setup
is a pointer to a structure defined
as follows:
typedef struct { void * app_data; int (*visual_cue) (FL_IMAGE *im, const char *msg); void (*error_message) (FL_IMAGE *im, const char *msg); const char * rgbfile; int do_not_clear; int max_frames; int delay; int double_buffer; int add_extension; } FLIMAGE_SETUP;
with
app_data
The application can use this field to set a value so the field
image->app_data
in all image structures returned by the library
will have this value. It’s most useful to set this field to something
that’s persistent during the application run, such as the fdui
structure of the main control panel.
Note that image->app_data
is different from
image->u_vdata
in that all image structures returned by the
library have the same value of image->app_data
, which is set by
the library. In contrast, image->u_vdata
is set by the
application on an image-by-image basis.
visual_cue
This is the function that will be called by all image reading, writing
and processing routines. The function is meant to give the user some
visual feedback about what is happening. For lengthy tasks, this
function is called repeatedly and periodically to indicate what
percentage of the task is completed and to give the application
program a chance to check and process GUI activities (for example, via
fl_check_forms()
).
The first parameter to the function is the image currently being worked on and the second parameter is a short message, indicating the name of the task, such as "Reading JPG" etc.
Two fields in the image structure can be used to obtain progress
information. The member fields image->total
indicates the total
amount of work to be done in some arbitrary units (usually number of
rows in the image). image->completed
indicates how much of the
task has been completed. The percentage of how much is completed is
then simply the ratio of image->completed
and
image->total
, multiplied by 100.
At the begin of a task image->completed
is set to a value less
or equal 1, and at the end of the task, image->completed
is set to
image->total
.
A special value of -1 for image->completed
may be used to
indicate a task of unknown length.
error_message
This is a function that is called when an error (of all severities) has occurred inside the library. It is recommanded that the application provide a means to show the messages to the user by sypplying this function.
The first parameter is a pointer to the image that’s being worked on, and the second parameter is a brief message, such as "memory allocation failed" etc.
A convenience function,
flimage_error()
, is provided to
call the error message handler.
rgbfile
This field should be set to the full path to the color name database (rgb.txt) if your system has it in non-standard locations. On most systems, this file is /usr/lib/X11/rgb.txt, which is the default if this field is not set.17
do_not_clear
By default, flimage_display()
clears the window before
displaying the image. Set this member to 1 to disable window clearing.
no_auto_extension
By default, flimage_dump()
changes the filename extension
to reflect the format. Set this member to 1 to disable extension
substitution.
double_buffer
If set, all image display will by default double-buffered. Double-buffering an image is very expensive (in terms of both resource and speed) as the backbuffer is simulated using a pixmap. If there are no annotations, double-buffering an image does not really improve anything.
It is far better to turn double-buffering on and off on a
image-by-image basis using the image->double_bufffer
field.
max_frames
This field specifies the maximum number of frames to read by
flimage_load()
. The default maximum is 30 frames.
delay
This field specifies the delay (in milliseconds) between successive
frames. It is used by the flimage_display()
routine.
Note that it is always a good idea to clear the setup structure before initializing and using it
FLIMAGE_SETUP mysetup; memset(mysetup, 0, sizeof mysetup); mysetup.max_frames = 100; mysetup.delay = 10; flimage_setup(&mysetup);
It is possible to modify the image loading process by utilizing the
following routines flimage_load()
is based on:
FL_IMAGE *flimage_open(const char *name);
This function takes a file name and returns an image sturcture pointer
if the file is a recognized image file. Otherwise NULL
is
returned.
FL_IMAGE *flimage_read(FL_IMAGE *im);
takes an image structure returned by flimage_open()
and
fills the image structure. Between flimage_open()
and
flimage_read()
you can inspect or modify fields in the
image structure.
int flimage_close(FL_IMAGE *im);
This function closes all file streams used to create the image.
The routine where this field is used searches some more locations than the default and should work on most systems automagically.
Next: Simple Image Processing, Previous: Supported Image Formats, Up: Part VI Images [Contents][Index]