File Coverage

blib/lib/Math/Geometry/Planar/GPC/PolygonXS.pm
Criterion Covered Total %
statement 21 21 100.0
branch n/a
condition n/a
subroutine 5 5 100.0
pod 2 2 100.0
total 28 28 100.0


line stmt bran cond sub pod time code
1             package Math::Geometry::Planar::GPC::PolygonXS;
2            
3 1     1   17786 use 5.012000;
  1         2  
  1         31  
4 1     1   4 use strict;
  1         2  
  1         30  
5 1     1   3 use warnings;
  1         5  
  1         286  
6            
7             require Exporter;
8            
9             our @ISA = qw(Exporter);
10            
11             # Items to export into callers namespace by default. Note: do not export
12             # names by default without a very good reason. Use EXPORT_OK instead.
13             # Do not simply export all your public functions/methods/constants.
14            
15             # This allows declaration use Math::Geometry::Planar::GPC::PolygonXS ':all';
16             # If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
17             # will save memory.
18             our %EXPORT_TAGS = ( 'all' => [ qw(
19             ) ] );
20            
21             our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
22            
23             our @EXPORT = qw(
24             new_gpc
25             );
26            
27             our $VERSION = '0.052';
28            
29             require XSLoader;
30             XSLoader::load('Math::Geometry::Planar::GPC::PolygonXS', $VERSION);
31            
32            
33             =pod
34            
35             =head1 NAME
36            
37             Math::Geometry::Planar::GPC::PolygonXS - OO wrapper to gpc library
38             (translated from Inline-based Math::Geometry::Planar::GPC::Polygon to XS)
39            
40             =head1 Status
41            
42             Successfully used in minor production use under perl 5.6.1 and 5.8.3.
43             Your mileage may vary (see NO WARRANTY.)
44            
45             =head1 AUTHOR
46            
47             Eric L. Wilhelm
48             ewilhelm at sbcglobal dot net
49             http://pages.sbcglobal.net/mycroft/
50            
51             =head1 Copyright
52            
53             Copyright 2004 Eric L. Wilhelm
54            
55             =head1 License
56            
57             This module and its C source code (functions.c) are distributed under
58             the same terms as Perl. See the Perl source package for details.
59            
60             You may use this software under one of the following licenses:
61            
62             (1) GNU General Public License
63             (found at http://www.gnu.org/copyleft/gpl.html)
64             (2) Artistic License
65             (found at http://www.perl.com/pub/language/misc/Artistic.html)
66            
67            
68             The General Polygon Clipping library (gpc.c and gpc.h) is distributed as
69             "free for non-commercial use". See gpc.c for details. A copy of these
70             files has been included with this distribution strictly for convenience
71             purposes, but YOU ARE RESPONSIBLE FOR ADHERING TO BOTH THE GPC LICENSE
72             AND THE LICENSE OF THIS MODULE. Note that the C library is authored by
73             Alan Murta.
74            
75             You may want to check the GPC home page for a more current version:
76            
77             http://www.cs.man.ac.uk/aig/staff/alan/software/
78            
79             =head1 Portability
80            
81             This module successfully compiles on i386 and solaris architectures
82             according to the cpan testers results. Hopefully, versions after 0.04
83             will work on WIN32. I don't have any non-linux machines, so feel free
84             to send patches.
85            
86             =head1 NO WARRANTY
87            
88             This code comes with ABSOLUTELY NO WARRANTY of any kind.
89            
90             =head1 Changes
91            
92             0.01 - First public release.
93             0.02 - Added API documentation.
94             0.03 - Fix to allocation error.
95             Possibly Fixed WIN32 compile problem?
96             0.04 - Twiddling with WIN32 compile problem (last try)
97             0.05 - Corrected license statements.
98            
99             =cut
100             ########################################################################
101            
102             =head1 Constructors
103            
104             =head2 new
105            
106             Traditional constructor, returns a blessed reference to the underlying C struct.
107            
108             use Math::Geometry::Planar::GPC::Polygon;
109             my $gpc = Math::Geometry::Planar::GPC::Polygon->new();
110            
111             =head2 new_gpc
112            
113             An optionally imported constructor, for those of you who don't like to
114             type so much.
115            
116             use Math::Geometry::Planar::GPC::Polygon qw(new_gpc);
117             my $gpc = new_gpc();
118            
119             =cut
120             sub new_gpc {
121 1     1 1 708 my $class = __PACKAGE__;
122 1         6 return(new($class));
123             } # end subroutine new_gpc definition
124             ########################################################################
125            
126             =head1 Bound Functions
127            
128             These are the functions provide by the Inline-C code. See functions.c
129             in the source package for intimate details.
130            
131             =cut
132             ########################################################################
133            
134             =head2 from_file
135            
136             Loads a from a file into your gpc object. See the GPC library
137             documentation for details.
138            
139             $gpc->from_file($filename, $want_hole);
140            
141             =cut
142            
143             =head2 to_file
144            
145             Writes to a file.
146            
147             $gpc->to_file($filename, $want_hole);
148            
149             =cut
150            
151             =head2 clip_to
152            
153             Clips the $gpc object to the $othergpc object.
154            
155             $action may be any of the following:
156            
157             INTERSECT
158             DIFFERENCE
159             UNION
160            
161             $gpc->clip_to($othergpc, $action);
162            
163             Be wary. This interface may need to change.
164            
165             =cut
166            
167             =head2 add_polygon
168            
169             Adds a polygon to the gpc object. @points is a list of array references
170             which describe the point of the polygon. $hole is 1 or 0 (0 to not add
171             a hole.)
172            
173             $gpc->add_polygon(\@points, $hole);
174            
175             =cut
176            
177             =head2 get_polygons
178            
179             Gets the polygons from the gpc object. I'm not sure how to tell you if
180             they are holes or not. @pgons will be a list of refs to lists of refs.
181            
182             @pgons = $gpc->get_polygons();
183            
184             =cut
185            
186             ########################################################################
187            
188            
189             =head1 Helper Functions
190            
191             Pure-perl implementation from here down.
192            
193             =cut
194             ########################################################################
195            
196             =head2 as_string
197            
198             $gpc->as_string();
199            
200             =cut
201             sub as_string {
202 4     4 1 5434 my $self = shift;
203 4         37 my @pgons = $self->get_polygons();
204 4         4 my @strings;
205 4         8 foreach my $pgon (@pgons) {
206             # print "pgon is $pgon\n";
207             # print "@$pgon\n";
208 10         8 my @pts;
209 10         12 foreach my $pt (@$pgon) {
210 58         69 push(@pts, join(", ", map({sprintf("%0.3f", $_)} @$pt)));
  116         379  
211             }
212 10         33 push(@strings, "\t" . join("\n\t", @pts));
213             }
214 4         62 return(join("\n\n", @strings));
215             } # end subroutine as_string definition
216             ########################################################################
217             1;
218             __END__