Top |
Functions
Properties
gint | bands | Read / Write |
VipsCoding | coding | Read / Write |
VipsDemandStyle | demand | Read / Write |
gchar * | filename | Read / Write |
gpointer | foreign-buffer | Read / Write |
VipsBandFormat | format | Read / Write |
gint | height | Read / Write |
VipsInterpretation | interpretation | Read / Write |
gboolean | kill | Read / Write |
gchar * | mode | Read / Write |
guint64 | sizeof-header | Read / Write |
gint | width | Read / Write |
gint | xoffset | Read / Write |
gdouble | xres | Read / Write |
gint | yoffset | Read / Write |
gdouble | yres | Read / Write |
Types and Values
enum | VipsDemandStyle |
enum | VipsImageType |
enum | VipsInterpretation |
enum | VipsBandFormat |
enum | VipsCoding |
enum | VipsAccess |
VipsProgress |
Description
The image class and associated types and macros.
Images can be created from formatted files on disc, from C-style arrays on
disc, from formatted areas of memory, or from C-style arrays in memory. See
vips_image_new_from_file()
and friends.
Creating an image is fast. VIPS reads just enough of
the image to be able to get the various properties, such as width in
pixels. It delays reading any pixels until they are really needed.
Once you have an image, you can get properties from it in the usual way.
You can use projection functions, like vips_image_get_width()
or
g_object_get()
, to get GObject
properties.
VIPS images are three-dimensional arrays, the dimensions being width,
height and bands. Each dimension can be up to 2 ** 31 pixels (or band
elements). An image has a format, meaning the machine number type used
to represent each value. VIPS supports 10 formats, from 8-bit unsigned
integer up to 128-bit double complex, see vips_image_get_format()
.
In VIPS, images are uninterpreted arrays, meaning that from the point of view of most operations, they are just large collections of numbers. There's no difference between an RGBA (RGB with alpha) image and a CMYK image, for example, they are both just four-band images. It's up to the user of the library to pass the right sort of image to each operation.
To take an example, VIPS has vips_Lab2XYZ()
, an operation to transform
an image from CIE LAB colour space to CIE XYZ space. It assumes the
first three bands represent pixels in LAB colour space and returns an
image where the first three bands are transformed to XYZ and any
remaining bands are just copied. Pass it a RGB image by mistake and
you'll just get nonsense.
VIPS has a feature to help (a little) with this: it sets a
VipsInterpretation hint for each image (see
vips_image_get_interpretation()
); a hint which says how pixels should
be interpreted. For example, vips_Lab2XYZ()
will set the
interpretation of the output image to VIPS_INTERPRETATION_XYZ. A
few utility operations will also use interpretation as a guide. For
example, you can give vips_colourspace()
an input image and a desired
colourspace and it will use the input's interpretation hint to apply
the best sequence of colourspace transforms to get to the desired space.
Use things like vips_invert()
to manipulate your images. When you are done,
you can write images to disc files (with vips_image_write_to_file()
),
to formatted memory buffers (with vips_image_write_to_buffer()
) and to
C-style memory arrays (with vips_image_write_to_memory()
.
You can also write image to other images. Create, for example, a temporary
disc image with vips_image_new_temp_file()
, then write your image to that
with vips_image_write()
. You can create several other types of image and
write to them, see vips_image_new_memory()
, for example.
See operation for an introduction to running operations on images, see header for getting and setting image metadata. See object for a discussion of the lower levels.
Functions
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_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_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_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_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()
.
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()
.
vips_image_new_from_file ()
VipsImage * vips_image_new_from_file (const char *name
,...
);
Optional arguments:
access
: hint VipsAccess mode to loader
disc
: load via a temporary disc file
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. VIPS_ACCESS_SEQUENTIAL_UNBUFFERED does not allow
non-local references, so will only work for very strict top-to-bottom
operations, but does have very low memory needs.
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 disc
to
TRUE
to force loading via disc. 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()
.
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()
.
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()
.
vips_image_new_from_memory ()
VipsImage * vips_image_new_from_memory (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”.
Use vips_copy()
to set other image properties.
See also: vips_image_new()
, vips_image_write_to_memory()
.
vips_image_new_from_buffer ()
VipsImage * vips_image_new_from_buffer (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()
. Only TIFF, PNG and
JPEG formats are supported. 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()
.
Parameters
buf |
start of memory buffer |
|
len |
length of memory buffer |
|
option_string |
set of extra options as a string |
|
... |
|
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()
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()
vips_image_new_matrix_from_array ()
VipsImage * vips_image_new_matrix_from_array (int width
,int height
,double *array
,int size
);
A binding-friendly version of vips_image_new_matrixv()
.
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.
vips uses g_mkstemp()
to make the temporary filename. They generally look
something like "vips-12-EJKJFGH.v".
See also: vips_image_new()
.
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()
.
Parameters
image |
image to write |
|
name |
write to this 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()
.
Parameters
in |
image to write |
|
suffix |
format to write |
|
buf |
return buffer start here. |
[array length=size][element-type guint8][transfer full] |
size |
return buffer length here |
|
... |
|
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.
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_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.
See also: 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()
.
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:
in
: array of input images
out
: output image
in_format
: write input files like this
out_format
: write output filename like this
log
: stdout of command is returned here
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.
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
.
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.
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()
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()
.
Types and Values
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 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.
These values are set by operations as hints to user-interfaces built on top of VIPS to help them show images to the user in a meaningful way. Operations do not use these values to decide their action.
The gaps in numbering are historical and must be maintained. Allocate new numbers from the end.
Members
generic many-band image |
||
some kind of single-band image |
||
a 1D image, eg. histogram or lookup table |
||
the first three bands are CIE XYZ |
||
pixels are in CIE Lab space |
||
the first four bands are in CMYK space |
||
implies VIPS_CODING_LABQ |
||
generic RGB space |
||
a uniform colourspace based on CMC(1:1) |
||
pixels are in CIE LCh space |
||
CIE LAB coded as three signed 16-bit values |
||
pixels are sRGB |
||
pixels are CIE Yxy |
||
image is in fourier space |
||
generic 16-bit RGB |
||
generic 16-bit mono |
||
a matrix |
||
pixels are scRGB |
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.
VIPS_ACCESS_SEQUENTIAL_UNBUFFERED
means requests will be strictly
top-to-bottom with no read-behind. This can save some memory.
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”.
Property Details
The “bands”
property
“bands” gint
Number of bands in image.
Flags: Read / Write
Allowed values: [1,1000000000]
Default value: 1
The “coding”
property
“coding” VipsCoding
Pixel coding.
Flags: Read / Write
Default value: VIPS_CODING_NONE
The “demand”
property
“demand” VipsDemandStyle
Preferred demand style for this image.
Flags: Read / Write
Default value: VIPS_DEMAND_STYLE_SMALLTILE
The “foreign-buffer”
property
“foreign-buffer” gpointer
Pointer to foreign pixels.
Flags: Read / Write
The “format”
property
“format” VipsBandFormat
Pixel format in image.
Flags: Read / Write
Default value: VIPS_FORMAT_UCHAR
The “height”
property
“height” gint
Image height in pixels.
Flags: Read / Write
Allowed values: [1,1000000000]
Default value: 1
The “interpretation”
property
“interpretation” VipsInterpretation
Pixel interpretation.
Flags: Read / Write
Default value: VIPS_INTERPRETATION_MULTIBAND
The “kill”
property
“kill” gboolean
Block evaluation on this image.
Flags: Read / Write
Default value: FALSE
The “sizeof-header”
property
“sizeof-header” guint64
Offset in bytes from start of file.
Flags: Read / Write
Allowed values: <= 1000000
Default value: 64
The “width”
property
“width” gint
Image width in pixels.
Flags: Read / Write
Allowed values: [1,1000000000]
Default value: 1
The “xoffset”
property
“xoffset” gint
Horizontal offset of origin.
Flags: Read / Write
Allowed values: [-1000000,1000000]
Default value: 0
The “xres”
property
“xres” gdouble
Horizontal resolution in pixels/mm.
Flags: Read / Write
Allowed values: [-0,1e+06]
Default value: 0
The “yoffset”
property
“yoffset” gint
Vertical offset of origin.
Flags: Read / Write
Allowed values: [-1000000,1000000]
Default value: 0
The “yres”
property
“yres” gdouble
Vertical resolution in pixels/mm.
Flags: Read / Write
Allowed values: [-0,1e+06]
Default value: 0
Signal Details
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.
Parameters
image |
the image being calculated |
|
progress |
VipsProgress for this image |
|
user_data |
user data set when the signal handler was connected. |
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()
.
Parameters
image |
the image that has changed |
|
user_data |
user data set when the signal handler was connected. |
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()
.
Parameters
image |
the image that is being minimised |
|
user_data |
user data set when the signal handler was connected. |
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.
Parameters
image |
the image that was calculated |
|
progress |
VipsProgress for this image |
|
user_data |
user data set when the signal handler was connected. |
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.
Parameters
image |
the image to be calculated |
|
progress |
VipsProgress for this image |
|
user_data |
user data set when the signal handler was connected. |
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.
Parameters
image |
the image that was calculated |
|
result |
set to non-zero to indicate error |
|
user_data |
user data set when the signal handler was connected. |
Flags: Action