| .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 |
