From 73bcc8b5d3f38aa4f5971d1fd7e6f224c61d9852 Mon Sep 17 00:00:00 2001 From: John Cupitt Date: Mon, 25 Jan 2016 09:35:06 +0000 Subject: [PATCH] improve the using-C docs add some stuff on giving options to operations see https://github.com/jcupitt/libvips/issues/373 --- ChangeLog | 1 + doc/gtk-doc.make | 20 ++++++---- doc/using-C.xml | 99 ++++++++++++++++++++++++++++++++++++------------ 3 files changed, 87 insertions(+), 33 deletions(-) diff --git a/ChangeLog b/ChangeLog index 0888781d..4f119364 100644 --- a/ChangeLog +++ b/ChangeLog @@ -10,6 +10,7 @@ - fix double free on attach ICC profile from file in tiff write [erdmann] - add VIPS_FLOOR()/VIPS_CEIL(), much faster [Lovell Fuller] - use g_assert_not_reached(); +- better vips-from-C docs 1/1/16 started 8.2.1 - add a compat stub [Benjamin Gilbert] diff --git a/doc/gtk-doc.make b/doc/gtk-doc.make index e7916563..9ccd0b04 100644 --- a/doc/gtk-doc.make +++ b/doc/gtk-doc.make @@ -25,6 +25,7 @@ TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) SETUP_FILES = \ $(content_files) \ + $(expand_content_files) \ $(DOC_MAIN_SGML_FILE) \ $(DOC_MODULE)-sections.txt \ $(DOC_MODULE)-overrides.txt @@ -86,7 +87,7 @@ GTK_DOC_V_SETUP_0=@echo " DOC Preparing build"; setup-build.stamp: -$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - files=`echo $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types`; \ + files=`echo $(SETUP_FILES) $(DOC_MODULE).types`; \ if test "x$$files" != "x" ; then \ for file in $$files ; do \ destdir=`dirname $(abs_builddir)/$$file`; \ @@ -118,7 +119,7 @@ scan-build.stamp: setup-build.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(GTK_DOC_V_INTROSPECT)if grep -l '^..*$$' $(DOC_MODULE).types > /dev/null 2>&1 ; then \ scanobj_options=""; \ gtkdoc-scangobj 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$(?)" = "0"; then \ + if test "$$?" = "0"; then \ if test "x$(V)" = "x1"; then \ scanobj_options="--verbose"; \ fi; \ @@ -162,17 +163,17 @@ GTK_DOC_V_XREF=$(GTK_DOC_V_XREF_$(V)) GTK_DOC_V_XREF_=$(GTK_DOC_V_XREF_$(AM_DEFAULT_VERBOSITY)) GTK_DOC_V_XREF_0=@echo " DOC Fixing cross-references"; -html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) $(GTK_DOC_V_HTML)rm -rf html && mkdir html && \ mkhtml_options=""; \ gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$(?)" = "0"; then \ + if test "$$?" = "0"; then \ if test "x$(V)" = "x1"; then \ mkhtml_options="$$mkhtml_options --verbose"; \ fi; \ fi; \ gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \ - if test "$(?)" = "0"; then \ + if test "$$?" = "0"; then \ mkhtml_options="$$mkhtml_options --path=\"$(abs_srcdir)\""; \ fi; \ cd html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) @@ -194,11 +195,11 @@ GTK_DOC_V_PDF=$(GTK_DOC_V_PDF_$(V)) GTK_DOC_V_PDF_=$(GTK_DOC_V_PDF_$(AM_DEFAULT_VERBOSITY)) GTK_DOC_V_PDF_0=@echo " DOC Building PDF"; -pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) +pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) $(expand_content_files) $(GTK_DOC_V_PDF)rm -f $(DOC_MODULE).pdf && \ mkpdf_options=""; \ gtkdoc-mkpdf 2>&1 --help | grep >/dev/null "\-\-verbose"; \ - if test "$(?)" = "0"; then \ + if test "$$?" = "0"; then \ if test "x$(V)" = "x1"; then \ mkpdf_options="$$mkpdf_options --verbose"; \ fi; \ @@ -223,12 +224,15 @@ clean-local: @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-types" ; then \ rm -f $(DOC_MODULE).types; \ fi + @if echo $(SCAN_OPTIONS) | grep -q "\-\-rebuild-sections" ; then \ + rm -f $(DOC_MODULE)-sections.txt; \ + fi distclean-local: @rm -rf xml html $(REPORT_FILES) $(DOC_MODULE).pdf \ $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt @if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \ - rm -f $(SETUP_FILES) $(expand_content_files) $(DOC_MODULE).types; \ + rm -f $(SETUP_FILES) $(DOC_MODULE).types; \ fi maintainer-clean-local: diff --git a/doc/using-C.xml b/doc/using-C.xml index afad197d..e9e7c04e 100644 --- a/doc/using-C.xml +++ b/doc/using-C.xml @@ -20,8 +20,7 @@ VIPS comes with a convenient, high-level C API. You should read the API docs for full details, but this section will try to give a brief - overview. The vips program is handy for getting a - summary of an operation's parameters. + overview. @@ -38,7 +37,7 @@ You can add the VIPS flags to your %GObject command-line processing - with vips_add_option_entries(), see below. + with vips_add_option_entries(). @@ -85,10 +84,78 @@ 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 + Use things like vips_embed() to manipulate your images. You use it from + C like this: + + +const char *filename; +VipsImage *in = vips_image_new_from_file (filename, NULL); +const int x = 10; +const int y = 10; +const int width = 1000; +const int height = 1000; +VipsImage *out; + +if (vips_embed (in, &out, x, y, width, height, NULL)) + error_handling(); + + + Now out will hold a reference to a 1000 by 1000 pixel + image, with in pasted 10 right and 10 down from the top + left-hand corner. The remainder of the image will be black. If + in is too large, it will be clipped at the image edges. + + + + Operations can take options. You give these as a set of NULL-terminated + name-value pairs at the end of the call. For example, you can write: + + +if (vips_embed (in, &out, x, y, width, height, + "extend", VIPS_EXTEND_COPY, + NULL)) + error_handling(); + + + And now the new edge pixels, which were black, will be filled with a copy + of the edge pixels of in. Operation options are listed + at the top of each operation's entry in the docs. Alternatively, + the vips program is handy for getting a + summary of an operation's parameters. For example: + + +$ vips embed +embed an image in a larger image +usage: + embed in out x y width height +where: + in - Input image, input VipsImage + out - Output image, output VipsImage + x - Left edge of input in output, input gint + default: 0 + min: -1000000000, max: 1000000000 + y - Top edge of input in output, input gint + default: 0 + min: -1000000000, max: 1000000000 + width - Image width in pixels, input gint + default: 1 + min: 1, max: 1000000000 + height - Image height in pixels, input gint + default: 1 + min: 1, max: 1000000000 +optional arguments: + extend - How to generate the extra pixels, input VipsExtend + default: black + allowed: black, copy, repeat, mirror, white, background + background - Colour for background pixels, input VipsArrayDouble +operation flags: sequential-unbuffered + + + See #VipsOperation for more 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. @@ -131,9 +198,6 @@ int main( int argc, char **argv ) { - GOptionContext *context; - GOptionGroup *main_group; - GError *error = NULL; VipsImage *in; double mean; VipsImage *out; @@ -141,21 +205,6 @@ main( int argc, char **argv ) if( VIPS_INIT( argv[0] ) ) vips_error_exit( NULL ); - 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 ); - 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 ); - } - - vips_error_exit( NULL ); - } - if( argc != 3 ) vips_error_exit( "usage: %s infile outfile", argv[0] );