fix up C docs intro
This commit is contained in:
John Cupitt
parent
ecf10f85a1
commit
c0c57f3f4a
@ -15,7 +15,7 @@
|
||||
<refpurpose>How to use the VIPS library from C</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 id="using-C">
|
||||
<refsect1 id="using-C-intro">
|
||||
<title>Introduction</title>
|
||||
<para>
|
||||
VIPS comes with a convenient, high-level C API. You should read the API
|
||||
@ -23,9 +23,12 @@
|
||||
overview. The <command>vips</command> program is handy for getting a
|
||||
summary of an operation's parameters.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="using-C-startup">
|
||||
<title>Library startup</title>
|
||||
<para>
|
||||
When your program starts, use <code>VIPS_INIT()</code>
|
||||
When your program starts, use VIPS_INIT()
|
||||
to start up the VIPS library. You should pass it the name
|
||||
of your program, usually <code>argv[0]</code>. Use
|
||||
vips_shutdown() when you exit.
|
||||
@ -33,17 +36,20 @@
|
||||
|
||||
<para>
|
||||
You can add the VIPS flags to your %GObject command-line processing
|
||||
with <code>vips_get_option_group()</code>, see below.
|
||||
with vips_add_option_entries(), see below.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="using-C-vipsimage">
|
||||
<title>The #VipsImage class</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -54,9 +60,12 @@
|
||||
See <link linkend="libvips-header">VIPS Header</link> to read about
|
||||
image properties.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="using-C-ref">
|
||||
<title>Reference counting</title>
|
||||
<para>
|
||||
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 @@
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Use things like vips_invert() to manipulate your images. See <link
|
||||
linkend="VipsOperation">VIPS Operations</link> for information on
|
||||
See #VipsOperation for more detail on VIPS
|
||||
reference counting conventions.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="using-C-operations">
|
||||
<title>VIPS operations</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="using-C-pixels">
|
||||
<title>Getting pixels</title>
|
||||
<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 introduction to writing your own operations.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="using-C-errors">
|
||||
<title>Error handling</title>
|
||||
|
||||
<para>
|
||||
VIPS keeps a log of error message, see <link
|
||||
linkend="libvips-error">VIPS Error</link> to find out how to get and
|
||||
set the error log.
|
||||
clear the error log.
|
||||
</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1 id="using-C-example">
|
||||
<title>Example</title>
|
||||
|
||||
<example>
|
||||
<title>VIPS from C example</title>
|
||||
@ -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 );
|
||||
}
|
||||
</programlisting>
|
||||
</example>
|
||||
|
||||
@ -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.
|
||||
*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user