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

more docs work

Browse Source
This commit is contained in:
John Cupitt 2014-06-16 14:28:00 +01:00
parent a76df77942
commit b7f16a1de9
5 changed files with 63 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
TODO
View File

@ -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

1
libvips/foreign/vipssave.c
View File

@ -46,6 +46,7 @@
#include <string.h>
#include <vips/vips.h>
#include <vips/internal.h>
typedef struct _VipsForeignSaveVips {
VipsForeignSave parent_object;

7
libvips/include/vips/image.h
View File

@ -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 );

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

@ -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 );

75
libvips/iofuncs/image.c
View File

@ -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 "&percnt;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.
*/