.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