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

improve the using-C docs

Browse Source 
add some stuff on giving options to operations

see https://github.com/jcupitt/libvips/issues/373
This commit is contained in:
John Cupitt 2016-01-25 09:35:06 +00:00
parent 07a1903390
commit 73bcc8b5d3
3 changed files with 87 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
ChangeLog
View File

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

20
doc/gtk-doc.make
View File

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

99
doc/using-C.xml
View File

@ -20,8 +20,7 @@
<para>
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 <command>vips</command> program is handy for getting a
summary of an operation's parameters.
overview.
</para>
</refsect3>
@ -38,7 +37,7 @@
<para>
You can add the VIPS flags to your %GObject command-line processing
with vips_add_option_entries(), see below.
with vips_add_option_entries().
</para>
</refsect3>
@ -85,10 +84,78 @@
<refsect3 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
Use things like vips_embed() to manipulate your images. You use it from
C like this:
<programlisting language="C">
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, &amp;out, x, y, width, height, NULL))
error_handling();
</programlisting>
Now <code>out</code> will hold a reference to a 1000 by 1000 pixel
image, with <code>in</code> pasted 10 right and 10 down from the top
left-hand corner. The remainder of the image will be black. If
<code>in</code> is too large, it will be clipped at the image edges.
</para>
<para>
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:
<programlisting language="C">
if (vips_embed (in, &amp;out, x, y, width, height,
"extend", VIPS_EXTEND_COPY,
NULL))
error_handling();
</programlisting>
And now the new edge pixels, which were black, will be filled with a copy
of the edge pixels of <code>in</code>. Operation options are listed
at the top of each operation's entry in the docs. Alternatively,
the <command>vips</command> program is handy for getting a
summary of an operation's parameters. For example:
<programlisting language="none">
$ 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
</programlisting>
See #VipsOperation for more information on running operations on images.
</para>
<para>
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>
@ -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, &amp;argc, &amp;argv, &amp;error ) ) {
if( error ) {
fprintf( stderr, "%s\n", error-&gt;message );
g_error_free( error );
}
vips_error_exit( NULL );
}
if( argc != 3 )
vips_error_exit( "usage: %s infile outfile", argv[0] );