104 lines
2.7 KiB
Groff
104 lines
2.7 KiB
Groff
.TH IM_RENDER 3 "5 October 2003"
|
|
.SH NAME
|
|
im_render, im_render_fade, im_cache \- make image in the background
|
|
.SH SYNOPSIS
|
|
#include <vips/vips.h>
|
|
|
|
int im_render_fade( IMAGE *in, IMAGE *out, IMAGE *mask,
|
|
.br
|
|
int width, int height, int max,
|
|
.br
|
|
int fps, int steps,
|
|
.br
|
|
int priority,
|
|
.br
|
|
void (*notify)( IMAGE *, Rect *, void * ), void *client );
|
|
|
|
int im_render( IMAGE *in, IMAGE *out, IMAGE *mask,
|
|
.br
|
|
int width, int height, int max,
|
|
.br
|
|
void (*notify)( IMAGE *, Rect *, void * ), void *client );
|
|
|
|
int im_cache( IMAGE *in, IMAGE *out,
|
|
.br
|
|
int width, int height, int max );
|
|
|
|
.SH DESCRIPTION
|
|
.B im_render_fade(3)
|
|
behaves rather like
|
|
.B im_copy(3)
|
|
between images
|
|
.B in
|
|
and
|
|
.B out,
|
|
except that it keeps a cache of computed pixels. This cache is made of up to
|
|
.B max
|
|
tiles (a value of -1 for
|
|
.B max
|
|
means any number of tiles), and each tile is of size
|
|
.B width
|
|
by
|
|
.B height
|
|
pixels. Each cache tile is made with a call to
|
|
.B im_prepare_thread(3),
|
|
so cache tile calculation will be accelerated on multi-CPU machines. If image
|
|
.B in
|
|
represents a large computation,
|
|
.B im_render_fade(3)
|
|
can save a lot of time.
|
|
|
|
If the
|
|
.B notify
|
|
parameter points to a function, then tiles are not calculated immediately, but
|
|
are added to a job list and calculated as CPU becomes available. When a tile has
|
|
been calculated, the notify function is passed the image which was being
|
|
cached, the area of the image which is now available, and a client pointer.
|
|
The notify function will be called by a background thread, so you will usually
|
|
need to implement some mechanism to interrupt your main thread and update.
|
|
|
|
The
|
|
.B mask
|
|
image is a one band uchar image the same size as out, which has 255 for every
|
|
pixels which is in the cache and 0 everywhere else. You should not read
|
|
pixels from
|
|
.B mask
|
|
after
|
|
.B out
|
|
has been closed. If mask is NULL, then no mask image is written.
|
|
|
|
If
|
|
.B steps
|
|
is greater than zero, then pixels in mask are moved between 0 and 255 as tiles
|
|
age in that many steps. The
|
|
.B fps
|
|
parameter sets how many times per second the notify function is called to
|
|
indicate that an updated tile is ready.
|
|
|
|
If
|
|
.B priority
|
|
is zero, then the render will only run when the system is idle, and only a few
|
|
renders will run at any time. Higher values will cause the render to happen
|
|
more quickly.
|
|
|
|
.B im_cache(3)
|
|
is a convenience function for
|
|
.B im_render_fade(3)
|
|
that caches image pixels synchronously. If you ask for an area not in the cache,
|
|
execution blocks until the area has been calculated.
|
|
|
|
.B im_render(3)
|
|
is deprecated: it is the old interface to the render function, before the
|
|
.B fps
|
|
and
|
|
.B steps
|
|
parameters were added.
|
|
|
|
.SH RETURN VALUE
|
|
The function returns 0 on success, and non-zero on error, setting
|
|
im_error().
|
|
.SH SEE ALSO
|
|
im_prepare(3)
|
|
.SH AUTHOR
|
|
J Cupitt, 2003
|