libvips

VipsStartFn ()

void *
(*VipsStartFn) (VipsImage *out,
                void *a,
                void *b);

Start a new processing sequence for this generate function. This allocates per-thread state, such as an input region.

See also: vips_start_one(), vips_start_many().

VipsGenerateFn ()

int
(*VipsGenerateFn) (VipsRegion *out,
                   void *seq,
                   void *a,
                   void *b,
                   gboolean *stop);

Fill out->valid with pixels. seq contains per-thread state, such as the input regions. Set stop to TRUE to stop processing.

See also: vips_image_generate(), vips_stop_many().

VipsStopFn ()

int
(*VipsStopFn) (void *seq,
               void *a,
               void *b);

Stop a processing sequence. This frees per-thread state, such as an input region.

See also: vips_stop_one(), vips_stop_many().

VIPS_IMAGE_SIZEOF_ELEMENT()

#define             VIPS_IMAGE_SIZEOF_ELEMENT( I )

VIPS_IMAGE_SIZEOF_PEL()

#define             VIPS_IMAGE_SIZEOF_PEL( I )

VIPS_IMAGE_SIZEOF_LINE()

#define             VIPS_IMAGE_SIZEOF_LINE( I )

VIPS_IMAGE_N_ELEMENTS()

#define             VIPS_IMAGE_N_ELEMENTS( I )

VIPS_IMAGE_N_PELS()

#define             VIPS_IMAGE_N_PELS( I )

VIPS_IMAGE_ADDR()

#define             VIPS_IMAGE_ADDR( I, X, Y )

This macro returns a pointer to a pixel in an image, cast to a VipsPel *. It only works for images which are fully available in memory, so memory buffers and small mapped images only.

If VIPS_DEBUG is defined, you get a version that checks bounds for you.

See also: vips_image_wio_input(), vips_image_inplace(), VIPS_REGION_ADDR().

VIPS_MATRIX()

#define             VIPS_MATRIX( I, X, Y )

This macro returns a pointer to a pixel in an image, cast to a double*. The image must have a single band, be VIPS_FORMAT_DOUBLE and be fully available in memory, so memory buffers and small mapped images only.

If VIPS_DEBUG is defined, you get a version that checks bounds and image type for you.

See also: vips_image_wio_input(), vips_image_inplace(), vips_check_matrix().

vips_progress_set ()

void
vips_progress_set (gboolean progress);

If set, vips will print messages about the progress of computation to stdout. This can also be enabled with the --vips-progress option, or by setting the environment variable VIPS_PROGRESS.

vips_image_invalidate_all ()

void
vips_image_invalidate_all (VipsImage *image);

Invalidate all pixel caches on image and any downstream images, that is, images which depend on this image. Additionally, all operations which depend upon this image are dropped from the VIPS operation cache.

You should call this function after destructively modifying an image with something like vips_draw_circle().

The “invalidate” signal is emitted for all invalidated images.

See also: vips_region_invalidate().

vips_image_minimise_all ()

void
vips_image_minimise_all (VipsImage *image);

Minimise memory use on this image and any upstream images, that is, images which this image depends upon. This function is called automatically at the end of a computation, but it might be useful to call at other times.

The “minimise” signal is emitted for all minimised images.

vips_image_is_sequential ()

gboolean
vips_image_is_sequential (VipsImage *image);

TRUE if any of the images upstream from image were opened in sequential mode. Some operations change behaviour slightly in sequential mode to optimize memory behaviour.

vips_image_set_progress ()

void
vips_image_set_progress (VipsImage *image,
                         gboolean progress);

vips signals evaluation progress via the “preeval”, “eval” and “posteval” signals. Progress is signalled on the most-downstream image for which vips_image_set_progress() was called.

vips_image_iskilled ()

gboolean
vips_image_iskilled (VipsImage *image);

If image has been killed (see vips_image_set_kill()), set an error message, clear the VipsImage.kill flag and return TRUE. Otherwise return FALSE.

Handy for loops which need to run sets of threads which can fail.

See also: vips_image_set_kill().

vips_image_set_kill ()

void
vips_image_set_kill (VipsImage *image,
                     gboolean kill);

Set the VipsImage.kill flag on an image. Handy for stopping sets of threads.

See also: vips_image_iskilled().

vips_filename_get_filename ()

char *
vips_filename_get_filename (const char *vips_filename);

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the filename part, "fred.jpg" in this case.

Useful for language bindings.

See also: vips_filename_get_options().

vips_filename_get_options ()

char *
vips_filename_get_options (const char *vips_filename);

Given a vips filename like "fred.jpg[Q=90]", return a new string of just the options part, "[Q=90]" in this case.

Useful for language bindings.

See also: vips_filename_get_filename().

vips_image_new ()

VipsImage *
vips_image_new (void);

vips_image_new() creates a new, empty VipsImage. If you write to one of these images, vips will just attach some callbacks, no pixels will be generated.

Write pixels to an image with vips_image_generate() or vips_image_write_line(). Write a whole image to another image with vips_image_write().

[constructor]

vips_image_new_memory ()

VipsImage *
vips_image_new_memory (void);

vips_image_new_memory() creates a new VipsImage which, when written to, will create a memory image.

See also: vips_image_new().

[skip]

vips_image_memory ()

VipsImage *
vips_image_memory (void);

A renamed vips_image_new_memory() ... Some gobject binding systems do not like more than one _new() method.

See also: vips_image_new_memory().

[constructor]

vips_image_new_from_file ()

VipsImage *
vips_image_new_from_file (const char *name,
                          ...);

Optional arguments:

vips_image_new_from_file() opens name for reading. It can load files in many image formats, including VIPS, TIFF, PNG, JPEG, FITS, Matlab, OpenEXR, CSV, WebP, Radiance, RAW, PPM and others.

Load options may be appended to filename as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename. Many loaders add extra options, see vips_jpegload(), for example.

vips_image_new_from_file() always returns immediately with the header fields filled in. No pixels are actually read until you first access them.

access lets you set a VipsAccess hint giving the expected access pattern for this file. VIPS_ACCESS_RANDOM means you can fetch pixels randomly from the image. This is the default mode. VIPS_ACCESS_SEQUENTIAL means you will read the whole image exactly once, top-to-bottom. In this mode, vips can avoid converting the whole image in one go, for a large memory saving. You are allowed to make small non-local references, so area operations like convolution will work.

In VIPS_ACCESS_RANDOM mode, small images are decompressed to memory and then processed from there. Large images are decompressed to temporary random-access files on disc and then processed from there.

Set memory to TRUE to force loading via memory. The default is to load large random access images via temporary disc files. See vips_image_new_temp_file() for an explanation of how VIPS selects a location for the temporary file.

The disc threshold can be set with the "--vips-disc-threshold" command-line argument, or the VIPS_DISC_THRESHOLD environment variable. The value is a simple integer, but can take a unit postfix of "k", "m" or "g" to indicate kilobytes, megabytes or gigabytes. The default threshold is 100 MB.

For example:

1
2
3

VipsImage *image = vips_image_new_from_file ("fred.tif",
	"page", 12,
	NULL);

Will open "fred.tif", reading page 12.

1
2

VipsImage *image = vips_image_new_from_file ("fred.jpg[shrink=2]",
	NULL);

Will open "fred.jpg", downsampling by a factor of two.

Use vips_foreign_find_load() or vips_foreign_is_a() to see what format a file is in and therefore what options are available. If you need more control over the loading process, you can call loaders directly, see vips_jpegload(), for example.

See also: vips_foreign_find_load(), vips_foreign_is_a(), vips_image_write_to_file().

[constructor]

vips_image_new_from_file_RW ()

VipsImage *
vips_image_new_from_file_RW (const char *filename);

Opens the named file for simultaneous reading and writing. This will only work for VIPS files in a format native to your machine. It is only for paintbox-type applications.

See also: vips_draw_circle().

[constructor]

vips_image_new_from_file_raw ()

VipsImage *
vips_image_new_from_file_raw (const char *filename,
                              int xsize,
                              int ysize,
                              int bands,
                              guint64 offset);

This function maps the named file and returns a VipsImage you can use to read it.

It returns an 8-bit image with bands bands. If the image is not 8-bit, use vips_copy() to transform the descriptor after loading it.

See also: vips_copy(), vips_rawload(), vips_image_new_from_file().

[constructor]

vips_image_new_from_memory ()

VipsImage *
vips_image_new_from_memory (const void *data,
                            size_t size,
                            int width,
                            int height,
                            int bands,
                            VipsBandFormat format);

This function wraps a VipsImage around a memory area. The memory area must be a simple array, for example RGBRGBRGB, left-to-right, top-to-bottom. Use vips_image_new_from_buffer() to load an area of memory containing an image in a format.

VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example “close”.

Because VIPS is "borrowing" data from the caller, this function is extremely dangerous. Unless you are very careful, you will get crashes or memory corruption. Use vips_image_new_from_memory_copy() instead if you are at all unsure.

Use vips_copy() to set other image properties.

See also: vips_image_new(), vips_image_write_to_memory(), vips_image_new_from_memory_copy().

[constructor]

vips_image_new_from_memory_copy ()

VipsImage *
vips_image_new_from_memory_copy (const void *data,
                                 size_t size,
                                 int width,
                                 int height,
                                 int bands,
                                 VipsBandFormat format);

Like vips_image_new_from_memory(), but VIPS will make a copy of the memory area. This means more memory use and an extra copy operation, but is much simpler and safer.

See also: vips_image_new_from_memory().

[constructor]

vips_image_new_from_buffer ()

VipsImage *
vips_image_new_from_buffer (const void *buf,
                            size_t len,
                            const char *option_string,
                            ...);

Loads an image from the formatted area of memory buf , len using the loader recommended by vips_foreign_find_load_buffer(). To load an unformatted area of memory, use vips_image_new_from_memory().

VIPS does not take responsibility for the area of memory, it's up to you to make sure it's freed when the image is closed. See for example “close”.

Load options may be given in option_string as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

See also: vips_image_write_to_buffer().

[constructor]

vips_image_new_from_source ()

VipsImage *
vips_image_new_from_source (VipsSource *source,
                            const char *option_string,
                            ...);

Loads an image from the formatted source input , loader recommended by vips_foreign_find_load_source().

Load options may be given in option_string as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the string.

See also: vips_image_write_to_target().

[constructor]

vips_image_new_matrix ()

VipsImage *
vips_image_new_matrix (int width,
                       int height);

This convenience function makes an image which is a matrix: a one-band VIPS_FORMAT_DOUBLE image held in memory.

Use VIPS_IMAGE_ADDR(), or VIPS_MATRIX() to address pixels in the image.

Use vips_image_set_double() to set "scale" and "offset", if required.

See also: vips_image_new_matrixv()

[constructor]

vips_image_new_matrixv ()

VipsImage *
vips_image_new_matrixv (int width,
                        int height,
                        ...);

As vips_image_new_matrix(), but initialise the matrix from the argument list. After height should be width * height double constants which are used to set the matrix elements.

See also: vips_image_new_matrix()

[constructor]

vips_image_new_matrix_from_array ()

VipsImage *
vips_image_new_matrix_from_array (int width,
                                  int height,
                                  const double *array,
                                  int size);

A binding-friendly version of vips_image_new_matrixv().

[constructor]

vips_image_matrix_from_array ()

VipsImage *
vips_image_matrix_from_array (int width,
                              int height,
                              const double *array,
                              int size);

A renamed vips_image_new_matrix_from_array(). Some gobject bindings do not like more than one _new method.

[skip]

vips_image_new_from_image ()

VipsImage *
vips_image_new_from_image (VipsImage *image,
                           const double *c,
                           int n);

Creates a new image with width, height, format, interpretation, resolution and offset taken from image , but with number of bands taken from n and the value of each band element set from c .

See also: vips_image_new_from_image1()

[constructor]

vips_image_new_from_image1 ()

VipsImage *
vips_image_new_from_image1 (VipsImage *image,
                            double c);

Creates a new image with width, height, format, interpretation, resolution and offset taken from image , but with one band and each pixel having the value c .

See also: vips_image_new_from_image()

[constructor]

vips_image_set_delete_on_close ()

void
vips_image_set_delete_on_close (VipsImage *image,
                                gboolean delete_on_close);

Sets the delete_on_close flag for the image. If this flag is set, when image is finalized, the filename held in image->filename at the time of this call is deleted.

This function is clearly extremely dangerous, use with great caution.

See also: vips_image_new_temp_file().

vips_get_disc_threshold ()

guint64
vips_get_disc_threshold (void);

Return the number of bytes at which we flip between open via memory and open via disc. This defaults to 100mb, but can be changed with the VIPS_DISC_THRESHOLD environment variable or the --vips-disc-threshold command-line flag. See vips_image_new_from_file().

vips_image_new_temp_file ()

VipsImage *
vips_image_new_temp_file (const char *format);

Make a VipsImage which, when written to, will create a temporary file on disc. The file will be automatically deleted when the image is destroyed. format is something like "%s.v" for a vips file.

The file is created in the temporary directory. This is set with the environment variable TMPDIR. If this is not set, then on Unix systems, vips will default to /tmp. On Windows, vips uses GetTempPath() to find the temporary directory.

See also: vips_image_new().

[constructor]

vips_image_write ()

int
vips_image_write (VipsImage *image,
                  VipsImage *out);

Write image to out . Use vips_image_new() and friends to create the VipsImage you want to write to.

See also: vips_image_new(), vips_copy(), vips_image_write_to_file().

vips_image_write_to_file ()

int
vips_image_write_to_file (VipsImage *image,
                          const char *name,
                          ...);

Writes in to name using the saver recommended by vips_foreign_find_save().

Save options may be appended to filename as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

See also: vips_image_new_from_file().

vips_image_write_to_buffer ()

int
vips_image_write_to_buffer (VipsImage *in,
                            const char *suffix,
                            void **buf,
                            size_t *size,
                            ...);

Writes in to a memory buffer in a format specified by suffix .

Save options may be appended to suffix as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

Currently only TIFF, JPEG and PNG formats are supported.

You can call the various save operations directly if you wish, see vips_jpegsave_buffer(), for example.

See also: vips_image_write_to_memory(), vips_image_new_from_buffer().

vips_image_write_to_target ()

int
vips_image_write_to_target (VipsImage *in,
                            const char *suffix,
                            VipsTarget *target,
                            ...);

Writes in to output in format suffix .

Save options may be appended to suffix as "[name=value,...]" or given as a NULL-terminated list of name-value pairs at the end of the arguments. Options given in the function call override options given in the filename.

You can call the various save operations directly if you wish, see vips_jpegsave_target(), for example.

See also: vips_image_write_to_file().

vips_image_write_to_memory ()

void *
vips_image_write_to_memory (VipsImage *in,
                            size_t *size);

Writes in to memory as a simple, unformatted C-style array.

The caller is responsible for freeing this memory with g_free().

See also: vips_image_write_to_buffer().

vips_image_decode_predict ()

int
vips_image_decode_predict (VipsImage *in,
                           int *bands,
                           VipsBandFormat *format);

We often need to know what an image will decode to without actually decoding it, for example, in arg checking.

See also: vips_image_decode().

vips_image_decode ()

int
vips_image_decode (VipsImage *in,
                   VipsImage **out);

A convenience function to unpack to a format that we can compute with. out.coding is always VIPS_CODING_NONE.

This unpacks LABQ to plain LAB. Use vips_LabQ2LabS() for a bit more speed if you need it.

See also: vips_image_encode(), vips_LabQ2Lab(), vips_rad2float().

vips_image_encode ()

int
vips_image_encode (VipsImage *in,
                   VipsImage **out,
                   VipsCoding coding);

A convenience function to pack to a coding. The inverse of vips_image_decode().

See also: vips_image_decode().

vips_image_isMSBfirst ()

gboolean
vips_image_isMSBfirst (VipsImage *image);

Return TRUE if image is in most-significant- byte first form. This is the byte order used on the SPARC architecture and others.

vips_image_isfile ()

gboolean
vips_image_isfile (VipsImage *image);

Return TRUE if image represents a file on disc in some way.

vips_image_ispartial ()

gboolean
vips_image_ispartial (VipsImage *image);

Return TRUE if im represents a partial image (a delayed calculation).

vips_image_hasalpha ()

gboolean
vips_image_hasalpha (VipsImage *image);

Look at an image's interpretation and see if it has extra alpha bands. For example, a 4-band VIPS_INTERPRETATION_sRGB would, but a six-band VIPS_INTERPRETATION_MULTIBAND would not.

Return TRUE if image has an alpha channel.

vips_image_copy_memory ()

VipsImage *
vips_image_copy_memory (VipsImage *image);

This function allocates memory, renders image into it, builds a new image around the memory area, and returns that.

If the image is already a simple area of memory, it just refs image and returns it.

Call this before using the draw operations to make sure you have a memory image that can be modified.

vips_copy() adds a null "copy" node to a pipeline. Use that instead if you want to change metadata and not pixels.

This operation is thread-safe, unlike vips_image_wio_input().

If you are sure that image is not shared with another thread (perhaps you have made it yourself), use vips_image_wio_input() instead.

See also: vips_image_wio_input().

vips_image_wio_input ()

int
vips_image_wio_input (VipsImage *image);

Check that an image is readable via the VIPS_IMAGE_ADDR() macro, that is, that the entire image is in memory and all pixels can be read with VIPS_IMAGE_ADDR(). If it isn't, try to transform it so that VIPS_IMAGE_ADDR() can work.

Since this function modifies image , it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. If the image might have been shared, use the less efficient vips_image_copy_memory() instead.

See also: vips_image_copy_memory(), vips_image_pio_input(), vips_image_inplace(), VIPS_IMAGE_ADDR().

vips_image_pio_input ()

int
vips_image_pio_input (VipsImage *image);

Check that an image is readable with vips_region_prepare() and friends. If it isn't, try to transform the image so that vips_region_prepare() can work.

See also: vips_image_pio_output(), vips_region_prepare().

vips_image_pio_output ()

int
vips_image_pio_output (VipsImage *image);

Check that an image is writeable with vips_image_generate(). If it isn't, try to transform the image so that vips_image_generate() can work.

See also: vips_image_pio_input().

vips_image_inplace ()

int
vips_image_inplace (VipsImage *image);

Gets image ready for an in-place operation, such as vips_draw_circle(). After calling this function you can both read and write the image with VIPS_IMAGE_ADDR().

This method is called for you by the base class of the draw operations, there's no need to call it yourself.

Since this function modifies image , it is not thread-safe. Only call it on images which you are sure have not been shared with another thread. All in-place operations are inherently not thread-safe, so you need to take great care in any case.

See also: vips_draw_circle(), vips_image_wio_input().

vips_image_write_prepare ()

int
vips_image_write_prepare (VipsImage *image);

Call this after setting header fields (width, height, and so on) to allocate resources ready for writing.

Normally this function is called for you by vips_image_generate() or vips_image_write_line(). You will need to call it yourself if you plan to write directly to the ->data member of a memory image.

vips_image_write_line ()

int
vips_image_write_line (VipsImage *image,
                       int ypos,
                       VipsPel *linebuffer);

Write a line of pixels to an image. This function must be called repeatedly with ypos increasing from 0 to “height” . linebuffer must be VIPS_IMAGE_SIZEOF_LINE() bytes long.

See also: vips_image_generate().

vips_band_format_isint ()

gboolean
vips_band_format_isint (VipsBandFormat format);

Return TRUE if format is one of the integer types.

vips_band_format_isuint ()

gboolean
vips_band_format_isuint (VipsBandFormat format);

Return TRUE if format is one of the unsigned integer types.

vips_band_format_is8bit ()

gboolean
vips_band_format_is8bit (VipsBandFormat format);

Return TRUE if format is uchar or schar.

vips_band_format_isfloat ()

gboolean
vips_band_format_isfloat (VipsBandFormat format);

Return TRUE if format is one of the float types.

vips_band_format_iscomplex ()

gboolean
vips_band_format_iscomplex (VipsBandFormat format);

Return TRUE if fmt is one of the complex types.

vips_system ()

int
vips_system (const char *cmd_format,
             ...);

Optional arguments:

vips_system() runs a command, optionally passing a set of images in and optionally getting an image back. The command's stdout is returned in log .

First, if in is set, the array of images are written to files. See vips_image_new_temp_file() to see how temporary files are created. If in_format is something like %s.png, the file will be written in PNG format. By default, in_format is %s.tif.

If out_format is set, an output filename is formed in the same way. Any trailing [options] are stripped from out_format .

The command string to run is made by substituting the first set of %s in cmd_format for the names of the input files, if in is set, and then the next %s for the output filename, if out_format is set. You can put a number between the % and the s to change the order in which the substitution occurs.

The command is executed with popen() and the output captured in log .

After the command finishes, if out_format is set, the output image is opened and returned in out . You can append [options] to out_format to control how this open happens. Closing out image will automatically delete the output file.

Finally the input images are deleted.

For example, this call will run the ImageMagick convert program on an image, using JPEG files to pass images into and out of the convert command.

1
2
3
4
5
6
7
8
9
10
11
12

VipsArrayImage *in;
VipsImage *out;
char *log;

if (vips_system ("convert %s -swirl 45 %s",
	"in", in, 
	"out", &out, 
  	"in_format", "%s.jpg", 
  	"out_format", "%s.jpg", 
  	"log", &log,
  	NULL))
  	error ...

vips_array_image_new ()

VipsArrayImage *
vips_array_image_new (VipsImage **array,
                      int n);

Allocate a new array of images and copy array into it. Free with vips_area_unref().

The images will all be reffed by this function. They will be automatically unreffed for you by vips_area_unref().

Add an extra NULL element at the end, handy for eg. vips_image_pipeline_array() etc.

See also: VipsArea.

[constructor]

vips_array_image_newv ()

VipsArrayImage *
vips_array_image_newv (int n,
                       ...);

Allocate a new array of n VipsImage and copy @... into it. Free with vips_area_unref().

The images will all be reffed by this function. They will be automatically unreffed for you by vips_area_unref().

Add an extra NULL element at the end, handy for eg. vips_image_pipeline_array() etc.

See also: vips_array_image_new()

[constructor]

vips_array_image_new_from_string ()

VipsArrayImage *
vips_array_image_new_from_string (const char *string,
                                  VipsAccess flags);

vips_array_image_empty ()

VipsArrayImage *
vips_array_image_empty (void);

Make an empty image array. Handy with vips_array_image_add() for bindings which can't handle object array arguments.

See also: vips_array_image_add().

[constructor]

vips_array_image_append ()

VipsArrayImage *
vips_array_image_append (VipsArrayImage *array,
                         VipsImage *image);

Make a new VipsArrayImage, one larger than array , with image appended to the end. Handy with vips_array_image_empty() for bindings which can't handle object array arguments.

See also: vips_array_image_empty().

vips_array_image_get ()

VipsImage **
vips_array_image_get (VipsArrayImage *array,
                      int *n);

Fetch an image array from a VipsArrayImage. Useful for language bindings.

vips_value_get_array_image ()

VipsImage **
vips_value_get_array_image (const GValue *value,
                            int *n);

Return the start of the array of images held by value . optionally return the number of elements in n .

See also: vips_value_set_array_image().

vips_value_set_array_image ()

void
vips_value_set_array_image (GValue *value,
                            int n);

Set value to hold an array of images. Pass in the array length in n .

See also: vips_array_image_get().

vips_reorder_prepare_many ()

int
vips_reorder_prepare_many (VipsImage *image,
                           VipsRegion **regions,
                           VipsRect *r);

vips_reorder_prepare_many() runs vips_region_prepare() on each region in regions , requesting the pixels in r .

It tries to request the regions in the order which will cause least recomputation. This can give a large speedup, in some cases.

See also: vips_region_prepare(), vips_reorder_margin_hint().

[method]

vips_reorder_margin_hint ()

void
vips_reorder_margin_hint (VipsImage *image,
                          int margin);

vips_reorder_margin_hint() sets a hint that image contains a margin, that is, that each vips_region_prepare() on image will request a slightly larger region from it's inputs. A good value for margin is (width * height) for the window the operation uses.

This information is used by vips_image_prepare_many() to attempt to reorder computations to minimise recomputation.

See also: vips_image_prepare_many().

[method]

vips_image_free_buffer ()

void
vips_image_free_buffer (VipsImage *image,
                        void *buffer);

Free the externally allocated buffer found in the input image. This function is intended to be used with g_signal_connect.

VIPS_MAGIC_INTEL

#define VIPS_MAGIC_INTEL (0xb6a6f208U)

The first four bytes of a VIPS file in Intel byte ordering.

VIPS_MAGIC_SPARC

#define VIPS_MAGIC_SPARC (0x08f2a6b6U)

The first four bytes of a VIPS file in SPARC byte ordering.

VIPS_MAX_COORD

#define VIPS_MAX_COORD (10000000)

enum VipsDemandStyle

See vips_image_pipelinev(). Operations can hint to the VIPS image IO system about the kind of demand geometry they prefer.

These demand styles are given below in order of increasing restrictiveness. When demanding output from a pipeline, vips_image_generate() will use the most restrictive of the styles requested by the operations in the pipeline.

VIPS_DEMAND_STYLE_THINSTRIP --- This operation would like to output strips the width of the image and a few pels high. This is option suitable for point-to-point operations, such as those in the arithmetic package.

This option is only efficient for cases where each output pel depends upon the pel in the corresponding position in the input image.

VIPS_DEMAND_STYLE_FATSTRIP --- This operation would like to output strips the width of the image and as high as possible. This option is suitable for area operations which do not violently transform coordinates, such as vips_conv().

VIPS_DEMAND_STYLE_SMALLTILE --- This is the most general demand format. Output is demanded in small (around 100x100 pel) sections. This style works reasonably efficiently, even for bizzare operations like 45 degree rotate.

VIPS_DEMAND_STYLE_ANY --- This image is not being demand-read from a disc file (even indirectly) so any demand style is OK. It's used for things like vips_black() where the pixels are calculated.

See also: vips_image_pipelinev().

enum VipsImageType

enum VipsInterpretation

How the values in an image should be interpreted. For example, a three-band float image of type VIPS_INTERPRETATION_LAB should have its pixels interpreted as coordinates in CIE Lab space.

RGB and sRGB are treated in the same way. Use the colourspace functions if you want some other behaviour.

The gaps in numbering are historical and must be maintained. Allocate new numbers from the end.

enum VipsBandFormat

The format used for each band element.

Each corresponds to a native C type for the current machine. For example, VIPS_FORMAT_USHORT is unsigned short.

enum VipsCoding

How pixels are coded.

Normally, pixels are uncoded and can be manipulated as you would expect. However some file formats code pixels for compression, and sometimes it's useful to be able to manipulate images in the coded format.

The gaps in the numbering are historical and must be maintained. Allocate new numbers from the end.

enum VipsAccess

The type of access an operation has to supply. See vips_tilecache() and VipsForeign.

VIPS_ACCESS_RANDOM means requests can come in any order.

VIPS_ACCESS_SEQUENTIAL means requests will be top-to-bottom, but with some amount of buffering behind the read point for small non-local accesses.

VipsProgress

typedef struct {
	int run;		/* Time we have been running */
	int eta;		/* Estimated seconds of computation left */
	gint64 tpels;		/* Number of pels we expect to calculate */
	gint64 npels;		/* Number of pels calculated so far */
	int percent;		/* Percent complete */
	GTimer *start;		/* Start time */
} VipsProgress;

A structure available to eval callbacks giving information on evaluation progress. See “eval”.

The “bands” property

  “bands”                    int

Number of bands in image.

Owner: VipsImage

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1

The “coding” property

  “coding”                   VipsCoding

Pixel coding.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_CODING_NONE

The “demand” property

  “demand”                   VipsDemandStyle

Preferred demand style for this image.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_DEMAND_STYLE_SMALLTILE

The “filename” property

  “filename”                 char *

Image filename.

Owner: VipsImage

Flags: Read / Write

Default value: NULL

The “foreign-buffer” property

  “foreign-buffer”           gpointer

Pointer to foreign pixels.

Owner: VipsImage

Flags: Read / Write

The “format” property

  “format”                   VipsBandFormat

Pixel format in image.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_FORMAT_UCHAR

The “height” property

  “height”                   int

Image height in pixels.

Owner: VipsImage

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1

The “interpretation” property

  “interpretation”           VipsInterpretation

Pixel interpretation.

Owner: VipsImage

Flags: Read / Write

Default value: VIPS_INTERPRETATION_MULTIBAND

The “kill” property

  “kill”                     gboolean

Block evaluation on this image.

Owner: VipsImage

Flags: Read / Write

Default value: FALSE

The “mode” property

  “mode”                     char *

Open mode.

Owner: VipsImage

Flags: Read / Write

Default value: "p"

The “sizeof-header” property

  “sizeof-header”            guint64

Offset in bytes from start of file.

Owner: VipsImage

Flags: Read / Write

Allowed values: <= 1000000000

Default value: 64

The “width” property

  “width”                    int

Image width in pixels.

Owner: VipsImage

Flags: Read / Write

Allowed values: [1,10000000]

Default value: 1

The “xoffset” property

  “xoffset”                  int

Horizontal offset of origin.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-10000000,10000000]

Default value: 0

The “xres” property

  “xres”                     double

Horizontal resolution in pixels/mm.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-0,1e+06]

Default value: 0

The “yoffset” property

  “yoffset”                  int

Vertical offset of origin.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-10000000,10000000]

Default value: 0

The “yres” property

  “yres”                     double

Vertical resolution in pixels/mm.

Owner: VipsImage

Flags: Read / Write

Allowed values: [-0,1e+06]

Default value: 0

The “eval” signal

void
user_function (VipsImage *image,
               gpointer   progress,
               gpointer   user_data)

The ::eval signal is emitted once per work unit (typically a 128 x 128 area of pixels) during image computation.

You can use this signal to update user-interfaces with progress feedback. Beware of updating too frequently: you will usually need some throttling mechanism.

Use vips_image_set_progress() to turn on progress reporting for an image.

Flags: Run Last

The “invalidate” signal

void
user_function (VipsImage *image,
               gpointer   user_data)

The ::invalidate signal is emitted when an image or one of it's upstream data sources has been destructively modified. See vips_image_invalidate_all().

Flags: Action

The “minimise” signal

void
user_function (VipsImage *image,
               gpointer   user_data)

The ::minimise signal is emitted when an image has been asked to minimise memory usage. All non-essential caches are dropped. See vips_image_minimise_all().

Flags: Action

The “posteval” signal

void
user_function (VipsImage *image,
               gpointer   progress,
               gpointer   user_data)

The ::posteval signal is emitted once at the end of the computation of image . It's a good place to shut down evaluation feedback.

Use vips_image_set_progress() to turn on progress reporting for an image.

Flags: Run Last

The “preeval” signal

void
user_function (VipsImage *image,
               gpointer   progress,
               gpointer   user_data)

The ::preeval signal is emitted once before computation of image starts. It's a good place to set up evaluation feedback.

Use vips_image_set_progress() to turn on progress reporting for an image.

Flags: Run Last

The “written” signal

void
user_function (VipsImage *image,
               gpointer   result,
               gpointer   user_data)

The ::written signal is emitted just after an image has been written to. It is used by vips to implement things like write to foreign file formats.

Flags: Action