/lib/pods/SDLx/Layer.pod

  1
  2=head1 NAME
  3
  4SDLx::Layer - Storage object for surface and position information
  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  $layer1->foreground;
 31  printf( "%s\n", $layer1->behind->[0]->data->{userdata} ); # prints 42
 32
 33=head1 DESCRIPTION
 34
 35A layer (see SDLx::Layer) is an SDL::Surface, the position of the surface on screen and some additional information, e.g. ingame states.
 36
 37=head1 METHODS
 38
 39=head2 new
 40
 41  my $layer = SDLx::Layer->new( $surface );
 42  my $layer = SDLx::Layer->new( $surface,                                   %data );
 43  my $layer = SDLx::Layer->new( $surface, $pos_x,                           %data );
 44  my $layer = SDLx::Layer->new( $surface, $pos_x, $pos_y,                   %data );
 45  my $layer = SDLx::Layer->new( $surface, $pos_x, $pos_y, $clip_w,          %data );
 46  my $layer = SDLx::Layer->new( $surface, $pos_x, $pos_y, $clip_w, $clip_h, %data );
 47
 48This constructs the layer object. See how you can omit the position and dimension of the layer. The hash C<%data> is for your use only.
 49The layer object just pass it through.
 50
 51=head2 index
 52
 53  my $index = $layer->index;
 54
 55The method C<index> represents the z-index of this layer within its layermanager.
 56
 57=head2 x
 58
 59  my $x = $layer->x;
 60
 61This is a shortcut for $layer->pos->x.
 62
 63=head2 y
 64
 65  my $y = $layer->y;
 66
 67This is a shortcut for $layer->pos->y.
 68
 69=head2 w
 70
 71  my $w = $layer->w;
 72
 73This is a shortcut for $layer->clip->w.
 74
 75=head2 h
 76
 77  my $h = $layer->h;
 78
 79This is a shortcut for $layer->pos->h.
 80
 81=head2 surface
 82
 83  my $surface = $layer->surface;
 84  my $surface = $layer->surface( $new_surface );
 85
 86B<Example>:
 87
 88  SDL::Video::blit_surface( $layer->surface, $layer->clip, $destination_surface, $layer->pos );
 89
 90This method let you retrieve the current or set a new surface.
 91
 92=head2 pos
 93
 94  my $rect = $layer->pos;
 95
 96The method C<pos> returns an SDL::Rect object. The pos x and y are stored there.
 97
 98B<Example>:
 99
100  SDL::Video::blit_surface( $layer->surface, $layer->clip, $destination_surface, $layer->pos );
101
102=head2 clip
103
104  my $rect = $layer->clip;
105
106The method C<clip> returns an SDL::Rect object. The clip width and height are stored there.
107
108B<Example>:
109
110  SDL::Video::blit_surface( $layer->surface, $layer->clip, $destination_surface, $layer->pos );
111
112=head2 data
113
114  my %data = %{ $layer->data };
115  my %data = %{ $layer->data( %new_data) };
116
117This method returns the hash C<%data>. You can set C<%data> by passing a hash.
118
119=head2 ahead
120
121  my @layers = $layer->ahead;
122
123This method returns all layers that are ahead of the given layer.
124Ahead means that a layer has a higher z-index and is blitted over the given layer.
125
126B<Note>: This method doesn't check for transparency. This will change in future versions.
127
128=head2 behind
129
130  my @layers = $layer->behind;
131
132This method returns all layers that are behind of the given layer.
133Behind means that a layer has a lower z-index and is blitted over the given layer.
134
135B<Note>: This method doesn't check for transparency. This will change in future versions.
136
137=head2 attach
138
139  $layer->attach( $x, $y );
140
141This function makes the given layer sticky to the mouse. If you move the mouse the layer will follow.
142The layermanager blits this layer at last, so they will appear on top of all layers.
143
144C<$x> and C<$y> should be set to the coords of the mouse, e.g. the coords of the mouse click.
145If you omit C<$x> and C<$y> the layer obtains them via SDL::Events::get_mouse_state.
146
147B<Note>: The z-index is not changed for the given layer.
148
149=head2 detach_xy
150
151  $layer->detach_xy( $x, $y );
152
153C<detach_xy> detaches the previously attached layer to the given coords. The upper left corner of this layer will be at C<$x> and C<$y>.
154
155=head2 foreground
156
157  $layer->foreground;
158
159This method moves the given layer to the foreground so that it is blitted on top of the other layers.
160
161=head1 BUGS
162
163Report at sdlperl.ath.cx
164
165=head1 SUPPORT
166
167#sdl irc.perl.org
168
169=head1 AUTHORS
170
171See L<SDL/AUTHORS>.
172
173=head1 COPYRIGHT
174
175This program is free software; you can redistribute
176it and/or modify it under the same terms as Perl itself.
177
178The full text of the license can be found in the
179LICENSE file included with this module.
180
181
182=head1 SEE ALSO
183
184perl(1), SDL(2).
185
186=cut
187