Vips.Image.sink_screen

### Method

# Vips Imagesink_screen

#### Declaration [src]

    int
    vips_sink_screen (
      VipsImage* in,
      VipsImage* out,
      VipsImage* mask,
      int tile_width,
      int tile_height,
      int max_tiles,
      int priority,
      VipsSinkNotify notify_fn,
      void* a
    )

#### Description [src]

This operation renders `in` in the background, making pixels available on `out` as they are calculated. The `notify_fn` callback is run every time a new set of pixels are available. Calculated pixels are kept in a cache with tiles sized `tile_width` by `tile_height` pixels and with at most `max_tiles` tiles. If `max_tiles` is -1, the cache is of unlimited size (up to the maximum image * size). The `mask` image is a one-band uchar image and has 255 for pixels which are currently in cache and 0 for uncalculated pixels.

Renders with a positive priority are assumed to be large, high-priority, foreground images. Although there can be many of these, only one is ever active, to avoid overcommitting threads.

Renders with a negative priority are assumed to be small, thumbnail images, consisting of a single tile. Single tile images are effectively single-threaded, so all these renders are evaluated together.

Calls to `vips_region_prepare()` on `out` return immediately and hold whatever is currently in cache for that `VipsRect` (check `mask` to see which parts of the `VipsRect` are valid). Any pixels in the `VipsRect` which are not in cache are added to a queue, and the `notify_fn` callback will trigger when those pixels are ready.

The `notify_fn` callback is run from one of the background threads. In the callback you need to somehow send a message to the main thread that the pixels are ready. In a glib-based application, this is easily done with `g_idle_add()`.

If `notify_fn` is `NULL` then `vips_sink_screen()` runs synchronously. `vips_region_prepare()` on `out` will always block until the pixels have been calculated.

See also

`vips_tilecache()`, `vips_region_prepare()`, `vips_sink_disc()`, `vips_sink()`.

#### Parameters

`out`

  Type: `VipsImage`

  Output image.

  The argument will be set by the function.
  The caller of the method takes ownership of the returned data, and is responsible for freeing it.

`mask`

  Type: `VipsImage`

  Mask image indicating valid pixels.

  The data is owned by the caller of the method.

`tile_width`

  Type: `int`

  Tile width.

`tile_height`

  Type: `int`

  Tile height.

`max_tiles`

  Type: `int`

  Maximum tiles to cache.

`priority`

  Type: `int`

  Rendering priority.

`notify_fn`

  Type: `VipsSinkNotify`

  Pixels are ready notification callback.

  The argument can be `NULL`.

`a`

  Type: `void*`

  Client data for callback.

  The argument can be `NULL`.
  The data is owned by the caller of the method.

#### Return value

Type: `int`

0 on success, -1 on error.