my $outname = shift || '-';
-
my @funcs = make_func_list();
my %funcs = map { $_ => 1 } @funcs;
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";
if ($synopsis) {
$funcsyns{$func} = $synopsis;
}
+ defined $order or $order = 50;
+ $order{$func} = $order;
}
undef $func;
undef $category;
+ undef $order;
$synopsis = '';
}
elsif ($func) {
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, $_;
}
=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;
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};
# 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";
}
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;
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<category-name>
+
+The category the function should be in.
+
+=item =synopsis I<sample-code>
+
+Sample code using the function to include in the Imager::APIRef SYNOPSIS
+
+=item =order I<integer>
+
+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 <tonyc@cpan.org>
+
+=cut
+
=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
# 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
=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<c.cmyk.y>. Note that
+Imager never uses CMYK colors except when reading/writing files.
+
+=item *
+
+channels - an array of four channels, eg C<c.channels[2]>.
+
+=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
=item i_clear_error()
-
Clears the error stack.
Called by any imager function before doing any other processing.
=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
=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
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
=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)
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
=back
-=head2 Image creation
+=head2 Image creation/destruction
=over
=for comment
From: File img16.c
-
-=back
-
-=head2 Image creation/destruction
-
-=over
-
=item i_img_8_new(x, y, ch)
I<ch> channels.
-=for comment
-From: File image.c
-
-=item i_img_destroy(img)
-
-
-Destroy an image object
-
-
=for comment
From: File image.c
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
=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<im>.
+
+
+=for comment
+From: File image.c
+
+=item i_img_getmask(im)
+
+Get the image channel mask for I<im>.
+
+
+=for comment
+From: File image.c
+
=item i_img_has_alpha(im)
=for comment
From: File immacros.h
+=item i_img_setmask(im, ch_mask)
+
+Set the image channel mask for I<im> to I<ch_mask>.
+
+The image channel mask gives some control over which channels can be
+written to in the image.
+
+
+=for comment
+From: File image.c
+
=back
=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.
=item i_tags_set(tags, name, data, size)
-
Sets the given tag to the string I<data>
+If size is -1 then the strlen(I<data>) bytes are stored.
+
+Even on failure, if an existing tag I<name> exists, it will be
+removed.
+
=for comment
From: File tags.c
=item i_tags_setn(tags, name, idata)
-
Sets the given tag to the integer I<idata>
-
-=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<im>.
-
-
-=for comment
-From: File image.c
-
-=item i_img_getmask(im)
-
-
-Get the image channel mask for I<im>.
+Even on failure, if an existing tag I<name> 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<im> to I<ch_mask>.
-
-
-=for comment
-From: File image.c
-
-
-
-=back
-
-
-=head1 UNDOCUMENTED
-
-The following API functions are undocumented so far, hopefully this
-will change:
-
-=over
-
-=item *
-
-B<i_color>
-
-=item *
-
-B<i_fcolor>
-
-=item *
-
-B<i_fill_t>
-
-=item *
-
-B<i_lhead>
-
+From: File tags.c
=back
projects / imager.git / commitdiff