From: Tony Cook Date: Mon, 7 Sep 2009 14:06:01 +0000 (+0000) Subject: API documentation (mostly) X-Git-Tag: Imager-0.71~16 X-Git-Url: http://git.imager.perl.org/imager.git/commitdiff_plain/6cfee9d1ec893f4947a6fd8c3472aad44b813ca8 API documentation (mostly) --- diff --git a/Makefile.PL b/Makefile.PL index 22f9ae9b..53966a42 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -232,7 +232,7 @@ imconfig.h : Makefile.PL $(PERLRUN) Makefile.PL $(ECHO) "==> Your Makefile has been rebuilt - re-run your make command <==" '.qq! -lib/Imager/APIRef.pod : \$(C_FILES) apidocs.perl +lib/Imager/APIRef.pod : \$(C_FILES) \$(H_FILES) apidocs.perl $perl apidocs.perl lib/Imager/APIRef.pod !.join('', map _im_rule($perl, $_), @ims) diff --git a/apidocs.perl b/apidocs.perl index 7aaa5f62..87c79b3c 100644 --- a/apidocs.perl +++ b/apidocs.perl @@ -4,7 +4,6 @@ use ExtUtils::Manifest 'maniread'; my $outname = shift || '-'; - my @funcs = make_func_list(); my %funcs = map { $_ => 1 } @funcs; @@ -24,6 +23,8 @@ my %funccats; my %cats; my $synopsis = ''; my %funcsyns; +my $order; +my %order; for my $file (@files) { open SRC, "< $file" or die "Cannot open $file for documentation: $!\n"; @@ -44,9 +45,12 @@ for my $file (@files) { if ($synopsis) { $funcsyns{$func} = $synopsis; } + defined $order or $order = 50; + $order{$func} = $order; } undef $func; undef $category; + undef $order; $synopsis = ''; } elsif ($func) { @@ -56,6 +60,11 @@ for my $file (@files) { elsif (/^=synopsis (.*)/) { $synopsis .= "$1\n"; } + elsif (/^=order (.*)$/) { + $order = $1; + $order =~ /^\d+$/ + or die "=order must specify a number for $func in $file\n"; + } else { push @funcdocs, $_; } @@ -79,18 +88,18 @@ you can find the documentation. =head1 NAME -Imager::APIRef - Imager's C API. +Imager::APIRef - Imager's C API - reference. =head1 SYNOPSIS i_color color; - color.rgba.red = 255; color.rgba.green = 0; color.rgba.blue = 255; + color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255; EOS for my $cat (sort { lc $a cmp lc $b } keys %cats) { print OUT "\n # $cat\n"; - for my $func (grep $funcsyns{$_}, sort @{$cats{$cat}}) { + for my $func (grep $funcsyns{$_}, sort { $order{$a} <=> $order{$b} } @{$cats{$cat}}) { my $syn = $funcsyns{$func}; $syn =~ s/^/ /gm; print OUT $syn; @@ -107,7 +116,11 @@ my %undoc = %funcs; for my $cat (sort { lc $a cmp lc $b } keys %cats) { print OUT "=head2 $cat\n\n=over\n\n"; - for my $func (sort @{$cats{$cat}}) { + my @ordered_funcs = sort { + $order{$a} <=> $order{$b} + || lc $a cmp lc $b + } @{$cats{$cat}}; + for my $func (@ordered_funcs) { print OUT @{$alldocs{$func}}, "\n"; print OUT "=for comment\nFrom: $from{$func}\n\n"; delete $undoc{$func}; @@ -118,12 +131,12 @@ for my $cat (sort { lc $a cmp lc $b } keys %cats) { # see if we have an uncategorized section if (grep $alldocs{$_}, keys %undoc) { print OUT "=head2 Uncategorized functions\n\n=over\n\n"; - for my $func (sort @funcs) { - if ($undoc{$func} && $alldocs{$func}) { - print OUT @{$alldocs{$func}}, "\n"; - print OUT "=for comment\nFrom: $from{$func}\n\n"; - delete $undoc{$func}; - } + #print join(",", grep !exists $order{$_}, @funcs), "\n"; + for my $func (sort { $order{$a} <=> $order{$b} || $a cmp $b } + grep $undoc{$_} && $alldocs{$_}, @funcs) { + print OUT @{$alldocs{$func}}, "\n"; + print OUT "=for comment\nFrom: $from{$func}\n\n"; + delete $undoc{$func}; } print OUT "\n\n=back\n\n"; } @@ -162,7 +175,7 @@ close OUT; sub make_func_list { - my @funcs = qw(i_img i_color i_fcolor i_fill_t mm_log i_img_color_channels i_img_has_alpha); + my @funcs = qw(i_img i_color i_fcolor i_fill_t mm_log i_img_color_channels i_img_has_alpha i_img_dim); open FUNCS, "< imexttypes.h" or die "Cannot open imexttypes.h: $!\n"; my $in_struct; @@ -186,3 +199,45 @@ sub make_func_list { die "Found neither the start nor end of the functions structure\n"; } } + +=head1 NAME + +apidocs.perl - parse Imager's source for POD documenting the C API + +=head1 SYNOPSIS + + perl apidocs.perl lib/Imager/APIRef.pod + +=head1 DESCRIPTION + +Parses Imager's C sources, including .c, .h and .im files searching +for function documentation. + +Besides the normal POD markup, the following can be included: + +=over + +=item =category I + +The category the function should be in. + +=item =synopsis I + +Sample code using the function to include in the Imager::APIRef SYNOPSIS + +=item =order I + +Allows a function to be listed out of order. If this isn't specified +it defaults to 50, so a value of 10 will cause the function to be +listed at the beginning of its category, or 90 to list at the end. + +Functions with equal order are otherwise ordered by name. + +=back + +=head1 AUTHOR + +Tony Cook + +=cut + diff --git a/error.c b/error.c index 10c31195..a3f172b0 100644 --- a/error.c +++ b/error.c @@ -183,7 +183,7 @@ the mark. =over =item i_clear_error() - +=synopsis i_clear_error(); =category Error handling Clears the error stack. @@ -209,10 +209,11 @@ void i_clear_error() { /* =item i_push_error(int code, char const *msg) - +=synopsis i_push_error(0, "Yep, it's broken"); +=synopsis i_push_error(errno, "Error writing"); =category Error handling -Called by an imager function to push an error message onto the stack. +Called by an Imager function to push an error message onto the stack. No message is pushed if the stack is full (since this means someone forgot to call i_clear_error(), or that a function that doesn't do @@ -253,6 +254,8 @@ void i_push_error(int code, char const *msg) { Intended for use by higher level functions, takes a varargs pointer and a format to produce the finally pushed error message. +Does not support perl specific format codes. + =cut */ void i_push_errorvf(int code, char const *fmt, va_list ap) { @@ -271,11 +274,13 @@ void i_push_errorvf(int code, char const *fmt, va_list ap) { /* =item i_push_errorf(int code, char const *fmt, ...) - +=synopsis i_push_errorf(errno, "Cannot open file %s: %d", filename, errno); =category Error handling A version of i_push_error() that does printf() like formating. +Does not support perl specific format codes. + =cut */ void i_push_errorf(int code, char const *fmt, ...) { diff --git a/fills.c b/fills.c index ac9660a8..9bb2cb1f 100644 --- a/fills.c +++ b/fills.c @@ -180,7 +180,7 @@ static i_fill_solid_t base_solid_fill = /* =item i_fill_destroy(fill) - +=order 90 =category Fills =synopsis i_fill_destroy(fill); diff --git a/image.c b/image.c index 5dba629f..d1aa2082 100644 --- a/image.c +++ b/image.c @@ -480,7 +480,7 @@ i_img_exorcise(i_img *im) { /* =item i_img_destroy(img) - +=order 90 =category Image creation/destruction =synopsis i_img_destroy(img) @@ -537,12 +537,15 @@ i_img_info(i_img *im,int *info) { /* =item i_img_setmask(im, ch_mask) - +=category Image Information =synopsis // only channel 0 writeable =synopsis i_img_setmask(img, 0x01); Set the image channel mask for I to I. +The image channel mask gives some control over which channels can be +written to in the image. + =cut */ void @@ -551,8 +554,8 @@ i_img_setmask(i_img *im,int ch_mask) { im->ch_mask=ch_mask; } /* =item i_img_getmask(im) - -=synopsis mask = i_img_getmask(img); +=category Image Information +=synopsis int mask = i_img_getmask(img); Get the image channel mask for I. @@ -563,8 +566,8 @@ i_img_getmask(i_img *im) { return im->ch_mask; } /* =item i_img_getchannels(im) - -=synopsis channels = i_img_getchannels(img); +=category Image Information +=synopsis int channels = i_img_getchannels(img); Get the number of channels in I. @@ -575,8 +578,8 @@ i_img_getchannels(i_img *im) { return im->channels; } /* =item i_img_get_width(im) - -=synopsis width = i_img_get_width(im); +=category Image Information +=synopsis i_img_dim width = i_img_get_width(im); Returns the width in pixels of the image. @@ -589,8 +592,8 @@ i_img_get_width(i_img *im) { /* =item i_img_get_height(im) - -=synopsis height = i_img_get_height(im); +=category Image Information +=synopsis i_img_dim height = i_img_get_height(im); Returns the height in pixels of the image. diff --git a/imdatatypes.h b/imdatatypes.h index 21fe65ac..007ba101 100644 --- a/imdatatypes.h +++ b/imdatatypes.h @@ -22,6 +22,48 @@ typedef struct { i_sample_t c,m,y,k; } cmyk_color; typedef int undef_int; /* special value to put in typemaps to retun undef on 0 and 1 on 1 */ +/* +=item i_color +=category Data Types +=synopsis i_color black; +=synopsis black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0; + +Type for 8-bit/sample color. + +Samples as per; + + i_color c; + +i_color is a union of: + +=over + +=item * + +gray - contains a single element gray_color, eg. c.gray.gray_color + +=item * + +rgb - contains three elements r, g, b, eg. c.rgb.r + +=item * + +rgba - contains four elements r, g, b, a, eg. c.rgba.a + +=item * + +cmyk - contains four elements c, m, y, k, eg. C. Note that +Imager never uses CMYK colors except when reading/writing files. + +=item * + +channels - an array of four channels, eg C. + +=back + +=cut +*/ + typedef union { gray_color gray; rgb_color rgb; @@ -40,6 +82,17 @@ typedef struct { i_fsample_t r, g, b; } i_frgb_color_t; typedef struct { i_fsample_t r, g, b, a; } i_frgba_color_t; typedef struct { i_fsample_t c, m, y, k; } i_fcmyk_color_t; +/* +=item i_fcolor +=category Data Types + +This is the double/sample color type. + +Its layout exactly corresponds to i_color. + +=cut +*/ + typedef union { i_fgray_color_t gray; i_frgb_color_t rgb; @@ -107,12 +160,25 @@ typedef int (*i_f_gsamp_bits_t)(i_img *im, int x, int r, int y, unsigned *samp, typedef int (*i_f_psamp_bits_t)(i_img *im, int x, int r, int y, unsigned const *samp, const int *chans, int chan_count, int bits); +/* +=item i_img_dim +=category Data Types +=synopsis i_img_dim x; +=order 90 + +A signed integer type that represents an image dimension or ordinate. + +May be larger than int on some platforms. + +=cut +*/ typedef int i_img_dim; /* =item i_img =category Data Types =synopsis i_img *img; +=order 10 This is Imager's image type. @@ -270,10 +336,6 @@ typedef struct { */ - - - - /* bitmap mask */ struct i_bitmap { @@ -287,12 +349,6 @@ int btm_test(struct i_bitmap *btm,int x,int y); void btm_set(struct i_bitmap *btm,int x,int y); - - - - - - /* Stack/Linked list */ struct llink { @@ -421,6 +477,18 @@ typedef enum { i_fts_circle } i_ft_supersample; +/* +=item i_fill_t +=category Data Types +=synopsis i_fill_t *fill; + +This is the "abstract" base type for Imager's fill types. + +Unless you're implementing a new fill type you'll typically treat this +as an opaque type. + +=cut +*/ typedef struct i_fill_tag { diff --git a/img16.c b/img16.c index 028539d2..321821e0 100644 --- a/img16.c +++ b/img16.c @@ -145,7 +145,7 @@ typedef unsigned short i_sample16_t; /* =item i_img_16_new(x, y, ch) -=category Image creation +=category Image creation/destruction =synopsis i_img *img = i_img_16_new(width, height, channels); Create a new 16-bit/sample image. diff --git a/lib/Imager/API.pod b/lib/Imager/API.pod index cc8839e0..2f16868e 100644 --- a/lib/Imager/API.pod +++ b/lib/Imager/API.pod @@ -235,6 +235,16 @@ include Imager 0.48 as a PREREQ_PM: Imager => 0.48, }, +=item * + +Since you use Imager::ExtUtils in Makefile.PL (or Build.PL) you should +include Imager in your configure_requires: + + META_MERGE => + { + configure_requires => { Imager => "0.48" } + }, + =back =head1 AUTHOR diff --git a/lib/Imager/APIRef.pod b/lib/Imager/APIRef.pod index 8220a1af..320f0648 100644 --- a/lib/Imager/APIRef.pod +++ b/lib/Imager/APIRef.pod @@ -6,64 +6,76 @@ you can find the documentation. =head1 NAME -Imager::APIRef - Imager's C API. +Imager::APIRef - Imager's C API - reference. =head1 SYNOPSIS i_color color; - color.rgba.red = 255; color.rgba.green = 0; color.rgba.blue = 255; + color.rgba.r = 255; color.rgba.g = 0; color.rgba.b = 255; # Data Types i_img *img; + i_color black; + black.rgba.r = black.rgba.g = black.rgba.b = black.rgba.a = 0; + i_fill_t *fill; + i_img_dim x; # Drawing i_arc(im, 50, 50, 20, 45, 135, &color); + i_arc_cfill(im, 50, 50, 35, 90, 135, fill); i_arc_aa(im, 50, 50, 35, 90, 135, &color); i_arc_aa_cfill(im, 50, 50, 35, 90, 135, fill); - i_arc_cfill(im, 50, 50, 35, 90, 135, fill); + i_circle_aa(im, 50, 50, 45, &color); i_box(im, 0, 0, im->xsize-1, im->ysize-1, &color). - i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill); i_box_filled(im, 0, 0, im->xsize-1, im->ysize-1, &color); - i_circle_aa(im, 50, 50, 45, &color); - i_flood_cfill(im, 50, 50, fill); - i_flood_cfill_border(im, 50, 50, fill, border); + i_box_cfill(im, 0, 0, im->xsize-1, im->ysize-1, fill); i_flood_fill(im, 50, 50, &color); + i_flood_cfill(im, 50, 50, fill); i_flood_fill_border(im, 50, 50, &color, &border); + i_flood_cfill_border(im, 50, 50, fill, border); # Error handling + i_clear_error(); + i_push_error(0, "Yep, it's broken"); + i_push_error(errno, "Error writing"); + i_push_errorf(errno, "Cannot open file %s: %d", filename, errno); # Files + i_set_image_file_limits(500, 500, 1000000); i_get_image_file_limits(&width, &height, &bytes) i_i_int_check_image_file_limits(width, height, channels, sizeof(i_sample_t)) - i_set_image_file_limits(500, 500, 1000000); # Fills - i_fill_destroy(fill); - fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, - i_fr_triangle, 0, i_fts_grid, 9, 1, segs); + i_fill_t *fill = i_new_fill_solidf(&fcolor, combine); + i_fill_t *fill = i_new_fill_solid(&color, combine); i_fill_t *fill = i_new_fill_hatch(&fg_color, &bg_color, combine, hatch, custom_hatch, dx, dy); i_fill_t *fill = i_new_fill_hatchf(&fg_fcolor, &bg_fcolor, combine, hatch, custom_hatch, dx, dy); i_fill_t *fill = i_new_fill_image(src_img, matrix, x_offset, y_offset, combine); - i_fill_t *fill = i_new_fill_solid(&color, combine); - i_fill_t *fill = i_new_fill_solidf(&fcolor, combine); + fill = i_new_fill_fount(0, 0, 100, 100, i_ft_linear, i_ft_linear, + i_fr_triangle, 0, i_fts_grid, 9, 1, segs); + i_fill_destroy(fill); # Image - # Image creation - i_img *img = i_img_16_new(width, height, channels); - # Image creation/destruction i_img *img = i_img_8_new(width, height, channels); - i_img_destroy(img) - i_img *img = i_img_double_new(width, height, channels); - i_img *img = i_img_pal_new(width, height, channels, max_palette_size) i_img *img = i_sametype(src, width, height); i_img *img = i_sametype_chans(src, width, height, channels); + i_img *img = i_img_pal_new(width, height, channels, max_palette_size) + i_img *img = i_img_double_new(width, height, channels); + i_img *img = i_img_16_new(width, height, channels); + i_img_destroy(img) # Image Implementation # Image Information + // only channel 0 writeable + i_img_setmask(img, 0x01); + int mask = i_img_getmask(img); + int channels = i_img_getchannels(img); + i_img_dim width = i_img_get_width(im); + i_img_dim height = i_img_get_height(im); # Image quantization @@ -72,6 +84,9 @@ Imager::APIRef - Imager's C API. # Paletted images # Tags + i_tags_set(&img->tags, "i_comment", -1); + i_tags_setn(&img->tags, "i_xres", 204); + i_tags_setn(&img->tags, "i_yres", 196); =head1 DESCRIPTION @@ -171,6 +186,76 @@ i_f_psamp_bits - implements i_psamp_bits() for this image. =back +=for comment +From: File imdatatypes.h + +=item i_color + +Type for 8-bit/sample color. + +Samples as per; + + i_color c; + +i_color is a union of: + +=over + +=item * + +gray - contains a single element gray_color, eg. c.gray.gray_color + +=item * + +rgb - contains three elements r, g, b, eg. c.rgb.r + +=item * + +rgba - contains four elements r, g, b, a, eg. c.rgba.a + +=item * + +cmyk - contains four elements c, m, y, k, eg. C. Note that +Imager never uses CMYK colors except when reading/writing files. + +=item * + +channels - an array of four channels, eg C. + +=back + + +=for comment +From: File imdatatypes.h + +=item i_fcolor + +This is the double/sample color type. + +Its layout exactly corresponds to i_color. + + +=for comment +From: File imdatatypes.h + +=item i_fill_t + +This is the "abstract" base type for Imager's fill types. + +Unless you're implementing a new fill type you'll typically treat this +as an opaque type. + + +=for comment +From: File imdatatypes.h + +=item i_img_dim + +A signed integer type that represents an image dimension or ordinate. + +May be larger than int on some platforms. + + =for comment From: File imdatatypes.h @@ -505,7 +590,6 @@ From: File imext.c =item i_clear_error() - Clears the error stack. Called by any imager function before doing any other processing. @@ -516,8 +600,7 @@ From: File error.c =item i_push_error(int code, char const *msg) - -Called by an imager function to push an error message onto the stack. +Called by an Imager function to push an error message onto the stack. No message is pushed if the stack is full (since this means someone forgot to call i_clear_error(), or that a function that doesn't do @@ -529,9 +612,10 @@ From: File error.c =item i_push_errorf(int code, char const *fmt, ...) - A version of i_push_error() that does printf() like formating. +Does not support perl specific format codes. + =for comment From: File error.c @@ -542,6 +626,8 @@ From: File error.c Intended for use by higher level functions, takes a varargs pointer and a format to produce the finally pushed error message. +Does not support perl specific format codes. + =for comment From: File error.c @@ -601,15 +687,6 @@ From: File limits.c =over -=item i_fill_destroy(fill) - - -Call to destroy any fill object. - - -=for comment -From: File fills.c - =item i_new_fill_fount(xa, ya, xb, yb, type, repeat, combine, super_sample, ssample_param, count, segs) @@ -688,6 +765,14 @@ Create a solid fill based on a float color. If combine is non-zero then alpha values will be combined. +=for comment +From: File fills.c + +=item i_fill_destroy(fill) + +Call to destroy any fill object. + + =for comment From: File fills.c @@ -772,7 +857,7 @@ From: File rubthru.im =back -=head2 Image creation +=head2 Image creation/destruction =over @@ -787,13 +872,6 @@ Returns the image on success, or NULL on failure. =for comment From: File img16.c - -=back - -=head2 Image creation/destruction - -=over - =item i_img_8_new(x, y, ch) @@ -802,15 +880,6 @@ Creates a new image object I pixels wide, and I pixels high with I channels. -=for comment -From: File image.c - -=item i_img_destroy(img) - - -Destroy an image object - - =for comment From: File image.c @@ -854,6 +923,14 @@ Returns an image of the same type (sample size). For paletted images the equivalent direct type is returned. +=for comment +From: File image.c + +=item i_img_destroy(img) + +Destroy an image object + + =for comment From: File image.c @@ -920,6 +997,38 @@ The number of channels holding color information. =for comment From: File immacros.h +=item i_img_get_height(im) + +Returns the height in pixels of the image. + + +=for comment +From: File image.c + +=item i_img_get_width(im) + +Returns the width in pixels of the image. + + +=for comment +From: File image.c + +=item i_img_getchannels(im) + +Get the number of channels in I. + + +=for comment +From: File image.c + +=item i_img_getmask(im) + +Get the image channel mask for I. + + +=for comment +From: File image.c + =item i_img_has_alpha(im) @@ -929,6 +1038,17 @@ Return true if the image has an alpha channel. =for comment From: File immacros.h +=item i_img_setmask(im, ch_mask) + +Set the image channel mask for I to I. + +The image channel mask gives some control over which channels can be +written to in the image. + + +=for comment +From: File image.c + =back @@ -985,6 +1105,14 @@ From: File quant.c =over +=item i_lhead(file, line) + +This is an internal function called by the mm_log() macro. + + +=for comment +From: File log.c + =item i_loog(level, format, ...) This is an internal function called by the mm_log() macro. @@ -1255,9 +1383,13 @@ From: File tags.c =item i_tags_set(tags, name, data, size) - Sets the given tag to the string I +If size is -1 then the strlen(I) bytes are stored. + +Even on failure, if an existing tag I exists, it will be +removed. + =for comment From: File tags.c @@ -1295,93 +1427,14 @@ From: File tags.c =item i_tags_setn(tags, name, idata) - Sets the given tag to the integer I - -=for comment -From: File tags.c - - -=back - -=head2 Uncategorized functions - -=over - -=item i_img_get_height(im) - - -Returns the height in pixels of the image. - - -=for comment -From: File image.c - -=item i_img_get_width(im) - - -Returns the width in pixels of the image. - - -=for comment -From: File image.c - -=item i_img_getchannels(im) - - -Get the number of channels in I. - - -=for comment -From: File image.c - -=item i_img_getmask(im) - - -Get the image channel mask for I. +Even on failure, if an existing tag I exists, it will be +removed. =for comment -From: File image.c - -=item i_img_setmask(im, ch_mask) - - -Set the image channel mask for I to I. - - -=for comment -From: File image.c - - - -=back - - -=head1 UNDOCUMENTED - -The following API functions are undocumented so far, hopefully this -will change: - -=over - -=item * - -B - -=item * - -B - -=item * - -B - -=item * - -B - +From: File tags.c =back diff --git a/lib/Imager/Files.pod b/lib/Imager/Files.pod index 546cbcd5..b7d612bf 100644 --- a/lib/Imager/Files.pod +++ b/lib/Imager/Files.pod @@ -1252,7 +1252,7 @@ paletted image being returned as a direct color image. Default: 1 or die $img->errstr; This was introduced in Imager 0.60. Previously reading ICO images -acted as if C< 0>>. +acted as if C 0>. =back diff --git a/log.c b/log.c index 2f043a95..a32db1b5 100644 --- a/log.c +++ b/log.c @@ -90,6 +90,14 @@ i_loog(int level,const char *fmt, ... ) { } } +/* +=item i_lhead(file, line) +=category Logging + +This is an internal function called by the mm_log() macro. + +=cut +*/ void i_lhead(const char *file, int line) { diff --git a/tags.c b/tags.c index 2579f26b..6812a49e 100644 --- a/tags.c +++ b/tags.c @@ -83,7 +83,7 @@ void i_tags_new(i_img_tags *tags) { Adds a tag that has an integer value. A simple wrapper around i_tags_add(). -Duplicate tags can be added. +Use i_tags_setn() instead, this function may be removed in the future. Returns non-zero on success. @@ -99,7 +99,7 @@ int i_tags_addn(i_img_tags *tags, char const *name, int code, int idata) { Adds a tag to the tags list. -Duplicate tags can be added. +Use i_tags_set() instead, this function may be removed in the future. Returns non-zero on success. @@ -615,11 +615,16 @@ int i_tags_get_string(i_img_tags *tags, char const *name, int code, /* =item i_tags_set(tags, name, data, size) - +=synopsis i_tags_set(&img->tags, "i_comment", -1); =category Tags Sets the given tag to the string I +If size is -1 then the strlen(I) bytes are stored. + +Even on failure, if an existing tag I exists, it will be +removed. + =cut */ @@ -632,11 +637,15 @@ i_tags_set(i_img_tags *tags, char const *name, char const *data, int size) { /* =item i_tags_setn(tags, name, idata) - +=synopsis i_tags_setn(&img->tags, "i_xres", 204); +=synopsis i_tags_setn(&img->tags, "i_yres", 196); =category Tags Sets the given tag to the integer I +Even on failure, if an existing tag I exists, it will be +removed. + =cut */