view release on metacpan or  search on metacpan

index.dox  view on Meta::CPAN

to STDOUT.

\section index_named_params Named parameters

Quite many methods and subroutines in Geo::GDAL accept named
parameters. In all cases the named parameters are handled with the
same filter, which accepts either a list of parameters (the order is
the order in which the named parameters are described in this
documentation), single hash reference, or a list of key value pairs.
The keys are given in the documentation but the filter ignores case
and underscores. Thus, although the name of the parameter is
ProgressData, the method will happily recognize also progress_data.

\section index_progress Progress callback

Some methods accept a callback function for reporting the
progress. The progress subroutine is called with three arguments: a
number, a string, and user defined data. The user defined data
is an argument to the method.

\code
sub progress {
    my($progress, $message, $data) = @_;
    my $terminate = 0;
    ...
    return $terminate ? 0 : 1;
}
\endcode

\section index_stdout_redirection Redirecting stdout to a writer object

The Perl bindings takes advantage of the virtual file system of GDAL
and offers a way to redirect the output from a format driver to a Perl
object. The object needs to implement \c write and \c close
methods. \c write is called for each output from the driver with the
output byte string as an argument. \c close is called when the dataset
being used in the creation is destroyed. Note that the destruction of
the dataset may depend on destruction of all objects that depend on
it. For a simple example see page \ref streaming.

Due to the limitation of the redirection mechanism only one redirection
may be active at any time.

Note that the return value of the \c write method does not have any
effect. Internally the return value is set to the length of the byte
string.

\section index_refcount Reference counting

In GDAL many objects may depend on other objects to exist, for example
a geometry, which is an attribute of a feature depends on the feature
to exist when the geometry is accessed. If a feature is destroyed,
then using a geometry object, which points for its data into the
feature, will lead to memory error.

GDAL maintains its own reference counting but this is largely lost in
the bindings.

The Perl bindings attempt to maintain these dependencies by keeping
the parent objects alive under the hood, independent of their existence
in the user space. Thus it is perfectly legal to do something like

\code
my $layer = Geo::OGR::Driver('Memory')->
    Create()->
        CreateLayer(Name => 'layer',
                    Fields => [{Name => 'test', Type => 'Integer'},
                               {Name => 'geom', Type => 'Point'}]);
\endcode

or

\code
my $geometry;
{
    my $feature = $layer->InsertFeature({test => 13, geom => {WKT => 'POINT (10 20)'}});
    $geometry = $feature->Geometry('geom');
}
say $geometry->AsText;
\endcode

There is at least one caveat. Swig sets the bindings up in such a way
that the objects are tied hashes. For example a feature can used as a
hash.

\code
my $feature = $lauer->InsertFeature({test => 13, geom => {WKT => 'POINT (10 20)'}});
my $test = $feature->{test};
\endcode

Due to the mechanism of tied hashes in Perl it is not possible to
maintain the parent referencing when using this syntax. Thus do not
use this for subobjects. (In fact it will create an error.)

\code
my $feature = $lauer->InsertFeature({test => 13, geom => {WKT => 'POINT (10 20)'}});
my $geom = $feature->{geom}; # will lead to memory error!
\endcode

\section index_footer Note

This documentation is generated from files within the GDAL
distribution (directory swig/perl) with Doxygen using a Perl module <a
href="http://search.cpan.org/~jordan/Doxygen-Filter-Perl/">Doxygen::Filter::Perl</a>.
A tailor made preprocessor in the GDAL distribution is used to process
and put all Perl code and documentation into a single file (all.pm)
for Doxygen-Filter-Perl and Doxygen.

Many methods are just interfaces to non-Perl code in the bindings or
GDAL and thus their code show as blank on these pages. The bindings
are created with Swig, which adds some methods by default.

Code examples in method pages contain dots ('.') to enforce
indentation. This is due to a doxygen bug.

*/