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