From b7f16a1de90e88ac74fb9e7251c32f0a7ef54246 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Mon, 16 Jun 2014 14:28:00 +0100 Subject: [PATCH] more docs work --- TODO | 4 ++ libvips/foreign/vipssave.c | 1 + libvips/include/vips/image.h | 7 +-- libvips/include/vips/internal.h | 3 ++ libvips/iofuncs/image.c | 75 +++++++++++++++++++++++---------- 5 files changed, 63 insertions(+), 27 deletions(-) diff --git a/TODO b/TODO index 165f77e2..814c5f71 100644 --- a/TODO +++ b/TODO @@ -1,3 +1,7 @@ +- the docs reference vips__temp_name() several times, but we don't doc it + + where should we discuss the temporary directory? vips_image_new_temp_file() + I guess. What about vips_system()? - check and fix up docs diff --git a/libvips/foreign/vipssave.c b/libvips/foreign/vipssave.c index bcb5ffa6..a502418e 100644 --- a/libvips/foreign/vipssave.c +++ b/libvips/foreign/vipssave.c @@ -46,6 +46,7 @@ #include #include +#include typedef struct _VipsForeignSaveVips { VipsForeignSave parent_object; diff --git a/libvips/include/vips/image.h b/libvips/include/vips/image.h index ee0e73c8..364215b3 100644 --- a/libvips/include/vips/image.h +++ b/libvips/include/vips/image.h @@ -406,13 +406,9 @@ void vips_image_minimise_all( VipsImage *image ); void vips_image_set_progress( VipsImage *image, gboolean progress ); -gboolean vips_image_iskilled( VipsImage *image ); -void vips_image_set_kill( VipsImage *image, gboolean kill ); - VipsImage *vips_image_new( void ); -VipsImage *vips_image_new_mode( const char *filename, const char *mode ); VipsImage *vips_image_new_memory( void ); -VipsImage *vips_image_new_from_file( const char *filename, ... ) +VipsImage *vips_image_new_from_file( const char *name, ... ) __attribute__((sentinel)); VipsImage *vips_image_new_from_file_RW( const char *filename ); VipsImage *vips_image_new_from_file_raw( const char *filename, @@ -448,6 +444,7 @@ gboolean vips_image_ispartial( VipsImage *image ); int vips_image_wio_input( VipsImage *image ); int vips_image_pio_input( VipsImage *image ); +int vips_image_pio_output( VipsImage *image ); int vips_image_inplace( VipsImage *image ); int vips_image_write_prepare( VipsImage *image ); diff --git a/libvips/include/vips/internal.h b/libvips/include/vips/internal.h index 8d131f1b..f0ba29de 100644 --- a/libvips/include/vips/internal.h +++ b/libvips/include/vips/internal.h @@ -147,6 +147,9 @@ int vips_image_written( VipsImage *image ); void vips_image_preeval( VipsImage *image ); void vips_image_eval( VipsImage *image, guint64 processed ); void vips_image_posteval( VipsImage *image ); +gboolean vips_image_iskilled( VipsImage *image ); +void vips_image_set_kill( VipsImage *image, gboolean kill ); +VipsImage *vips_image_new_mode( const char *filename, const char *mode ); int vips__formatalike_vec( VipsImage **in, VipsImage **out, int n ); int vips__sizealike_vec( VipsImage **in, VipsImage **out, int n ); diff --git a/libvips/iofuncs/image.c b/libvips/iofuncs/image.c index a884fbfe..7986b462 100644 --- a/libvips/iofuncs/image.c +++ b/libvips/iofuncs/image.c @@ -1531,6 +1531,20 @@ vips_image_set_progress( VipsImage *image, gboolean progress ) image->progress_signal = NULL; } + +/** + * vips_image_iskilled: + * @image: image to test + * + * If @image has been killed (see vips_image_kill()), set an error message, + * clear the #VipsImage.kill flag and return %FALSE. Otherwise return %TRUE. + * + * Handy for loops which need to run sets of threads which can fail. + * + * See also: vips_image_kill(). + * + * Returns: %FALSE if @image has been killed. + */ gboolean vips_image_iskilled( VipsImage *image ) { @@ -1555,6 +1569,18 @@ vips_image_iskilled( VipsImage *image ) return( kill ); } +/** + * vips_image_set_kill: + * @image: image to test + * @kill: the kill state + * + * Set the #VipsImage.kill flag on an image. Handy for stopping sets of + * threads. + * + * See also: vips_image_iskilled(). + * + * Returns: %FALSE if @image has been killed. + */ void vips_image_set_kill( VipsImage *image, gboolean kill ) { @@ -1582,10 +1608,12 @@ vips_image_temp_name( void ) /** * vips_image_new: * - * vips_image_new() creates a "glue" descriptor you can use to join two image - * processing operations together. + * 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. * - * It is the equivalent of vips_image_new_mode("xxx", "p"). + * It is the equivalent of + * vips_image_new_mode() with @mode "p". * * Returns: the new #VipsImage, or %NULL on error. */ @@ -1636,8 +1664,11 @@ vips_image_new_mode( const char *filename, const char *mode ) * vips_image_new_memory: * * 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(vips_image_temp_name(), "t"). + * 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(). * @@ -1671,7 +1702,8 @@ vips_image_new_memory( void ) * 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 hint the expected access pattern for this file. + * @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 @@ -1749,8 +1781,8 @@ vips_image_new_from_file( const char *name, ... ) * vips_image_new_from_file_RW: * @filename: filename to open * - * Opens the named file for reading and writing. This will only work for - * VIPS files in a format native to your machine. It is only for + * 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(). @@ -1775,9 +1807,9 @@ vips_image_new_from_file_RW( const char *filename ) * 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. + * vips_copy() to transform the descriptor after loading it. * - * See also: im_copy_set(), im_raw2vips(), vips_image_new_from_file(). + * See also: vips_copy(), vips_rawload(), vips_image_new_from_file(). * * Returns: the new #VipsImage, or %NULL on error. */ @@ -1823,7 +1855,7 @@ vips_image_new_from_file_raw( const char *filename, * 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 #VipsObject::close. * - * Use vips_copy_morph() to set other image properties. + * Use vips_copy() to set other image properties. * * See also: vips_image_new(), vips_image_write_to_memory(). * @@ -1917,7 +1949,7 @@ vips_image_new_from_buffer( void *buf, size_t len, * @height: image height * * This convenience function makes an image which is a matrix: a one-band - * VIPS_FORMAT_DOUBLE image held in memory. + * #VIPS_FORMAT_DOUBLE image held in memory. * * Use VIPS_IMAGE_ADDR(), or VIPS_MATRIX() to address pixels in the image. * @@ -2002,7 +2034,7 @@ vips_image_new_matrixv( int width, int height, ... ) * * This function is clearly extremely dangerous, use with great caution. * - * See also: vips__temp_name(), vips_image_new_temp_file(). + * See also: vips_image_new_temp_file(). */ void vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close ) @@ -2021,7 +2053,7 @@ vips_image_set_delete_on_close( VipsImage *image, gboolean delete_on_close ) * @format: format of file * * Make a "w" disc #VipsImage which will be automatically unlinked when it is - * destroyed. @format is something like "%s.v" for a vips file. + * destroyed. @format is something like "%s.v" for a vips file. * * The file is created in the temporary directory, see vips__temp_name(). * @@ -2078,10 +2110,10 @@ vips_image_write_gen( VipsRegion *or, * @image: image to write * @out: write to this image * - * Write @image to @out. Use vips_image_new_mode() and friends to create the + * Write @image to @out. Use vips_image_new() and friends to create the * #VipsImage you want to write to. * - * See also: vips_image_new_mode(), vips_copy(), vips_image_write_to_file(). + * See also: vips_image_new(), vips_copy(), vips_image_write_to_file(). * * Returns: 0 on success, or -1 on error. */ @@ -2259,7 +2291,7 @@ vips_image_write_to_memory( VipsImage *in, void **buf_out, size_t *len_out ) * @out: write to this image * * A convenience function to unpack to a format that we can compute with. - * @out->Coding is always VIPS_CODING_NONE. + * @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. @@ -2490,7 +2522,7 @@ vips_image_write_prepare( VipsImage *image ) * @linebuffer: scanline of pixels * * Write a line of pixels to an image. This function must be called repeatedly - * with @ypos increasing from 0 to @YSize - + * with @ypos increasing from 0 to #VipsImage.height . * @linebuffer must be VIPS_IMAGE_SIZEOF_LINE() bytes long. * * See also: vips_image_generate(). @@ -2630,8 +2662,7 @@ vips_image_rewind_output( VipsImage *image ) * If it * isn't, try to transform it so that VIPS_IMAGE_ADDR() can work. * - * See also: vips_image_wio_output(), vips_image_pio_input(), - * vips_image_inplace(), VIPS_IMAGE_ADDR(). + * See also: vips_image_pio_input(), vips_image_inplace(), VIPS_IMAGE_ADDR(). * * Returns: 0 on succeess, or -1 on error. */ @@ -2778,11 +2809,11 @@ vips__image_wio_output( VipsImage *image ) * vips_image_inplace: * @image: image to make read-write * - * Gets @image ready for an in-place operation, such as im_insertplace(). + * 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: im_insertplace(), vips_image_wio_input(). + * See also: vips_draw_circle(), vips_image_wio_input(). * * Returns: 0 on succeess, or -1 on error. */