![]() |
![]() |
![]() |
VIPS Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties | Signals |
#include <vips/vips.h> #define VIPS_IMAGE_ADDR (I, X, Y) #define VIPS_IMAGE_N_ELEMENTS (I) #define VIPS_IMAGE_N_PELS (I) #define VIPS_IMAGE_SIZEOF_ELEMENT (I) #define VIPS_IMAGE_SIZEOF_LINE (I) #define VIPS_IMAGE_SIZEOF_PEL (I) #define VIPS_MAGIC_INTEL #define VIPS_MAGIC_SPARC enum VipsBandFormat; enum VipsCoding; enum VipsDemandStyle; VipsImage; VipsImageClass; enum VipsImageType; enum VipsInterpretation; VipsProgress; gboolean vips_band_format_iscomplex (VipsBandFormat format
); gboolean vips_band_format_isfloat (VipsBandFormat format
); gboolean vips_band_format_isint (VipsBandFormat format
); gboolean vips_band_format_isuint (VipsBandFormat format
); void vips_image_eval (VipsImage *image
,guint64 processed
); int vips_image_inplace (VipsImage *image
); void vips_image_invalidate_all (VipsImage *image
); gboolean vips_image_isMSBfirst (VipsImage *image
); gboolean vips_image_isfile (VipsImage *image
); gboolean vips_image_iskilled (VipsImage *image
); gboolean vips_image_ispartial (VipsImage *image
); void vips_image_minimise_all (VipsImage *image
); VipsImage * vips_image_new (void
); VipsImage * vips_image_new_array (int xsize
,int ysize
); VipsImage * vips_image_new_buffer (void
); VipsImage * vips_image_new_disc_temp (const char *format
); VipsImage * vips_image_new_from_file (const char *filename
); VipsImage * vips_image_new_from_file_raw (const char *filename
,int xsize
,int ysize
,int bands
,guint64 offset
); VipsImage * vips_image_new_from_memory (void *buffer
,int xsize
,int ysize
,int bands
,VipsBandFormat bandfmt
); VipsImage * vips_image_new_mode (const char *filename
,const char *mode
); int vips_image_pio_input (VipsImage *image
); void vips_image_posteval (VipsImage *image
); void vips_image_preeval (VipsImage *image
); void vips_image_set_delete_on_close (VipsImage *image
,gboolean delete_on_close
); void vips_image_set_kill (VipsImage *image
,gboolean kill
); void vips_image_set_progress (VipsImage *image
,gboolean progress
); int vips_image_wio_input (VipsImage *image
); int vips_image_write (VipsImage *image
,VipsImage *out
); int vips_image_write_line (VipsImage *image
,int ypos
,VipsPel *linebuffer
); int vips_image_write_prepare (VipsImage *image
); int vips_image_write_to_file (VipsImage *image
,const char *filename
); int vips_image_written (VipsImage *image
);
GEnum +----VipsBandFormat
GEnum +----VipsCoding
GEnum +----VipsDemandStyle
GObject +----VipsObject +----VipsImage
GEnum +----VipsImageType
GEnum +----VipsInterpretation
"bands" gint : Read / Write "coding" VipsCoding : Read / Write "demand" VipsDemandStyle : Read / Write "filename" gchar* : Read / Write "foreign-buffer" gpointer : Read / Write "format" VipsBandFormat : Read / Write "height" gint : Read / Write "interpretation" VipsInterpretation : Read / Write "kill" gboolean : Read / Write "mode" gchar* : Read / Write "sizeof-header" guint64 : Read / Write "width" gint : Read / Write "xoffset" gint : Read / Write "xres" gdouble : Read / Write "yoffset" gint : Read / Write "yres" gdouble : Read / Write
"eval" :Run Last
"invalidate" :Action
"minimise" :Action
"posteval" :Run Last
"preeval" :Run Last
"written" :Action
The image class and associated types and macros.
vips_image_wio_input()
and friends indicate the image IO style you
intend to use, transforming the underlying VipsImage structure if
necessary.
#define VIPS_IMAGE_ADDR( I, X, Y )
This macro returns a pointer to a pixel in an image. 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_REGION_ADDR()
.
|
a VipsImage |
|
x coordinate |
|
y coordinate |
Returns : |
The address of pixel (x,y) in the image. |
#define VIPS_IMAGE_N_ELEMENTS( I )
|
a VipsImage |
Returns : |
The number of band elements in a scanline. |
#define VIPS_IMAGE_N_PELS( I )
|
a VipsImage |
Returns : |
The number of pels in an image. A 64-bit unsigned int. |
#define VIPS_IMAGE_SIZEOF_ELEMENT( I )
|
a VipsImage |
Returns : |
sizeof() a band element. |
#define VIPS_IMAGE_SIZEOF_LINE( I )
|
a VipsImage |
Returns : |
sizeof() a scanline of pixels. |
#define VIPS_IMAGE_SIZEOF_PEL( I )
|
a VipsImage |
Returns : |
sizeof() a pixel. |
#define VIPS_MAGIC_INTEL (0xb6a6f208U)
The first four bytes of a VIPS file in Intel byte ordering.
#define VIPS_MAGIC_SPARC (0x08f2a6b6U)
The first four bytes of a VIPS file in SPARC byte ordering.
typedef enum { VIPS_FORMAT_NOTSET = -1, VIPS_FORMAT_UCHAR = 0, VIPS_FORMAT_CHAR = 1, VIPS_FORMAT_USHORT = 2, VIPS_FORMAT_SHORT = 3, VIPS_FORMAT_UINT = 4, VIPS_FORMAT_INT = 5, VIPS_FORMAT_FLOAT = 6, VIPS_FORMAT_COMPLEX = 7, VIPS_FORMAT_DOUBLE = 8, VIPS_FORMAT_DPCOMPLEX = 9, VIPS_FORMAT_LAST = 10 } VipsBandFormat;
The format used for each band element.
Each corresponnds to a native C type for the current machine. For example, VIPS_FORMAT_USHORT is unsigned short.
invalid setting | |
unsigned char format | |
char format | |
unsigned short format | |
short format | |
unsigned int format | |
int format | |
float format | |
complex (two floats) format | |
double float format | |
double complex (two double) format | |
typedef enum { VIPS_CODING_ERROR = -1, VIPS_CODING_NONE = 0, VIPS_CODING_LABQ = 2, VIPS_CODING_RAD = 6, VIPS_CODING_LAST = 7 } 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.
typedef enum { VIPS_DEMAND_STYLE_ERROR = -1, VIPS_DEMAND_STYLE_SMALLTILE, VIPS_DEMAND_STYLE_FATSTRIP, VIPS_DEMAND_STYLE_THINSTRIP, VIPS_DEMAND_STYLE_ANY } VipsDemandStyle;
See vips_demand_hint()
. 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 im_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
im_black()
where the pixels are calculated.
See also: vips_demand_hint()
.
demand in small (typically 64x64 pixel) tiles | |
demand in fat (typically 10 pixel high) strips | |
demand in thin (typically 1 pixel high) strips | |
demand geometry does not matter |
typedef struct _VipsImage VipsImage;
An image. These can represent an image on disc, a memory buffer, an image in the process of being written to disc or a partially evaluated image in memory.
typedef struct { VipsObjectClass parent_class; /* Signals we emit. */ /* Evaluation is starting. */ void (*preeval)( VipsImage *image, VipsProgress *progress ); /* Evaluation progress. */ void (*eval)( VipsImage *image, VipsProgress *progress ); /* Evaluation is ending. */ void (*posteval)( VipsImage *image, VipsProgress *progress ); /* An image has been written to. * Used by eg. vips_image_new_mode("x.jpg", "w") to do the * final write to jpeg. * Set *result to non-zero to indicate an error on write. */ void (*written)( VipsImage *image, int *result ); /* An image has been modified in some way and all caches * need dropping. */ void (*invalidate)( VipsImage *image ); /* Minimise this pipeline. * * This is triggered (sometimes) at the end of eval to signal that * we're probably done and that operations involved should try to * minimise memory use by, for example, dropping caches. * * See vips_tilecache(). */ void (*minimise)( VipsImage *image ); } VipsImageClass;
typedef enum { VIPS_IMAGE_ERROR = -1, VIPS_IMAGE_NONE, /* no type set */ VIPS_IMAGE_SETBUF, /* malloced memory array */ VIPS_IMAGE_SETBUF_FOREIGN, /* memory array, don't free on close */ VIPS_IMAGE_OPENIN, /* input from fd with a window */ VIPS_IMAGE_MMAPIN, /* memory mapped input file */ VIPS_IMAGE_MMAPINRW, /* memory mapped read/write file */ VIPS_IMAGE_OPENOUT, /* output to fd */ VIPS_IMAGE_PARTIAL /* partial image */ } VipsImageType;
typedef enum { VIPS_INTERPRETATION_ERROR = -1, VIPS_INTERPRETATION_MULTIBAND = 0, VIPS_INTERPRETATION_B_W = 1, VIPS_INTERPRETATION_HISTOGRAM = 10, VIPS_INTERPRETATION_XYZ = 12, VIPS_INTERPRETATION_LAB = 13, VIPS_INTERPRETATION_CMYK = 15, VIPS_INTERPRETATION_LABQ = 16, VIPS_INTERPRETATION_RGB = 17, VIPS_INTERPRETATION_CMC = 18, VIPS_INTERPRETATION_LCH = 19, VIPS_INTERPRETATION_LABS = 21, VIPS_INTERPRETATION_sRGB = 22, VIPS_INTERPRETATION_YXY = 23, VIPS_INTERPRETATION_FOURIER = 24, VIPS_INTERPRETATION_RGB16 = 25, VIPS_INTERPRETATION_GREY16 = 26, VIPS_INTERPRETATION_ARRAY = 27, VIPS_INTERPRETATION_scRGB = 28 } 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 the numbering are historical and must be maintained. Allocate new numbers from the end.
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 | |
an array | |
pixels are scRGB |
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".
gboolean vips_band_format_iscomplex (VipsBandFormat format
);
Return TRUE
if fmt
is one of the complex types.
|
format to test |
gboolean vips_band_format_isfloat (VipsBandFormat format
);
Return TRUE
if format
is one of the float types.
|
format to test |
gboolean vips_band_format_isint (VipsBandFormat format
);
Return TRUE
if format
is one of the integer types.
|
format to test |
gboolean vips_band_format_isuint (VipsBandFormat format
);
Return TRUE
if format
is one of the unsigned integer types.
|
format to test |
int vips_image_inplace (VipsImage *image
);
Gets image
ready for an in-place operation, such as im_insertplace()
.
After calling this function you can both read and write the image with
VIPS_IMAGE_ADDR()
.
See also: im_insertplace()
, vips_image_wio_input()
.
|
image to make read-write |
Returns : |
0 on succeess, or -1 on error. |
void vips_image_invalidate_all (VipsImage *image
);
Invalidate all pixel caches on an image
and any downstream images, that
is, images which depend on this image.
The "invalidate" callback is triggered for all invalidated images.
|
VipsImage to invalidate |
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.
|
image to test |
gboolean vips_image_isfile (VipsImage *image
);
Return TRUE
if image
represents a file on disc in some way.
|
image to test |
gboolean vips_image_ispartial (VipsImage *image
);
Return TRUE
if im
represents a partial image (a delayed calculation).
|
image to test |
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.
The "minimise" callback is triggered for all minimised images.
|
VipsImage to minimise |
VipsImage * vips_image_new (void
);
vips_image_new()
creates a "glue" descriptor you can use to join two image
processing operations together.
It is the equivalent of vips_image_new_mode("xxx", "p").
Returns : |
the new VipsImage, or NULL on error. |
VipsImage * vips_image_new_array (int xsize
,int ysize
);
This convenience function makes an image which is an array: a one-band VIPS_FORMAT_DOUBLE image held in memory.
Use VIPS_IMAGE_ADDR()
to address pixels in the image.
|
image width |
|
image height |
Returns : |
the new VipsImage, or NULL on error. |
VipsImage * vips_image_new_buffer (void
);
vips_image_new_buffer()
creates a new VipsImage which when written to will
create a memory buffer. It is a convenience function for
vips_image_new_mode(vips_image_temp_name()
, "t").
See also: vips_image_new()
.
Returns : |
the new VipsImage, or NULL on error. |
VipsImage * vips_image_new_disc_temp (const char *format
);
Make a "w" disc VipsImage which will be automatically unlinked when it is
destroyed. format
is something like "s
.v" for a vips file.
The file is created in the temporary directory, see vips__temp_name()
.
See also: vips__temp_name()
.
|
format of file |
Returns : |
the new VipsImage, or NULL on error. |
VipsImage * vips_image_new_from_file (const char *filename
);
vips_image_new_from_file()
opens filename
for reading in mode "r". See
vips_image_new_mode()
for details.
See also: vips_image_new_mode()
.
|
file to open |
Returns : |
the new VipsImage, or NULL on error. |
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
im_copy_set()
to transform the descriptor after loading it.
See also: im_copy_set()
, im_raw2vips()
, vips_image_new_from_file()
.
|
filename to open |
|
image width |
|
image height |
|
image bands (or bytes per pixel) |
|
bytes to skip at start of file |
Returns : |
the new VipsImage, or NULL on error. |
VipsImage * vips_image_new_from_memory (void *buffer
,int xsize
,int ysize
,int bands
,VipsBandFormat bandfmt
);
This function wraps an IMAGE around a memory buffer. 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".
See also: im_binfile()
, im_raw2vips()
, vips_image_new()
.
|
start of memory area |
|
image width |
|
image height |
|
image bands (or bytes per pixel) |
|
image format |
Returns : |
the new VipsImage, or NULL on error. |
VipsImage * vips_image_new_mode (const char *filename
,const char *mode
);
vips_image_new_mode()
examines the mode string and creates an
appropriate VipsImage.
"t" creates a temporary memory buffer image.
"p"
creates a "glue" descriptor you can use to join operations, see also
vips_image_new()
.
"r"
opens the named file for reading. If the file is not in the native
VIPS format for your machine, vips_image_new_mode()
automatically converts the file for you.
Some formats (eg. tiled tiff) are read directly.
Some formats (eg. strip tiff) do not support random access and can't be processed directly. Small images are decompressed to memory and loaded from there, large images are decompressed to a disc file and processed from that.
If the operations you intend to perform are sequential, that is, they operate in a strict top-to-bottom manner, you can use sequential mode instead, see "rs" below, or you can use the lower-level API and control the loading process yourself. See VipsForeign.
See im_system_image()
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 IM_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.
For example:
1 2 3 4 |