sergiotarxz/libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge branch 'master' of github.com:jcupitt/libvips

Browse Source
This commit is contained in:
John Cupitt 2014-08-27 13:58:48 +01:00
commit e6401448d4
31 changed files with 288 additions and 199 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

@ -7,6 +7,7 @@
- more doc fixes
- fix similarity rotate+scale, thanks Topochicho
- fix 16-bit PNG save, thanks John
- fix dzsave date on Windows, thanks John
25/7/14 started 7.40.5
- fix a race in im_maxpos_avg()

11
TODO
View File

@ -1,18 +1,17 @@
- can we pick the vipsthumbnail int shrink factor more intelligently?
- vips_resize() should use vipsthumbnail's block/cache/affine/sharpen chain
- vips_object_unref_outputs() needs docs ... bindings will need it
- rewrite im_conv() etc. as vips_conv()
finally finish --disable-deprecated option
- vips_object_unref_outputs() needs docs ... bindings will need it
- vips_init() has a deprecation warning, bizarre
- vips_affine() for simple resize is slow at the command-line, since it has to
be non-seq ... make a seq version that can only up/down size
- where should we explain VIPS_IMAGE_ADDR(), VIPS_REGION_ADDR(),
vips_region_region() etc.?

4
doc/reference/extending.xml
View File

@ -364,6 +364,10 @@ if( negative( in, &out, "image_max", 128, NULL ) )
#VipsRect in _generate().
</para>
<para>
Make zero-copy operations, like vips_insert(), with vips_region_region().
</para>
</refsect1>
</refentry>

13
doc/reference/using-C.xml
View File

@ -24,14 +24,14 @@
</para>
<para>
When your program starts, use <function>vips_init()</function> to set up
When your program starts, use <function>VIPS_INIT()</function> to set up
the VIPS library. You should pass it the name of your program, usually
<literal>argv[0]</literal>. Use <function>vips_shutdown()</function>
when you exit.
</para>
<para>
You can add the VIPS flags to your GObject command-line processing
You can add the VIPS flags to your %GObject command-line processing
with vips_get_option_group(), see below.
</para>
@ -73,6 +73,13 @@
C-style memory array. See vips_image_write_to_file() and friends.
</para>
<para>
Use #VipsRegion to read pixels out of images. You can use
VIPS_IMAGE_ADDR() as well, but this can need a large amount of
memory to work. See <link linkend="extending">extending</link>
for an introduxction to writing your own operations.
</para>
<para>
VIPS keeps a log of error message, see <link
linkend="libvips-error">VIPS Error</link> to find out how to get and
@ -100,7 +107,7 @@ main( int argc, char **argv )
double mean;
VipsImage *out;
if( vips_init( argv[0] ) )
if( VIPS_INIT( argv[0] ) )
vips_error_exit( NULL );
context = g_option_context_new( "hello infile outfile - VIPS demo" );

2
libvips/arithmetic/add.c
View File

@ -200,7 +200,7 @@ vips_add_init( VipsAdd *add )
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>), then the
* <link linkend="libvips-arithmetic">arithmetic</link>), then the
* following table is used to determine the output type:
*
* <table>

2
libvips/arithmetic/boolean.c
View File

@ -260,7 +260,7 @@ vips_booleanv( VipsImage *left, VipsImage *right, VipsImage **out,
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>).
* <link linkend="libvips-arithmetic">arithmetic</link>).
*
* See also: vips_boolean_const().
*

2
libvips/arithmetic/divide.c
View File

@ -254,7 +254,7 @@ vips_divide_init( VipsDivide *divide )
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>), then the
* <link linkend="libvips-arithmetic">arithmetic</link>), then the
* following table is used to determine the output type:
*
* <table>

2
libvips/arithmetic/math2.c
View File

@ -247,7 +247,7 @@ vips_math2v( VipsImage *left, VipsImage *right, VipsImage **out,
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>), and that format is the
* <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the
* result type.
*
* See also: vips_math2_const().

2
libvips/arithmetic/multiply.c
View File

@ -200,7 +200,7 @@ vips_multiply_init( VipsMultiply *multiply )
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>), then the
* <link linkend="libvips-arithmetic">arithmetic</link>), then the
* following table is used to determine the output type:
*
* <table>

2
libvips/arithmetic/relational.c
View File

@ -270,7 +270,7 @@ vips_relationalv( VipsImage *left, VipsImage *right, VipsImage **out,
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>).
* <link linkend="libvips-arithmetic">arithmetic</link>).
*
* To decide if pixels match exactly, that is have the same value in every
* band, use vips_bandbool() after this operation to AND or OR image bands

2
libvips/arithmetic/remainder.c
View File

@ -207,7 +207,7 @@ vips_remainder_init( VipsRemainder *remainder )
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>), and that format is the
* <link linkend="libvips-arithmetic">arithmetic</link>), and that format is the
* result type.
*
* See also: vips_remainder_const(), vips_divide(), vips_round().

2
libvips/arithmetic/subtract.c
View File

@ -190,7 +190,7 @@ vips_subtract_init( VipsSubtract *subtract )
*
* The two input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>), then the
* <link linkend="libvips-arithmetic">arithmetic</link>), then the
* following table is used to determine the output type:
*
* <table>

4
libvips/arithmetic/sum.c
View File

@ -179,7 +179,7 @@ vips_sumv( VipsImage **in, VipsImage **out, int n, va_list ap )
* @n: number of input images
* @...: %NULL-terminated list of optional named arguments
*
* This operation sums @in1 + @in2 and writes the result to @out.
* This operation sums all images in @in and writes the result to @out.
*
* If the images differ in size, the smaller images are enlarged to match the
* largest by adding zero pixels along the bottom and right.
@ -191,7 +191,7 @@ vips_sumv( VipsImage **in, VipsImage **out, int n, va_list ap )
*
* The input images are cast up to the smallest common format (see table
* Smallest common format in
* <link linkend="VIPS-arithmetic">arithmetic</link>), then the
* <link linkend="libvips-arithmetic">arithmetic</link>), then the
* following table is used to determine the output type:
*
* <table>

2
libvips/deprecated/wrapvips7.c
View File

@ -36,7 +36,7 @@
TODO:
- masks would be hard, vips8 won't really have these
- keep for testing, mostly ... iofuncs/init.c has a commeted-out
- keep for testing, mostly ... iofuncs/init.c has a commented-out
call to init this thing
*/

17
libvips/foreign/dzsave.c
View File

@ -45,6 +45,8 @@
* 25/6/14
* - stop on zip write >4gb, thanks bgilbert
* - save metadata, see https://github.com/jcupitt/libvips/issues/137
* 18/8/14
* - use g_ date funcs, helps Windows
*/
/*
@ -809,17 +811,13 @@ write_vips_meta( VipsForeignSaveDz *dz )
{
VipsObjectClass *class = VIPS_OBJECT_GET_CLASS( dz );
time_t now;
char time_string[50];
xmlDoc *doc;
GTimeVal now;
char *date;
char *dump;
int dump_size;
GsfOutput *out;
time( &now );
strftime( time_string, sizeof( time_string ),
"%FT%TZ", gmtime( &now ) );
if( !(doc = xmlNewDoc( (xmlChar *) "1.0" )) ) {
vips_error( class->nickname, "%s", _( "xml save error" ) );
return( -1 );
@ -830,14 +828,19 @@ write_vips_meta( VipsForeignSaveDz *dz )
xmlFreeDoc( doc );
return( -1 );
}
g_get_current_time( &now );
date = g_time_val_to_iso8601( &now );
if( set_prop( dz, doc->children, "xmlns",
"http://www.vips.ecs.soton.ac.uk/dzsave" ) ||
set_prop( dz, doc->children, "date", time_string ) ||
set_prop( dz, doc->children, "date", date ) ||
set_prop( dz, doc->children, "version", VIPS_VERSION ) ||
write_vips_properties( dz, doc->children ) ) {
g_free( date );
xmlFreeDoc( doc );
return( -1 );
}
g_free( date );
xmlDocDumpFormatMemory( doc, (xmlChar **) &dump, &dump_size, 1 );
if( !dump ) {

3
libvips/include/vips/generate.h
View File

@ -56,10 +56,9 @@ typedef void (*VipsSinkNotify)( VipsImage *im, VipsRect *rect, void *a );
int vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask,
int tile_width, int tile_height, int max_tiles,
int priority,
VipsSinkNotify notify, void *a );
VipsSinkNotify notify_fn, void *a );
int vips_sink_memory( VipsImage *im );
int vips_sink_memory2( VipsImage *image );
void *vips_start_one( VipsImage *out, void *a, void *b );
int vips_stop_one( void *seq, void *a, void *b );

2
libvips/include/vips/internal.h
View File

@ -104,6 +104,8 @@ extern gboolean vips__cache_trace;
void vips__cache_init( void );
void vips__print_renders( void );
void vips__type_leak( void );
typedef int (*im__fftproc_fn)( VipsImage *, VipsImage *, VipsImage * );

2
libvips/include/vips/threadpool.h
View File

@ -131,8 +131,6 @@ int vips_threadpool_run( VipsImage *im,
void vips_get_tile_size( VipsImage *im,
int *tile_width, int *tile_height, int *nlines );
void vips__print_renders( void );
void vips_concurrency_set( int concurrency );
int vips_concurrency_get( void );

3
libvips/include/vips/type.h
View File

@ -91,7 +91,6 @@ typedef struct _VipsArea {
VipsArea *vips_area_copy( VipsArea *area );
void vips_area_unref( VipsArea *area );
void vips__type_leak( void );
VipsArea *vips_area_new( VipsCallbackFn free_fn, void *data );
VipsArea *vips_area_new_blob( VipsCallbackFn free_fn,
@ -198,8 +197,6 @@ int vips_value_set_array_object( GValue *value, int n );
* vips_value_set_array_image(). They need to be declared after VipsImage.
*/
void vips__meta_init_types( void );
#ifdef __cplusplus
}
#endif /*__cplusplus*/

21
libvips/iofuncs/generate.c
View File

@ -112,12 +112,12 @@
* SECTION: generate
* @short_description: calculate pixels and pixel buffers
* @stability: Stable
* @see_also: <link linkend="libvips-image">image</link>,
* <link linkend="libvips-region">region</link>
* @see_also: <link linkend="VipsImage">VipsImage</link>,
* <link linkend="VipsRegion">VipsRegion</link>
* @include: vips/vips.h
*
* These functions let you generate regions of pixels in an image
* processing operation, and ask for regions of image to be calculated.
* These functions let you attach generate functions to images
* and ask for regions of images to be calculated.
*/
/* Max number of images we can handle.
@ -349,7 +349,7 @@ vips__demand_hint_array( VipsImage *image,
* @image prefers to supply pixels according to @hint.
*
* Operations can set demand hints, that is, hints to the VIPS IO system about
* the type of region geometry this operation works best with. For example,
* the type of region geometry they work best with. For example,
* operations which transform coordinates will usually work best with
* %VIPS_DEMAND_STYLE_SMALLTILE, operations which work on local windows of
* pixels will like %VIPS_DEMAND_STYLE_FATSTRIP.
@ -642,13 +642,14 @@ write_vips( VipsRegion *region, VipsRect *area, void *a, void *b )
*
* Generates an image. The action depends on the image type.
*
* For images opened with "p", vips_image_generate() just attaches the
* start/generate/stop callbacks and returns.
* For images created with vips_image_new(), vips_image_generate() just
* attaches the start/generate/stop callbacks and returns.
*
* For "t" images, memory is allocated for the whole image and it is entirely
* generated using vips_sink().
* For images created with vips_image_new_memory(), memory is allocated for
* the whole image and it is entirely generated using vips_sink_memory().
*
* For "w" images, memory for a few scanlines is allocated and
* For images created with vips_image_new_temp_file() and friends, memory for
* a few scanlines is allocated and
* vips_sink_disc() used to generate the image in small chunks. As each
* chunk is generated, it is written to disc.
*

209
libvips/iofuncs/header.c
View File

@ -71,41 +71,22 @@
* SECTION: header
* @short_description: get, set and walk image headers
* @stability: Stable
* @see_also: <link linkend="libvips-meta">meta</link>,
* <link linkend="libvips-check">check</link>
* @see_also: <link linkend="libvips-type">type</link>
* @include: vips/vips.h
*
* These functions let you get at image header data (including metadata) in a
* uniform way. They are handy for language bindings but less useful for C
* users.
* uniform way.
*
* They first search the
* VIPS header
* fields (see <link linkend="libvips-image">image</link>), then search for
* a metadata field of that name (see
* <link linkend="libvips-meta">meta</link>).
* Use vips_image_get_typeof() to test for the
* existance and #GType
* of a header field.
*
* See <link linkend="libvips-meta">meta</link>
* for a set of functions for adding new metadata to an image.
*/
/**
* SECTION: meta
* @short_description: get and set image metadata
* @stability: Stable
* @see_also: <link linkend="libvips-header">header</link>
* @include: vips/vips.h
*
* You can attach arbitrary metadata to images. VipsMetadata is copied as images
* You can attach arbitrary metadata to images. Metadata is copied as images
* are processed, so all images which used this image as input, directly or
* indirectly, will have this same bit of metadata attached to them. Copying
* is implemented with reference-counted pointers, so it is efficient, even for
* large items of data. This does however mean that metadata items need to be
* immutable. VipsMetadata
* is handy for things like ICC profiles or EXIF data.
* immutable. Metadata is handy for things like ICC profiles or EXIF data.
*
* Various convenience functions (eg. vips_image_set_int()) let you easily
* attach
@ -120,13 +101,14 @@
* If you save an image in VIPS format, all metadata (with a restriction, see
* below) is automatically saved for you in a block of XML at the end of the
* file. When you load a VIPS image, the metadata is restored. You can use the
* 'edvips' command-line tool to extract or replace this block of XML.
* `vipsedit` command-line tool to extract or replace this block of XML.
*
* VIPS metadata is based on GValue. See the docs for that system if you want
* VIPS metadata is based on %GValue. See the docs for that system if you want
* to do fancy stuff such as defining a new metadata type.
* VIPS defines a new GValue called "vips_save_string", a variety of string. If
* your GValue can be transformed to vips_save_string, it will be saved and
* loaded to and from VIPS files for you.
* VIPS defines a new %GValue called `vips_save_string`, a variety of string,
* see vips_value_set_save_string().
* If your %GValue can be transformed to `vips_save_string`, it will be
* saved and loaded to and from VIPS files for you.
*
* VIPS provides a couple of base classes which implement
* reference-counted areas of memory. If you base your metadata on one of
@ -201,7 +183,11 @@ const guint64 vips__image_sizeof_bandformat[] = {
2 * sizeof( double ) /* VIPS_FORMAT_DPCOMPLEX */
};
/* Return number of bytes for a band format, or -1 on error.
/**
* vips_format_sizeof:
* @format: format type
*
* Returns: number of bytes for a band format, or -1 on error.
*/
guint64
vips_format_sizeof( VipsBandFormat format )
@ -335,38 +321,69 @@ meta_init( VipsImage *im )
}
}
/**
* vips_image_get_width:
* @image: image to get from
*
* Returns: the number of pixels across the image.
*/
int
vips_image_get_width( const VipsImage *image )
{
return( image->Xsize );
}
/**
* vips_image_get_height:
* @image: image to get from
*
* Returns: the number of pixels down the image.
*/
int
vips_image_get_height( const VipsImage *image )
{
return( image->Ysize );
}
/**
* vips_image_get_bands:
* @image: image to get from
*
* Returns: the number of bands (channels) in the image.
*/
int
vips_image_get_bands( const VipsImage *image )
{
return( image->Bands );
}
/**
* vips_image_get_format:
* @image: image to get from
*
* Returns: the format of each band element.
*/
VipsBandFormat
vips_image_get_format( const VipsImage *image )
{
return( image->BandFmt );
}
/**
* vips_image_get_coding:
* @image: image to get from
*
* Returns: the image coding
*/
VipsCoding
vips_image_get_coding( const VipsImage *image )
{
return( image->Coding );
}
/* vips_image_get_interpretation:
* @image: image to guess for
/**
* vips_image_get_interpretation:
* @image: image to get from
*
* Return the #VipsInterpretation set in the image header.
* Use vips_image_guess_interpretation() if you want a sanity-checked value.
@ -400,11 +417,12 @@ vips_image_default_interpretation( const VipsImage *image )
return( VIPS_INTERPRETATION_MULTIBAND );
}
/* vips_image_guess_interpretation:
/**
* vips_image_guess_interpretation:
* @image: image to guess for
*
* Return the #VipsInterpretation for an image, guessing a default value if
* the set value looks wrong.
* Return the #VipsInterpretation for an image, guessing a sane value if
* the set value looks crazy.
*
* Returns: a sensible #VipsInterpretation for the image.
*/
@ -510,42 +528,90 @@ vips_image_guess_interpretation( const VipsImage *image )
return( vips_image_default_interpretation( image ) );
}
/**
* vips_image_get_xres:
* @image: image to get from
*
* Returns: the horizontal image resolution in pixels per millimeter.
*/
double
vips_image_get_xres( const VipsImage *image )
{
return( image->Xres );
}
/**
* vips_image_get_yres:
* @image: image to get from
*
* Returns: the vertical image resolution in pixels per millimeter.
*/
double
vips_image_get_yres( const VipsImage *image )
{
return( image->Yres );
}
/**
* vips_image_get_xoffset:
* @image: image to get from
*
* Returns: the horizontal position of the image origin, in pixels.
*/
int
vips_image_get_xoffset( const VipsImage *image )
{
return( image->Xoffset );
}
/**
* vips_image_get_yoffset:
* @image: image to get from
*
* Returns: the vertical position of the image origin, in pixels.
*/
int
vips_image_get_yoffset( const VipsImage *image )
{
return( image->Yoffset );
}
/**
* vips_image_get_filename:
* @image: image to get from
*
* Returns: the name of the file the image was loaded from.
*/
const char *
vips_image_get_filename( const VipsImage *image )
{
return( image->filename );
}
/**
* vips_image_get_mode:
* @image: image to get from
*
* Image modes are things like `"t"`, meaning a memory buffer, and `"p"`
* meaning a delayed computation.
*
* Returns: the image mode.
*/
const char *
vips_image_get_mode( const VipsImage *image )
{
return( image->mode );
}
/**
* vips_image_get_scale:
* @image: image to get from
*
* Matrix images can have an optional `scale` field for use by integer
* convolution.
*
* Returns: the scale.
*/
double
vips_image_get_scale( const VipsImage *array )
{
@ -558,6 +624,15 @@ vips_image_get_scale( const VipsImage *array )
return( scale );
}
/**
* vips_image_get_offset:
* @image: image to get from
*
* Matrix images can have an optional `offset` field for use by integer
* convolution.
*
* Returns: the offset.
*/
double
vips_image_get_offset( const VipsImage *array )
{
@ -571,7 +646,7 @@ vips_image_get_offset( const VipsImage *array )
}
/**
* vips_image_get_data: (skip)
* vips_image_get_data:
* @image: image to get data for
*
* Return a pointer to the image's pixel data, if possible. This can involve
@ -607,7 +682,7 @@ vips_image_get_data( VipsImage *image )
* Normally you copy the fields from your input images with
* vips_image_pipelinev() and then make
* any adjustments you need, but if you are creating an image from scratch,
* for example im_black() or im_jpeg2vips(), you do need to set all the
* for example vips_black() or vips_jpegload(), you do need to set all the
* fields yourself.
*
* See also: vips_image_pipelinev().
@ -724,24 +799,22 @@ vips__image_copy_fields_array( VipsImage *out, VipsImage *in[] )
* vips_image_set:
* @image: image to set the metadata on
* @field: the name to give the metadata
* @value: the GValue to copy into the image
* @value: the %GValue to copy into the image
*
* Set a piece of metadata on @image. Any old metadata with that name is
* destroyed. The GValue is copied into the image, so you need to unset the
* destroyed. The %GValue is copied into the image, so you need to unset the
* value when you're done with it.
*
* For example, to set an integer on an image (though you would use the
* convenience function vips_image_set_int() in practice), you would need:
* convenience function vips_image_set_int() in practice), you would do:
*
* |[
* GValue value = { 0 };
*
* g_value_init( &value, G_TYPE_INT );
* g_value_set_int( &value, 42 );
* vips_image_set( image, field, &value );
* g_value_unset( &value );
*
* return( 0 );
* g_value_init (&value, G_TYPE_INT);
* g_value_set_int (&value, 42);
* vips_image_set (image, field, &value);
* g_value_unset (&value);
* ]|
*
* See also: vips_image_get().
@ -764,15 +837,14 @@ vips_image_set( VipsImage *image, const char *field, GValue *value )
* vips_image_get:
* @image: image to get the field from from
* @field: the name to give the metadata
* @value_copy: the GValue is copied into this
* @value_copy: the %GValue is copied into this
*
* Fill @value_copy with a copy of the header field. @value_copy must be zeroed
* but uninitialised.
*
* This will return -1 and add a message to the error buffer if the field
* does not exist. Use vips_image_get_typeof() to test for the
* existence
* of a field first if you are not certain it will be there.
* existence of a field first if you are not certain it will be there.
*
* For example, to read a double from an image (though of course you would use
* vips_image_get_double() in practice):
@ -781,22 +853,20 @@ vips_image_set( VipsImage *image, const char *field, GValue *value )
* GValue value = { 0 };
* double d;
*
* if( vips_image_get( image, field, &value ) )
* return( -1 );
* if (vips_image_get (image, field, &value))
* return -1;
*
* if( G_VALUE_TYPE( &value ) != G_TYPE_DOUBLE ) {
* if (G_VALUE_TYPE (&value) != G_TYPE_DOUBLE) {
* vips_error( "mydomain",
* _( "field \"%s\" is of type %s, not double" ),
* _("field \"%s\" is of type %s, not double"),
* field,
* g_type_name( G_VALUE_TYPE( &value ) ) );
* g_value_unset( &value );
* return( -1 );
* g_type_name (G_VALUE_TYPE (&value)));
* g_value_unset (&value);
* return -1;
* }
*
* d = g_value_get_double( &value );
* g_value_unset( &value );
*
* return( 0 );
* d = g_value_get_double (&value);
* g_value_unset (&value);
* ]|
*
* See also: vips_image_get_typeof(), vips_image_get_double().
@ -875,12 +945,12 @@ vips_image_get( const VipsImage *image, const char *field, GValue *value_copy )
* @image: image to test
* @field: the name to search for
*
* Read the GType for a header field. Returns zero if there is no
* Read the %GType for a header field. Returns zero if there is no
* field of that name.
*
* See also: vips_image_get().
*
* Returns: the GType of the field, or zero if there is no
* Returns: the %GType of the field, or zero if there is no
* field of that name.
*/
GType
@ -945,7 +1015,7 @@ vips_image_map_fn( VipsMeta *meta, VipsImageMapFn fn, void *a )
}
/**
* vips_image_map: (skip)
* vips_image_map:
* @image: image to map over
* @fn: function to call for each header field
* @a: user data for function
@ -1101,7 +1171,7 @@ vips_image_set_blob( VipsImage *image, const char *field,
}
/**
* vips_image_get_blob: (skip)
* vips_image_get_blob:
* @image: image to get the metadata from
* @field: metadata name
* @data: pointer to area of memory
@ -1333,7 +1403,7 @@ vips_image_set_string( VipsImage *image, const char *field, const char *str )
* vips_image_get_as_string:
* @image: image to get the header field from
* @field: field name
* @out: return field value as string
* @out: (transfer full): return field value as string
*
* Gets @out from @im under the name @field.
* This function will read any field, returning it as a printable string.
@ -1378,7 +1448,7 @@ vips_image_get_as_string( const VipsImage *image,
* vips_image_history_printf:
* @image: add history line to this image
* @format: printf() format string
* @Varargs: arguments to format string
* @...: arguments to format string
*
* Add a line to the image history. The @format and arguments are expanded, the
* date and time is appended prefixed with a hash character, and the whole
@ -1387,15 +1457,14 @@ vips_image_get_as_string( const VipsImage *image,
* For example:
*
* |[
* vips_image_history_printf( image, "vips im_invert %s %s",
* in->filename, out->filename );
* vips_image_history_printf (image, "vips invert %s %s",
* in->filename, out->filename);
* ]|
*
* Might add the string
*
* |[
* "vips im_invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35
* 2009\n"
* "vips invert /home/john/fred.v /home/john/jim.v # Fri Apr 3 23:30:35 2009\n"
* ]|
*
* VIPS operations don't add history lines for you because a single action at
@ -1486,7 +1555,7 @@ vips_image_history_args( VipsImage *image,
*
* See also: vips_image_history_printf().
*
* Returns: The history of @image as a C string. Do not free!
* Returns: (transfer none): The history of @image as a C string. Do not free!
*/
const char *
vips_image_get_history( VipsImage *image )

67
libvips/iofuncs/image.c
View File

@ -58,7 +58,10 @@
* SECTION: image
* @short_description: the VIPS image class
* @stability: Stable
* @see_also: <link linkend="libvips-region">region</link>
* @see_also: <link linkend="libvips-header">header</link>
* <link linkend="VipsRegion">VipsRegion</link>
* <link linkend="libvips-generate">generate</link>
* <link linkend="VipsOperation">VipsOperation</link>
* @include: vips/vips.h
*
* The image class and associated types and macros.
@ -78,7 +81,7 @@
* 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()..
* 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.
@ -96,7 +99,7 @@
* 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
* probably be interpreted. For example, vips_Lab2XYZ() will set the
* 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
@ -108,6 +111,11 @@
* 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 <link linkend="VipsOperation">operation</link> for an introduction to
* running operations on images, see <link
* linkend="libvips-header">header</link> for getting and setting image
@ -152,8 +160,8 @@
* @VIPS_DEMAND_STYLE_THINSTRIP: demand in thin (typically 1 pixel high) strips
* @VIPS_DEMAND_STYLE_ANY: demand geometry does not matter
*
* See vips_image_pipelinev(). Operations can hint to the VIPS image IO system about
* the kind of demand geometry they prefer.
* 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,
@ -213,7 +221,7 @@
* 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
* The gaps in numbering are historical and must be maintained. Allocate
* new numbers from the end.
*/
@ -233,7 +241,7 @@
*
* The format used for each band element.
*
* Each corresponnds to a native C type for the current machine. For example,
* Each corresponds to a native C type for the current machine. For example,
* #VIPS_FORMAT_USHORT is <type>unsigned short</type>.
*/
@ -322,9 +330,9 @@
*
* If VIPS_DEBUG is defined, you get a version that checks bounds for you.
*
* See also: VIPS_REGION_ADDR().
* See also: vips_image_wio_input(), vips_image_inplace(), VIPS_REGION_ADDR().
*
* Returns: The address of pixel (x,y) in the image.
* Returns: The address of pixel (@X,@Y) in @I.
*/
/**
@ -341,9 +349,9 @@
* If VIPS_DEBUG is defined, you get a version that checks bounds and image
* type for you.
*
* See also: VIPS_IMAGE_ADDR().
* See also: vips_image_wio_input(), vips_image_inplace(), vips_check_matrix().
*
* Returns: The address of pixel (x,y) in the image.
* Returns: The address of pixel (@X,@Y) in @I.
*/
/* Our signals.
@ -1245,8 +1253,8 @@ vips_image_class_init( VipsImageClass *class )
* 128 area of pixels) during image computation.
*
* You can use this signal to update user-interfaces with progress
* feedback. Beware of updating too frequently: there will usually
* need to be some mechanism to limit update frequency.
* 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.
@ -1285,9 +1293,10 @@ vips_image_class_init( VipsImageClass *class )
* @image: the image that was calculated
* @result: set to non-zero to indicate error
*
* The ::written signal is emitted when an image is written to. It is
* used by things like vips_image_new_mode("x.jpg", "w") to do the
* final write of @image.
* 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.
*/
vips_image_signals[SIG_WRITTEN] = g_signal_new( "written",
G_TYPE_FROM_CLASS( class ),
@ -1662,8 +1671,9 @@ vips_image_temp_name( void )
* If you write to one of these images, vips will just attach some callbacks,
* no pixels will be generated.
*
* It is the equivalent of
* vips_image_new_mode() with @mode "p".
* 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().
*
* Returns: the new #VipsImage, or %NULL on error.
*/
@ -1716,10 +1726,6 @@ vips_image_new_mode( const char *filename, const char *mode )
* vips_image_new_memory() creates a new #VipsImage which, when written to, will
* create a memory image.
*
* It is a convenience function for
* vips_image_new_mode() with @filename set by vips_image_temp_name() and
* @mode "t".
*
* See also: vips_image_new().
*
* Returns: the new #VipsImage, or %NULL on error.
@ -2080,7 +2086,7 @@ vips_image_new_matrixv( int width, int height, ... )
*
* 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 unlinked.
* this call is deleted.
*
* This function is clearly extremely dangerous, use with great caution.
*
@ -2102,8 +2108,9 @@ vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close )
* vips_image_new_temp_file:
* @format: format of file
*
* Make a "w" disc #VipsImage which will be automatically unlinked when it is
* destroyed. @format is something like "&percnt;s.v" for a vips file.
* 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 "&percnt;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
@ -2113,6 +2120,8 @@ vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close )
* vips uses g_mkstemp() to make the temporary filename. They generally look
* something like "vips-12-EJKJFGH.v".
*
* See also: vips_image_new().
*
* Returns: the new #VipsImage, or %NULL on error.
*/
VipsImage *
@ -2292,10 +2301,10 @@ vips_image_write_to_buffer( VipsImage *in,
/**
* vips_image_write_to_memory:
* @in: image to write
* @buf: return buffer start here
* @buf: (transfer full): return buffer start here
* @len: return buffer length here
*
* Writes @in to memory as a simple, unformatted array.
* Writes @in to memory as a simple, unformatted C-style array.
*
* The caller is responsible for freeing memory.
*
@ -2381,7 +2390,7 @@ vips_image_decode( VipsImage *in, VipsImage **out )
* @bands: predict bands here
* @format: predict format here
*
* We often need to know what an image will decode to without actuaklly
* 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().
@ -2514,7 +2523,7 @@ vips_image_ispartial( VipsImage *image )
*
* 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 "t" image.
* write directly to the ->data member of a memory image.
*
* Returns: 0 on success, or -1 on error.
*/

4
libvips/iofuncs/init.c
View File

@ -811,7 +811,7 @@ guess_prefix( const char *argv0, const char *name )
*
* See also: vips_guess_libdir().
*
* Returns: the install prefix as a static string, do not free.
* Returns: (transfer none): the install prefix as a static string, do not free.
*/
const char *
vips_guess_prefix( const char *argv0, const char *env_name )
@ -876,7 +876,7 @@ vips_guess_prefix( const char *argv0, const char *env_name )
*
* See also: vips_guess_prefix().
*
* Returns: the libdir as a static string, do not free.
* Returns: (transfer none): the libdir as a static string, do not free.
*/
const char *
vips_guess_libdir( const char *argv0, const char *env_name )

11
libvips/iofuncs/object.c
View File

@ -105,11 +105,11 @@
* The stages inside vips_object_build() are:
*
* 1. Chain up through the object's @build class methods. At each stage,
* each object does any initial setup and checking, then chains up to its
* each class does any initial setup and checking, then chains up to its
* superclass.
*
* 2. The innermost @build method in #VipsObject itself checks that all input
* arguments have been set and then returns.
* 2. The innermost @build method inside #VipsObject itself checks that all
* input arguments have been set and then returns.
*
* 3. All object @build methods now finish executing, from innermost to
* outermost. They know all input arguments have been checked and supplied, so
@ -120,7 +120,10 @@
* signal. #VipsObject::postbuild only runs if the object has constructed
* successfuly.
*
* And the stages inside close are:
* #VipsOperation has a cache of recent operation objects, see that class for
* an explanation of vips_cache_operation_build().
*
* Finally the stages inside close are:
*
* 1. #VipsObject::preclose. This is emitted at the start of
* the #VipsObject dispose. The object is still functioning.

15
libvips/iofuncs/region.c
View File

@ -158,12 +158,14 @@
* @X: x coordinate
* @Y: y coordinate
*
* This macro returns a pointer to a pixel in a region. The (x, y) coordinates
* need to be within the #VipsRect (@R->valid).
* This macro returns a pointer to a pixel in a region. The (@X, @Y)
* coordinates need to be within the #VipsRect (@R->valid).
*
* If DEBUG is defined, you get a version that checks bounds for you.
*
* Returns: The address of pixel (x,y) in the region.
* See also: vips_region_prepare().
*
* Returns: The address of pixel (@X,@Y) in @R.
*/
/**
@ -173,6 +175,8 @@
* This macro returns a pointer to the top-left pixel in the #VipsRegion, that
* is, the pixel at (@R->valid.left, @R->valid.top).
*
* See also: vips_region_prepare().
*
* Returns: The address of the top-left pixel in the region.
*/
@ -1090,11 +1094,10 @@ vips_region_generate( VipsRegion *reg )
* the calling thread, no new threads are involved, and computation
* blocks until the pixels are ready.
*
* Use vips_region_prepare_thread() to calculate an area of pixels with many
* threads. Use vips_sink_screen() to calculate an area of pixels in the
* Use vips_sink_screen() to calculate an area of pixels in the
* background.
*
* See also: vips_region_prepare_thread(), vips_sink_screen(),
* See also: vips_sink_screen(),
* vips_region_prepare_to().
*
* Returns: 0 on success, or -1 on error.

12
libvips/iofuncs/sink.c
View File

@ -335,8 +335,9 @@ vips_sink_base_progress( void *a )
* @a: user data
* @b: user data
*
* Loops over an image. @generate is called for every pixel in the image, with
* the @reg argument being a region of pixels for processing.
* Loops over an image. @generate_fn is called for every
* pixel in the image, with
* the @reg argument being a region of calculated pixels.
*
* Each set of pixels is @tile_width by @tile_height pixels (less at the
* image edges). This is handy for things like writing a tiled TIFF image,
@ -398,9 +399,10 @@ vips_sink_tile( VipsImage *im,
* @a: user data
* @b: user data
*
* Loops over an image. @generate is called for every pixel in the image, with
* the @reg argument being a region of pixels for processing. vips_sink() is
* used to implement operations like #VipsAvg which have no image output.
* Loops over an image. @generate_fn is called for every pixel in
* the image, with
* the @reg argument being a region of calculated pixels. vips_sink() is
* used to implement operations like vips_avg() which have no image output.
*
* Each set of pixels is sized according to the requirements of the image
* pipeline that generated @im.

5
libvips/iofuncs/sinkdisc.c
View File

@ -451,7 +451,7 @@ write_free( Write *write )
* @a: client data
*
* The function should write the pixels in @area from @region. @a is the
* value passed into vips_discsink().
* value passed into vips_sink_disc().
*
* See also: vips_sink_disc().
*
@ -472,7 +472,8 @@ write_free( Write *write )
* sections in top-to-bottom order, and there are never any gaps.
*
* This operation is handy for making image sinks which output to things like
* disc files.
* disc files. Things like vips_jpegsave(), for example, use this to write
* images to files in JPEG format.
*
* See also: vips_concurrency_set().
*

6
libvips/iofuncs/sinkmemory.c
View File

@ -313,10 +313,10 @@ sink_memory_init( SinkMemory *memory, VipsImage *image )
* vips_sink_memory:
* @im: generate this image to memory
*
* Loops over an image, generating it to a memory buffer attached to the
* image.
* Loops over @im, generating it to a memory buffer attached to @im. It is
* used by vips to implement writing to a memory buffer.
*
* See also: vips_sink(), vips_get_tile_size().
* See also: vips_sink(), vips_get_tile_size(), vips_image_new_memory().
*
* Returns: 0 on success, or -1 on error.
*/

14
libvips/iofuncs/sinkscreen.c
View File

@ -1047,11 +1047,11 @@ mask_fill( VipsRegion *out, void *seq, void *a, void *b, gboolean *stop )
* @tile_height: tile height
* @max_tiles: maximum tiles to cache
* @priority: rendering priority
* @notify: pixels are ready notification callback
* @notify_fn: pixels are ready notification callback
* @a: client data for callback
*
* This operation renders @in in the background, making pixels available on
* @out as they are calculated. The @notify callback is run every time a new
* @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.
@ -1071,15 +1071,15 @@ mask_fill( VipsRegion *out, void *seq, void *a, void *b, gboolean *stop )
* 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 callback will trigger when those pixels are
* to a queue, and the @notify_fn callback will trigger when those pixels are
* ready.
*
* The @notify callback is run from one of the background threads. In the
* 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 is %NULL then vips_sink_screen() runs synchronously.
* 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.
*
@ -1093,7 +1093,7 @@ vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask,
int tile_width, int tile_height,
int max_tiles,
int priority,
VipsSinkNotify notify, void *a )
VipsSinkNotify notify_fn, void *a )
{
Render *render;
@ -1125,7 +1125,7 @@ vips_sink_screen( VipsImage *in, VipsImage *out, VipsImage *mask,
}
if( !(render = render_new( in, out, mask,
tile_width, tile_height, max_tiles, priority, notify, a )) )
tile_width, tile_height, max_tiles, priority, notify_fn, a )) )
return( -1 );
VIPS_DEBUG_MSG( "vips_sink_screen: max = %d, %p\n", max_tiles, render );

41
libvips/iofuncs/type.c
View File

@ -59,10 +59,10 @@
* SECTION: type
* @short_description: basic types
* @stability: Stable
* @see_also: <link linkend="libvips-operation">operation</link>
* @see_also: <link linkend="libvips-header">header</link>
* @include: vips/vips.h
*
* A selection of GType defintions used by VIPS.
* A selection of %GType defintions used by VIPS.
*/
/* A very simple boxed type for testing. Just an int.
@ -138,21 +138,6 @@ vips_thing_get_type( void )
return( type );
}
/**
* SECTION: VipsArea
* @short_description: an area of memory
* @stability: Stable
* @see_also: <link linkend="libvips-meta">header</link>,
* @include: vips/vips.h
*
* A VipsArea wraps a chunk of memory. It adds reference counting and a free
* function. It also keeps a count and a GType, so the area can be an array.
*
* This type is used for things like passing an array of double or an array of
* VipsObject pointers to operations, and for reference-counted immutable
* strings.
*/
static GSList *vips_area_all = NULL;
VipsArea *
@ -227,8 +212,14 @@ vips_area_unref( VipsArea *area )
* @free_fn: (scope async): @data will be freed with this function
* @data: data will be freed with this function
*
* An area of memory with a free function. (eg. \0-terminated string, or a
* struct). Inital count == 1, so _unref() after attaching somewhere.
* A VipsArea wraps a chunk of memory. It adds reference counting and a free
* function. It also keeps a count and a %GType, so the area can be an array.
*
* This type is used for things like passing an array of double or an array of
* #VipsObject pointers to operations, and for reference-counted immutable
* strings.
*
* Inital count == 1, so _unref() after attaching somewhere.
*
* See also: vips_area_unref().
*
@ -313,7 +304,7 @@ vips_area_new_blob( VipsCallbackFn free_fn, void *data, size_t length )
* @sizeof_type: sizeof() an element in the array
* @n: number of elements in the array
*
* An area which holds an array of elements of some GType. To set values for
* An area which holds an array of elements of some %GType. To set values for
* the elements, get the pointer and write.
*
* See also: vips_area_unref().
@ -351,7 +342,7 @@ vips_area_free_array_object( GObject **array, VipsArea *area )
* vips_area_new_array_object:
* @n: number of elements in the array
*
* An area which holds an array of GObjects. See vips_area_new_array(). When
* An area which holds an array of %GObjects. See vips_area_new_array(). When
* the area is freed, each %GObject will be unreffed.
*
* See also: vips_area_unref().
@ -934,7 +925,7 @@ vips_value_set_save_stringf( GValue *value, const char *fmt, ... )
* @value: %GValue to get from
* @length: (allow-none): return length here, optionally
*
* Get the C string held internally by the GValue.
* Get the C string held internally by the %GValue.
*
* Returns: (transfer none): The C string held by @value.
*/
@ -946,14 +937,14 @@ vips_value_get_ref_string( const GValue *value, size_t *length )
/**
* vips_value_set_ref_string:
* @value: (out): GValue to set
* @value: (out): %GValue to set
* @str: C string to copy into the GValue
*
* Copies the C string @str into @value.
*
* vips_ref_string are immutable C strings that are copied between images by
* copying reference-counted pointers, making the much more efficient than
* regular GValue strings.
* regular %GValue strings.
*
* Returns: 0 on success, -1 otherwise.
*/
@ -1353,7 +1344,7 @@ vips_value_get_array_object( const GValue *value, int *n )
* @value: (out): %GValue to set
* @n: the number of elements
*
* Set @value to hold an array of GObject. Pass in the array length in @n.
* Set @value to hold an array of %GObject. Pass in the array length in @n.
*
* See also: vips_array_object_get().
*

2
libvips/iofuncs/vips.c
View File

@ -92,7 +92,7 @@
* SECTION: vips
* @short_description: startup, shutdown, version
* @stability: Stable
* @see_also: <link linkend="libvips-operation">operation</link>
* @see_also: <link linkend="VipsOperation">VipsOperation</link>
* @include: vips/vips.h
*
* Start VIPS up, shut VIPS down, get version information, relocation.