[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.18.3 Perl Bindings

Crystal Space is accessible from Perl in two ways: (1) as a Crystal Space plugin module in which C++ code can call upon Perl code, and in which Perl code can call upon Crystal Space; (2) as a pure Perl module named `cspace' which one can `use' from within Perl programs. To use the first option, load the `csperl5' plugin as you would load any other Crystal Space plugin, and interact with it via the SCF `iScript' interface (see section The iScript Interface). The second approach allows you to write Crystal Space applications entirely in Perl, without any C++ coding. The rest of this document pertains to the second method of using Crystal Space from Perl, though much of the discussion is meaningful to both methods.

To make use of Crystal Space classes from a pure Perl script, first make sure that the file `cspace.pm' is available to Perl. This file is installed at:

${prefix}/share/crystalspace/bindings/perl5/cspace.pm

where `${prefix}' is the location at which Crystal Space was installed (typically, `/usr/local'). If you have not installed Crystal Space, then you can find this file in the top level build directory after building the project (the `CS' directory if you built and configured there). There are several ways to tell Perl where this file resides. One way is to use the `lib' pragma within your Perl code:

 
use lib "$ENV{CRYSTAL}/share/crystalspace/bindings/perl5";

You can also use Perl's `-I' command-line option to tell it the location of this file. Finally, you can set the `PERL5LIB' environment variable so that it mentions the directory containing `cspace.pm'.

In addition to the `.pm' file, there is also a shared library, `cspace', which contains the low-level bindings between Perl and Crystal Space. On Unix and MacOS/X, this file is named `cspace.so'; on Windows it is named `cspace.dll'. The shared library file should reside in the same directory as the `cspace.pm' file. This happens automatically when you install Crystal Space (via `make install' or `jam install'). If you have not installed Crystal Space, then the shared library will be in the top-level build directory, along with `cspace.pm'.

To actually utilize Crystal Space from within your script, begin with:

 
use cspace;

Getting Started

To get started with pure Perl scripts, you probably want to know how to initialize Crystal Space and obtain an `iObjectRegistry' pointer:

 
my $object_reg =
  cspace::csInitializer::CreateEnvironment([$0, @ARGV]);

Functions and Classes

Crystal Space has several global functions which can be accessed easily from Perl. For instance, in C++, one might say:

 
char const* str = "Hello, world!";
int key = csHashCompute(str);

Perl is almost exactly the same, the most notable difference is the cspace:: prefix:

 
my $str = "Hello, world!";
my $key = cspace::csHashCompute($str);

To create an object instance, use the `new' method:

 
my $vect = new cspace::csVector3(1, 2, 3);

The object will be deleted automatically when it goes out of scope. Perl also has built-in reference counting, so if the object is still referenced in some other Perl code when one reference goes out of scope, it will continue to exist until there are no more references to it in Perl.

There are three ways to access object properties:

 
print $vect->x;       # Preferred way, conforms to Perl convention
print $vect->{"x"}; # Swig's primary way
print $vect->get_x(); # Swig's secondary way

And, three ways to modify object properties:

 
$vect->x(123);        # Preferred way, conforms to Perl convention
$vect->{"x"} = 123; # Swig's primary way
$vect->set_x(123);    # Swig's secondary way

Calling methods works as you might expect:

 
$vect->Norm();

Arrays

Wherever an array is expected, or wherever an array is returned, in or from a Crystal Space C++ function, a Perl array reference is used.

Operator Overloading

Operator overloading is not yet supported. All the code required to support it has been written, but the code requires some non-existant features of Swig. The operators that exist in C++ and which Perl can overload are: + - * / % << >> & | ^ && || ! ~ < <= == >= > != ++ -- = += -= *= /= %= <<= >>= &= |= ^=

And: ** **= (expontentiation), lt le eq ge gt ne (string comparison), <> (iteration), x x= (repeat), . .= (concatenate), $ @ % * & (convert to Perl native types: scalar, array, hash, glob, subroutine), abs (absolute value), truth evaluation, stringify and numerify.

Interface Pointers

Suppose you call a function that returns a pointer to some SCF interface. You can store the returned value in a variable, and use it similarly to how objects are used in Perl (see above). You can call methods in the same way, and pass them on to other functions as arguments where appropriate.

The Perl bindings automatically and correctly handle csRef<> and csPtr<>.

Implementing Interfaces

You can write your own Perl class and have it inherit from a Crystal Space interface, then use instances of that class wherever an implementation of that interface is expected. Currently the interfaces that support this feature are `iEventHandler', `iEventPlug', and `iAwsSink', but it is easy to add more.

 
package MyPerlEventHandler;
@ISA = qw{ cspace::iEventHandler };
sub new
{
  my $x = {};
  bless($x, "MyPerlEventHandler");
  return $x;
}
sub HandleEvent
{
  my ($self, $event) = @_;
  # your event handler here...
}

package main;
my $eventq = cspace::CS_QUERY_REGISTRY($object_reg, "iEventQueue");
my $handler = new MyPerlEventHandler;
$eventq->RegisterListener($handler);

Special Cases

Take note of the following special cases.

Macros Accepting Interfaces as Parameters

In Perl, Crystal Space macros that take interface names as parameters--for instance CS_QUERY_REGISTRY()--take interface names as strings:

 
my $engine = cspace::CS_QUERY_REGISTRY($object_reg, "iEngine");

This differs from the C++ CS_QUERY_REGISTRY() macro in which `iEngine' would not be quoted.

csRGBpixel

To convert a `csRGBpixel' to a `csRGBcolor', use the csRGBpixel::asRGBcolor() method:

 
my $color = $pixel->asRGBcolor();

iSprite2DState

`iSprite2DState' has an extra method in Perl, GetVertexByIndex(), which accepts a single integer parameter (an array index) and returns a `csSprite2DVertex' from the sprite's array of vertices.

iEvent

The overloaded iEvent::Add() and Retrieve() methods are replaced in Perl with ones given names which explicitly specify the types of their parameters (since otherwise Perl would not know which C++ function to call):

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated using texi2html 1.76.