/lib/pods/SDLx/LayerManager.pod

  1
  2=head1 NAME
  3
  4SDLx::LayerManager - Extension for managing layers in a 2D world
  5
  6=head1 CATEGORY 
  7
  8Extension
  9
 10=head1 SYNOPSIS
 11
 12  use SDLx::Layer;
 13  use SDLx::LayerManager;
 14  
 15  use SDL::Image;
 16  use SDL::Surface;
 17  use SDL::Video;
 18  
 19  # creating layers
 20  my $layer1 = SDLx::Layer->new( SDL::Image::load('image1.png'), {userdata => '7'} );
 21  my $layer2 = SDLx::Layer->new( SDL::Image::load('image2.png'), 100, 200, {userdata => '42'} );
 22  
 23  # creating the manager that holds the layers
 24  my $layermanager = SDLx::LayerManager->new();
 25  $layermanager->add( $layer1 );
 26  $layermanager->add( $layer2 );
 27  
 28  my $display = # create your video surface here
 29  
 30  $layermanager->blit( $display );
 31  
 32  # accessing the layer at point(x,y)
 33  print( $layermanager->by_position( 150, 200 )->data->{userdata} ); # should print '42'
 34
 35=head1 DESCRIPTION
 36
 37SDLx::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.
 38
 39The 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.
 40
 41You will even be able to attach one or more layers to the mouse, e.g. for simulation some drag&drop functionality.
 42
 43=head1 METHODS
 44
 45=head2 new
 46
 47  my $layermanager = SDLx::LayerManager->new();
 48
 49This creates your layermanager object. It doesn't take any parameters.
 50
 51=head2 add
 52
 53  $layermanager->add( $layer );
 54  $layermanager->add( SDLx::Layer->new( $surface, $x, $y, $options ) );
 55
 56Call C<add> to push an SDLx::Layer object to the layermanager.
 57
 58=head2 layers
 59
 60  my @layers = @{ $layermanager->layers };
 61  my $first_layer = $layermanager->layers->[0];
 62
 63The method C<layers> returns all layers that were added before.
 64
 65=head2 layer
 66
 67  my $layer = $layermanager->layer( $index );
 68
 69To obtain only one layer at index C<$index> use this function. C<$index> ranges from C<0> to C<length - 1>.
 70
 71=head2 length
 72
 73  my $length = $layermanager->length();
 74
 75This method returns the count of the added layers.
 76
 77=head2 blit
 78
 79  $layermanager->blit( $surface );
 80
 81This method blits all layers to the surface (e.g. your video surface).
 82
 83=head2 by_position
 84
 85  my $layer = $layermanager->by_position( $x, $y );
 86
 87C<by_position> returns the C<SDLx::Layer> object at point C<$x $y>, which is not fully transparent at this pixel.
 88
 89=head2 ahead
 90
 91  my @layers = @{ $layermanager->ahead( $index ) };
 92
 93This method returns all layers that are ahead of the given layer indicated by C<$index>.
 94Ahead means that a layer has a higher z-index and is blitted over the given layer.
 95
 96B<Note>: This method doesn't check for transparency. This will change in future versions.
 97
 98=head2 behind
 99
100  my @layers = @{ $layermanager->behind( $index ) };
101
102This method returns all layers that are behind of the given layer indicated by C<$index>.
103Behind means that a layer has a lower z-index and is blitted before the given layer.
104
105B<Note>: This method doesn't check for transparency. This will change in future versions.
106
107=head2 attach
108
109  $layermanager->attach( $layer,  $x, $y );
110  $layermanager->attach( @layers, $x, $y );
111
112This function makes the given layer(s) sticky to the mouse. If you move the mouse the layer(s) will follow.
113The layermanager blits these layers at last, so they will appear on top of all layers.
114
115C<$x> and C<$y> should be set to the coords of the mouse, e.g. the coords of the mouse click.
116If you omit C<$x> and C<$y> the layermanager obtains them via SDL::Events::get_mouse_state.
117
118B<Note>: The z-index is not changed for the given layers.
119
120=head2 detach_xy
121
122  $layermanager->detach_xy( $x, $y );
123
124C<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>.
125The other layers are positioned relative to the backmost layer just like before.
126
127=head2 detach_back
128
129  $layermanager->detach_back( );
130
131C<detach_back> detaches the previously attached layers back to the position where they were attached.
132
133=head2 foreground
134
135  $layermanager->foreground( $layer );
136  $layermanager->foreground( @layers );
137
138This method moves the given layer(s) to the foreground so that they are blitted on top of the other layers.
139
140=head1 BUGS
141
142Report at sdlperl.ath.cx
143
144=head1 SUPPORT
145
146#sdl irc.perl.org
147
148=head1 AUTHORS
149
150See L<SDL/AUTHORS>.
151
152=head1 COPYRIGHT
153
154This program is free software; you can redistribute
155it and/or modify it under the same terms as Perl itself.
156
157The full text of the license can be found in the
158LICENSE file included with this module.
159
160
161=head1 SEE ALSO
162
163perl(1), SDL(2).
164
165=cut
166