/*! \page create_vector Creating a vector dataset

The code here does not have any warranty. It is recommended that
before using any of this code, you look into it and try to understand
what it does, what input it needs, etc. Do not blindly execute
anything!

This example creates a new layer to a named datasource. The layer will
contain polygon features and each feature will contain an integer as
an attribute value. The name of the attribute will be 'key'. Each
polygon will have four vertices. The SRS is explicitly set to WGS84.


\code
use Geo::GDAL;

# information that we need:
$dsname = ".";          # name of the datasource (in this case a directory)
$lname = "boxes";        # name of the layer
@data;                   # array which contains the data as hashref items,
                         # each item comprises items 'points' and 'key'
                         # 'points' is in this case an array of four points
                         # which are refs to arrays (x,y)
                         # 'key' is an integer which is stored as each
                         # feature's attribute data

@data = ({key => 'rect1', points => [[0,0],[1,0],[1,1],[0,1]]},
	 {key => 'rect2', points => [[5,5],[7,5],[7,6],[5,6]]});

$datasource = Geo::OGR::Driver('ESRI Shapefile')->Create($dsname) or die;

$osr = new Geo::OSR::SpatialReference;
$osr->SetWellKnownGeogCS('WGS84');

$layer = $datasource->CreateLayer({ Name => $lname, SRS => $osr, GeometryType => 'Polygon'});
$layer->Schema( Fields => 
		[{ Name => 'key', Type => 'Integer' }] );

# make sure the cells share the points

for $item (@data) {

    @ring = ($item->{points}[0], 
	     $item->{points}[1], 
	     $item->{points}[2], 
	     $item->{points}[3],
	     $item->{points}[0]);

    $layer->InsertFeature({ 
	key => $item->{key},
	Geometry => { Points => [ \@ring ] }
    });

}
\endcode

*/