diff --git a/doc/How-it-opens-files.xml b/doc/How-it-opens-files.xml index fd03df88..30388045 100644 --- a/doc/How-it-opens-files.xml +++ b/doc/How-it-opens-files.xml @@ -91,27 +91,6 @@ $ vips shrink fred.png jim.png 10 10 This is done automatically in command-line operation. In programs, you need to set access to #VIPS_ACCESS_SEQUENTIAL in calls to functions like vips_image_new_from_file(). - - Debugging - - There are a few flags you can use to find out what libvips is doing. - - - --vips-leak This makes libvips test for leaks on program exit. It checks for images which haven’t been closed and also (usefully) shows the memory high-water mark. It counts all memory allocated in libvips for pixel buffers. - - - --vips-progress This makes libvips show a crude progress bar for every major image loop, with destination and elapsed time. You can see whether images are going to disc or to memory and how long the decompression is taking. - - - `–vips-cache-trace This shows a line for every vips operation that executes, with arguments. It’s part of vips8, so it doesn’t display vips7 operations, sadly. - - - - Summary - - libvips tries hard to do the quickest thing in every case, but will sometimes fail. You can prod it in the right direction with a mixture of hints and flags to the load system. - - diff --git a/doc/How-it-works.xml b/doc/How-it-works.xml index 8cdf0606..6d282ed0 100644 --- a/doc/How-it-works.xml +++ b/doc/How-it-works.xml @@ -138,7 +138,7 @@ g_object_unref( region ); Data sources - VIPS has data sources which can supply pixels for processing from a variety of sources. VIPS can stream images from files in VIPS native format, from tiled TIFF files, from binary PPM/PGM/PBM/PFM, from Radiance (HDR) files, from FITS images and from tiled OpenEXR images. VIPS will automatically unpack other formats to temporary disc files for you but this can obviously generate a lot of disc traffic. It also has a special sequential mode for streaming operations on non-random-access formats. A post on the libvips blog explains how libvips opens a file. One of the sources uses the ImageMagick (or optionally GraphicsMagick) library, so VIPS can read any image format that these libraries can read. + VIPS has data sources which can supply pixels for processing from a variety of sources. VIPS can stream images from files in VIPS native format, from tiled TIFF files, from binary PPM/PGM/PBM/PFM, from Radiance (HDR) files, from FITS images and from tiled OpenEXR images. VIPS will automatically unpack other formats to temporary disc files for you but this can obviously generate a lot of disc traffic. It also has a special sequential mode for streaming operations on non-random-access formats. Another section in these docs explains how libvips opens a file. One of the sources uses the ImageMagick (or optionally GraphicsMagick) library, so VIPS can read any image format that these libraries can read. VIPS images are held on disc as a 64-byte header containing basic image information like width, height, bands and format, then the image data as a single large block of pixels, left-to-right and top-to-bottom, then an XML extension block holding all the image metadata, such as ICC profiles and EXIF blocks. diff --git a/doc/Using-vipsthumbnail.xml b/doc/Using-vipsthumbnail.xml index 4cbdb049..7e9c738d 100644 --- a/doc/Using-vipsthumbnail.xml +++ b/doc/Using-vipsthumbnail.xml @@ -77,6 +77,9 @@ $ vipsthumbnail shark.jpg --size 200x You can append < or > to mean only resize if the image is smaller or larger than the target. + + You can append ! to force a resize to the exact target size, breaking the aspect ratio. + Cropping @@ -185,7 +188,7 @@ $ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.png You can give options to the image write operation as a list of comma-separated arguments in square brackets. For example: -$ vipsthumbnail fred.jpg ../jim.tif -o > tn_%s.jpg[Q=90,optimize_coding] +$ vipsthumbnail fred.jpg ../jim.tif -o tn_%s.jpg[Q=90,optimize_coding] will write jpeg images with quality 90, and will turn on the libjpeg coding optimizer. diff --git a/doc/binding.xml b/doc/binding.xml index eddd0b6a..1215134f 100644 --- a/doc/binding.xml +++ b/doc/binding.xml @@ -11,18 +11,18 @@ Binding Writing bindings for libvips - There are full libvips bindings for quite a few environments now: C, C++, command-line, Ruby, PHP, Python and JavaScript (node). + There are full libvips bindings for quite a few environments now: C, C++, command-line, Ruby, PHP, Lua, Python and JavaScript (node). This chapter runs through the four main styles that have been found to work well. If you want to write a new binding, one of these should be close to what you need. - - C API + + Don’t bind the top-level C API - The libvips C API (vips_add() and so on) is very inconvenient to use from other languages due to its heavy use of varargs. + The libvips C API (vips_add() and so on) is very inconvenient and dangerous to use from other languages due to its heavy use of varargs. - It’s much better to use the layer below. This lower layer is structured as: create operator, set parameters, execute, extract results. For example, you can execute vips_invert() like this: + It’s much better to use the layer below. This lower layer is structured as create operator, set parameters, execute, extract results. For example, you can execute vips_invert() like this: /* compile with @@ -112,7 +112,7 @@ main( int argc, char **argv ) } - libvips has a couple of extra things to let you fetch the arguments and types of an operator. Use vips_lib.vips_argument_map() to loop over all the arguments of an operator, and vips_object_get_argument() to fetch the type and flags of a specific argument. + libvips has a couple of extra things to let you examine the arguments and types of an operator at runtime. Use vips_lib.vips_argument_map() to loop over all the arguments of an operator, and vips_object_get_argument() to fetch the type and flags of a specific argument. Use vips_operation_get_flags() to get general information about an operator. @@ -139,7 +139,7 @@ VImage VImage::invert( VOption *options ) } - So from C++ you can call any libvips operator, though without type-safety, with VImage::call(), or use the member functions on VImage to get type-safe calls for at least the required operator arguments. + So from C++ you can call any libvips operator (though without type-safety) with VImage::call(), or use the member functions on VImage to get type-safe calls for at least the required operator arguments. The VImage class also adds automatic reference counting, constant expansion, operator overloads, and various other useful features. @@ -151,7 +151,7 @@ VImage VImage::invert( VOption *options ) Languages like Ruby, Python, JavaScript and Lua can’t call C directly, but they do support FFI. The bindings for these languages work rather like C++, but use FFI to call into libvips and run operations. - Since these languages are dynamic, they can add another trick: they intercept the method-missing hook and attempt to run any method calls not implemented by the Image class as libvips operators. This makes these bindings self-writing: they only contain a small amount of codeand just expose everything they find in the libvips class hierarchy. + Since these languages are dynamic, they can add another trick: they intercept the method-missing hook and attempt to run any method calls not implemented by the Image class as libvips operators. This makes these bindings self-writing: they only contain a small amount of code and just expose everything they find in the libvips class hierarchy. @@ -161,7 +161,7 @@ VImage VImage::invert( VOption *options ) - <literal>gobject-introspection</literal> + gobject-introspection The C source code to libvips has been marked up with special comments describing the interface in a standard way. These comments are read by the gobject-introspection package when libvips is compiled and used to generate a typelib, a description of how to call the library. Many languages have gobject-introspection packages: all you need to do to call libvips from your favorite language is to start g-o-i, load the libvips typelib, and you should have the whole library available. For example, from Python it’s as simple as: