---
name: "im_render_fade"
section: "3"
platform: "linux"
package: "libvips-dev"
version: "7.20.7-1+b3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/im_render"
---

# im\_render\_fade(3)

make image in the background

Part of [im\_render(3)](/im_render/3.md).

## NAME

im\_render, im\_render\_fade, im\_cache - make image in the background

## SYNOPSIS

\#include \<vips/vips.h\>

int im\_render\_fade( IMAGE \*in, IMAGE \*out, IMAGE \*mask, \
\
   int width, int height, int max, \
\
   int fps, int steps,\
\
   int priority, \
\
   void (\*notify)( IMAGE \*, Rect \*, void \* ), void \*client );

int im\_render( IMAGE \*in, IMAGE \*out, IMAGE \*mask, \
\
   int width, int height, int max, \
\
   void (\*notify)( IMAGE \*, Rect \*, void \* ), void \*client );

int im\_cache( IMAGE \*in, IMAGE \*out, \
\
   int width, int height, int max );

## DESCRIPTION

**[im\_render\_fade(3)](/im_render_fade/3.md)** behaves rather like  **[im\_copy(3)](/im_copy/3.md)** between images **in** and  **out,** except that it keeps a cache of computed pixels. This cache is made of up to **max** tiles (a value of -1 for **max** means any number of tiles), and each tile is of size **width** by **height** pixels. Each cache tile is made with a call to  **im\_prepare\_thread(3),** so cache tile calculation will be accelerated on multi-CPU machines. If image **in** represents a large computation,  **[im\_render\_fade(3)](/im_render_fade/3.md)** can save a lot of time.

If the **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 **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 **mask** after  **out** has been closed. If mask is NULL, then no mask image is written.

If  **steps** is greater than zero, then pixels in mask are moved between 0 and 255 as tiles age in that many steps. The **fps** parameter sets how many times per second the notify function is called to indicate that an updated tile is ready.

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

**[im\_cache(3)](/im_cache/3.md)** is a convenience function for **[im\_render\_fade(3)](/im_render_fade/3.md)** that caches image pixels synchronously. If you ask for an area not in the cache, execution blocks until the area has been calculated.

**[im\_render(3)](/im_render/3.md)** is deprecated: it is the old interface to the render function, before the **fps** and **steps** parameters were added.

## RETURN VALUE

The function returns 0 on success, and non-zero on error, setting im\_error().

## SEE ALSO

[im\_prepare(3)](/im_prepare/3.md)

## AUTHOR

J Cupitt, 2003