The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Games-3D-0.10
River stage zero No dependents
++
/ Games::3D::Link

NAME

Games::3D::Link - link two or more objects together by a signal-relay chain

SYNOPSIS

        use Games::3D::Thingy;
        use Games::3D::Link;

        # send signal straight through
        my $link = Games::3D::Link->new();

        my $src = Games::3D::Thingy->new();
        my $dst = Games::3D::Thingy->new();

        $src->link ($dst, $link);

EXPORTS

Exports nothing on default.

DESCRIPTION

Represents a link between two objects and allows relaying a signal between them.

A link has one (or more) inputs, and one (or more) outputs. Signals are send to the inputs via calling a subroutine (any of on(), off(), flip(), or signal()), and the signal will effect the state of the input. Each input will remember it's state and is per default in the off state.

Each link is by default an OR gate e.g. each incoming signal is relayed instantly to each output.

You can use $link->and_gate(1) to switch the link to the AND gate type.

In this state only when all the inputs are in the the same state, the specified signal (default is the state the inputs are in) is sent to all the outputs.

This means a link acts like an AND gate, only if all the inputs are in the same state, it triggers.

METHODS

timer_provider
        Games::3D::Link::timer_provider( $class );

You need to call this before any link with delay will work. Pass as argument a classname or an object reference. This works best when you pass an Games::Irrlicht object :)

        my $app = Games::Irrlicht->new();
        Games::3D::Link::timer_provider( $app );
new()
        my $link = Games::3D::Link->new( @options );

Creates a new link.

is_active()
        $link->is_active();

Returns true if the link is active, or false for inactive. Inactive links will not relay signals, but will still maintain their inputs.

activate()
        $link->activate();

Set the link to the active state. Newly created links are always active.

deactivate()
        $link->deactivate();

Set the link to inactive. Newly created ones are always active. Inactive links will not relay signals until they are activated again, but they will maintain their input states properly while inactive.

id()

Return the link's unique id.

name()
        print $link->name();
        $link->name('new name');

Set and/or return the link's name. The default name is the last part of the classname, uppercased, preceded by '#' and the link's unique id.

signal()
        $link->signal($input_id,$signal);
        $link->signal($self,$signal);

Put the signal into the link's input. The input can either be an ID, or just the object sending the signal. The object needs to be linked to the input of the link first, by using link(), or add_input().

add_input()
        $link->add_input($object);

Registers $object as a valid input source for this link. See also link().

Do not forget to also register the link $link as output for $object via $object-add_output($link);>. It is easier and safer to just use $link-link($src,$dst);>, though.

add_output()
        $link->add_output($object);

Registers $object as an output of this link, e.g. each signal the link relays will also be sent to this object. See also link().

Do not forget to also register the link $link as input for $object via $object-add_input($link);>. It is easier and safer to just use $link-link($src,$dst);>, though.

link()
        $link->link($src,$dest);

Is a combination of add_input() and add_output(), e.g links the source object via this link to the destination object. If the link was connecting other objects beforehand, these connections will also remain.

count()
        $link->count(2);

Sets the count of how many times the incoming signal is sent out. Default is 1. This acts basically as a multiplier, setting it to 2 will for instance send each incoming signal two times out, with a delay in between. The delay can be set with delay().

Returns the count.

delay()
        $link->delay(2000);             # 2 seconds
        $link->delay(1000,500);         # 1 second, and then 1/2 second
        $link->delay(1000,500,200);     # 1s, 1/2s, and both of them with
                                        # randomized by +/- 200 ms

Sets the delay between the receiving of the signal and it's relaying. The default for this is 0. Also sets the delay between each consecutive relay if count() is different than 1. The third parameter is an optional random offset applied to both delays.

Returns a list of (first_delay, resend_delay, random_offset).

once()
        if ($link->once()) { ... }              # return true if one-time link
        $link->once(1);                         # enable one-time sending
        $link->once(0);                         # disable

Sets the one-time flag of the link. If set to a true value, the link will only re-act to the first signal, and then deactivate itself.

If the link is set to send for each incoming signal more than one signal (via delay()), they still will all be sent. Also, each of the outputs of the link will receive the signal. The once flag is only for the incoming signals, not how many go out.

You can enable the link again (with activate(), and it will once more work on one incoming signal.

Default is off, e.g. the link will work on infinitely many incoming signals.

Returns the once flag.

fixed_output()
        if (defined $link->fixed_output()) { ... }
        $link->fixed_output(undef);                     # disable
        $link->fixed_output(SIG_ON);                    # always send ON

Get/set the fixed output signal. If set to undef (default), then the input signal will be relayed through (unless invert() was set, which would invert the input before sending it out), if set to a specific value, this set signal will always be sent, regardless of the input signal or the invert() flag.

and_gate()
        $link->and_gate(1) unless $link->and_gate();

Set/get the flag indicating this link is an AND gate.

invert()
        $link->invert(1) unless $link->invert();

Set/get the flag indicating this link is inverted.

unlink()
        $link->unlink();

Unlink all inputs and outputs from the link.

add_timer()
        $link->add_timer();

Add a timer to this link. See timer_provider.

AUTHORS

(c) 2003, 2004, 2006 Tels <http://bloodgate.com/>

SEE ALSO

Games::3D::Thingy, Games::Irrlicht