diff --git a/doc/reference/using-C.xml b/doc/reference/using-C.xml index 5e3f3af4..dee6054c 100644 --- a/doc/reference/using-C.xml +++ b/doc/reference/using-C.xml @@ -15,7 +15,7 @@ How to use the VIPS library from C - + Introduction VIPS comes with a convenient, high-level C API. You should read the API @@ -23,9 +23,12 @@ overview. The vips program is handy for getting a summary of an operation's parameters. + + + Library startup - When your program starts, use VIPS_INIT() + When your program starts, use VIPS_INIT() to start up the VIPS library. You should pass it the name of your program, usually argv[0]. Use vips_shutdown() when you exit. @@ -33,17 +36,20 @@ You can add the VIPS flags to your %GObject command-line processing - with vips_get_option_group(), see below. + with vips_add_option_entries(), see below. + + + The #VipsImage class The basic data object is the #VipsImage. You can create an image from a file on disc or from an area of memory, either as a C-style array, or as a formatted object, like JPEG. See vips_image_new_from_file() and friends. Loading an - image is fast. VIPS read just enough of the image to be able to get - the various properties, such as width in pixels. It delays reading - any pixels until they are really needed. + image is fast: VIPS read just enough of the image to be able to get + the various properties, such as width, but no decoding occurs until + pixel values are really needed. @@ -54,9 +60,12 @@ See VIPS Header to read about image properties. + + + Reference counting - VIPS is based on the %GObject library and is therefore refcounted. + VIPS is based on the %GObject library and is therefore reference counted. vips_image_new_from_file() returns an object with a count of 1. When you are done with an image, use g_object_unref() to dispose of it. If you pass an image to an operation and that operation needs to keep a @@ -66,25 +75,45 @@ - Use things like vips_invert() to manipulate your images. See VIPS Operations for information on + See #VipsOperation for more detail on VIPS + reference counting conventions. + + + + + VIPS operations + + Use things like vips_invert() to manipulate your images. See + #VipsOperation + for information on running operations on images. When you are done, you can write the final image to a disc file, to a formatted memory buffer, or to C-style memory array. See vips_image_write_to_file() and friends. + + + Getting pixels 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 extending for an introduction to writing your own operations. + + + + Error handling VIPS keeps a log of error message, see VIPS Error to find out how to get and - set the error log. + clear the error log. + + + + Example VIPS from C example @@ -100,55 +129,55 @@ int main( int argc, char **argv ) { - GOptionContext *context; - GOptionGroup *main_group; - GError *error = NULL; - VipsImage *in; - double mean; - VipsImage *out; + GOptionContext *context; + GOptionGroup *main_group; + GError *error = NULL; + VipsImage *in; + double mean; + VipsImage *out; - if( VIPS_INIT( argv[0] ) ) - vips_error_exit( NULL ); + if( VIPS_INIT( argv[0] ) ) + vips_error_exit( NULL ); - context = g_option_context_new( "hello infile outfile - VIPS demo" ); + context = g_option_context_new( "hello infile outfile - VIPS demo" ); - main_group = g_option_group_new( NULL, NULL, NULL, NULL, NULL ); - g_option_context_set_main_group( context, main_group ); - g_option_context_add_group( context, vips_get_option_group() ); + main_group = g_option_group_new( NULL, NULL, NULL, NULL, NULL ); + g_option_context_set_main_group( context, main_group ); + vips_add_option_entries( main_group ); - if( !g_option_context_parse( context, &argc, &argv, &error ) ) { - if( error ) { - fprintf( stderr, "%s\n", error->message ); - g_error_free( error ); - } + if( !g_option_context_parse( context, &argc, &argv, &error ) ) { + if( error ) { + fprintf( stderr, "%s\n", error->message ); + g_error_free( error ); + } - vips_error_exit( NULL ); - } + vips_error_exit( NULL ); + } - if( argc != 3 ) - vips_error_exit( "usage: %s infile outfile", argv[0] ); - - if( !(in = vips_image_new_from_file( argv[1], NULL )) ) - vips_error_exit( NULL ); + if( argc != 3 ) + vips_error_exit( "usage: %s infile outfile", argv[0] ); + + if( !(in = vips_image_new_from_file( argv[1], NULL )) ) + vips_error_exit( NULL ); - printf( "image width = %d\n", vips_image_get_width( in ) ); + printf( "image width = %d\n", vips_image_get_width( in ) ); - if( vips_avg( in, &mean, NULL ) ) - vips_error_exit( NULL ); + if( vips_avg( in, &mean, NULL ) ) + vips_error_exit( NULL ); - printf( "mean pixel value = %g\n", mean ); + printf( "mean pixel value = %g\n", mean ); - if( vips_invert( in, &out, NULL ) ) - vips_error_exit( NULL ); + if( vips_invert( in, &out, NULL ) ) + vips_error_exit( NULL ); - g_object_unref( in ); + g_object_unref( in ); - if( vips_image_write_to_file( out, argv[2], NULL ) ) - vips_error_exit( NULL ); + if( vips_image_write_to_file( out, argv[2], NULL ) ) + vips_error_exit( NULL ); - g_object_unref( out ); + g_object_unref( out ); - return( 0 ); + return( 0 ); } diff --git a/libvips/iofuncs/init.c b/libvips/iofuncs/init.c index c360ea5d..8da21350 100644 --- a/libvips/iofuncs/init.c +++ b/libvips/iofuncs/init.c @@ -160,7 +160,7 @@ vips_get_argv0( void ) * } * ]| * - * See also: vips_shutdown(), vips_get_option_group(), vips_version(), + * See also: vips_shutdown(), vips_add_option_entries(), vips_version(), * vips_guess_prefix(), vips_guess_libdir(). * * Returns: 0 on success, -1 otherwise @@ -1008,7 +1008,7 @@ vips_version( int flag ) * @leak: turn leak checking on or off * * Turn on or off vips leak checking. See also --vips-leak and - * vips_get_option_group(). + * vips_add_option_entries(). * * You should call this very early in your program. */