/lib/pods/SDLx/LayerManager.pod
http://github.com/PerlGameDev/SDL · Unknown · 166 lines · 92 code · 74 blank · 0 comment · 0 complexity · ec0b8736535b4e5057c84be4f4e4d01f MD5 · raw file
- =head1 NAME
- SDLx::LayerManager - Extension for managing layers in a 2D world
- =head1 CATEGORY
- Extension
- =head1 SYNOPSIS
- use SDLx::Layer;
- use SDLx::LayerManager;
-
- use SDL::Image;
- use SDL::Surface;
- use SDL::Video;
-
- # creating layers
- my $layer1 = SDLx::Layer->new( SDL::Image::load('image1.png'), {userdata => '7'} );
- my $layer2 = SDLx::Layer->new( SDL::Image::load('image2.png'), 100, 200, {userdata => '42'} );
-
- # creating the manager that holds the layers
- my $layermanager = SDLx::LayerManager->new();
- $layermanager->add( $layer1 );
- $layermanager->add( $layer2 );
-
- my $display = # create your video surface here
-
- $layermanager->blit( $display );
-
- # accessing the layer at point(x,y)
- print( $layermanager->by_position( 150, 200 )->data->{userdata} ); # should print '42'
- =head1 DESCRIPTION
- SDLx::LayerManager is a package to handle a bunch of layers. A layer (see SDLx::Layer) is an SDL::Surface, the position of the surface on screen and some additional information.
- The layermanager gives you the opportunity to obtain the layer at a given point on screen and get the layers that are ahead or behind a layer.
- You will even be able to attach one or more layers to the mouse, e.g. for simulation some drag&drop functionality.
- =head1 METHODS
- =head2 new
- my $layermanager = SDLx::LayerManager->new();
- This creates your layermanager object. It doesn't take any parameters.
- =head2 add
- $layermanager->add( $layer );
- $layermanager->add( SDLx::Layer->new( $surface, $x, $y, $options ) );
- Call C<add> to push an SDLx::Layer object to the layermanager.
- =head2 layers
- my @layers = @{ $layermanager->layers };
- my $first_layer = $layermanager->layers->[0];
- The method C<layers> returns all layers that were added before.
- =head2 layer
- my $layer = $layermanager->layer( $index );
- To obtain only one layer at index C<$index> use this function. C<$index> ranges from C<0> to C<length - 1>.
- =head2 length
- my $length = $layermanager->length();
- This method returns the count of the added layers.
- =head2 blit
- $layermanager->blit( $surface );
- This method blits all layers to the surface (e.g. your video surface).
- =head2 by_position
- my $layer = $layermanager->by_position( $x, $y );
- C<by_position> returns the C<SDLx::Layer> object at point C<$x $y>, which is not fully transparent at this pixel.
- =head2 ahead
- my @layers = @{ $layermanager->ahead( $index ) };
- This method returns all layers that are ahead of the given layer indicated by C<$index>.
- Ahead means that a layer has a higher z-index and is blitted over the given layer.
- B<Note>: This method doesn't check for transparency. This will change in future versions.
- =head2 behind
- my @layers = @{ $layermanager->behind( $index ) };
- This method returns all layers that are behind of the given layer indicated by C<$index>.
- Behind means that a layer has a lower z-index and is blitted before the given layer.
- B<Note>: This method doesn't check for transparency. This will change in future versions.
- =head2 attach
- $layermanager->attach( $layer, $x, $y );
- $layermanager->attach( @layers, $x, $y );
- This function makes the given layer(s) sticky to the mouse. If you move the mouse the layer(s) will follow.
- The layermanager blits these layers at last, so they will appear on top of all layers.
- C<$x> and C<$y> should be set to the coords of the mouse, e.g. the coords of the mouse click.
- If you omit C<$x> and C<$y> the layermanager obtains them via SDL::Events::get_mouse_state.
- B<Note>: The z-index is not changed for the given layers.
- =head2 detach_xy
- $layermanager->detach_xy( $x, $y );
- C<detach_xy> detaches the previously attached layers to the given coords. The upper left corner of the backmost layer will be at C<$x> and C<$y>.
- The other layers are positioned relative to the backmost layer just like before.
- =head2 detach_back
- $layermanager->detach_back( );
- C<detach_back> detaches the previously attached layers back to the position where they were attached.
- =head2 foreground
- $layermanager->foreground( $layer );
- $layermanager->foreground( @layers );
- This method moves the given layer(s) to the foreground so that they are blitted on top of the other layers.
- =head1 BUGS
- Report at sdlperl.ath.cx
- =head1 SUPPORT
- #sdl irc.perl.org
- =head1 AUTHORS
- See L<SDL/AUTHORS>.
- =head1 COPYRIGHT
- This program is free software; you can redistribute
- it and/or modify it under the same terms as Perl itself.
- The full text of the license can be found in the
- LICENSE file included with this module.
- =head1 SEE ALSO
- perl(1), SDL(2).
- =cut