updated docs

[sdlgit/SDL-Site.git] / pages / SDLx-LayerManager.html-inc

<div class="pod">
<!-- INDEX START -->
<h3 id="TOP">Index</h3>

<ul><li><a href="#NAME">NAME</a></li>
<li><a href="#CATEGORY">CATEGORY </a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#METHODS">METHODS</a>
<ul><li><a href="#new">new</a></li>
<li><a href="#add">add</a></li>
<li><a href="#layers">layers</a></li>
<li><a href="#layer">layer</a></li>
<li><a href="#length">length</a></li>
<li><a href="#blit">blit</a></li>
<li><a href="#by_position">by_position</a></li>
<li><a href="#ahead">ahead</a></li>
<li><a href="#behind">behind</a></li>
<li><a href="#attach">attach</a></li>
<li><a href="#detach_xy">detach_xy</a></li>
<li><a href="#detach_back">detach_back</a></li>
<li><a href="#foreground">foreground</a></li>
</ul>
</li>
<li><a href="#BUGS">BUGS</a></li>
<li><a href="#SUPPORT">SUPPORT</a></li>
<li><a href="#AUTHORS">AUTHORS</a></li>
<li><a href="#COPYRIGHT">COPYRIGHT</a></li>
<li><a href="#SEE_ALSO">SEE ALSO</a>
</li>
</ul><hr />
<!-- INDEX END -->

<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="NAME_CONTENT">
<p>SDLx::LayerManager - Extension for managing layers in a 2D world</p>

</div>
<h1 id="CATEGORY">CATEGORY </h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="CATEGORY_CONTENT">
<p>Extension</p>

</div>
<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SYNOPSIS_CONTENT">
<pre>  use SDLx::Layer;
  use SDLx::LayerManager;

  use SDL::Image;
  use SDL::Surface;
  use SDL::Video;

  # creating layers
  my $layer1 = SDLx::Layer-&gt;new( SDL::Image::load('image1.png'), {userdata =&gt; '7'} );
  my $layer2 = SDLx::Layer-&gt;new( SDL::Image::load('image2.png'), 100, 200, {userdata =&gt; '42'} );

  # creating the manager that holds the layers
  my $layermanager = SDLx::LayerManager-&gt;new();
  $layermanager-&gt;add( $layer1 );
  $layermanager-&gt;add( $layer2 );

  my $display = # create your video surface here

  $layermanager-&gt;blit( $display );

  # accessing the layer at point(x,y)
  print( $layermanager-&gt;by_position( 150, 200 )-&gt;data-&gt;{userdata} ); # should print '42'

</pre>

</div>
<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="DESCRIPTION_CONTENT">
<p>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.</p>
<p>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.</p>
<p>You will even be able to attach one or more layers to the mouse, e.g. for simulation some drag&amp;drop functionality.</p>

</div>
<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="METHODS_CONTENT">

</div>
<h2 id="new">new</h2>
<div id="new_CONTENT">
<pre>  my $layermanager = SDLx::LayerManager-&gt;new();

</pre>
<p>This creates your layermanager object. It doesn't take any parameters.</p>

</div>
<h2 id="add">add</h2>
<div id="add_CONTENT">
<pre>  $layermanager-&gt;add( $layer );
  $layermanager-&gt;add( SDLx::Layer-&gt;new( $surface, $x, $y, $options ) );

</pre>
<p>Call <code>add</code> to push an SDLx::Layer object to the layermanager.</p>

</div>
<h2 id="layers">layers</h2>
<div id="layers_CONTENT">
<pre>  my @layers = @{ $layermanager-&gt;layers };
  my $first_layer = $layermanager-&gt;layers-&gt;[0];

</pre>
<p>The method <code>layers</code> returns all layers that were added before.</p>

</div>
<h2 id="layer">layer</h2>
<div id="layer_CONTENT">
<pre>  my $layer = $layermanager-&gt;layer( $index );

</pre>
<p>To obtain only one layer at index <code>$index</code> use this function. <code>$index</code> ranges from <code>0</code> to <code>lenght - 1</code>.</p>

</div>
<h2 id="length">length</h2>
<div id="length_CONTENT">
<pre>  my $length = $layermanager-&gt;length();

</pre>
<p>This method returns the count of the added layers.</p>

</div>
<h2 id="blit">blit</h2>
<div id="blit_CONTENT">
<pre>  $layermanager-&gt;blit( $surface );

</pre>
<p>This method blits all layers to the surface (e.g. your video surface).</p>

</div>
<h2 id="by_position">by_position</h2>
<div id="by_position_CONTENT">
<pre>  my $layer = $layermanager-&gt;by_position( $x, $y );

</pre>
<p><code>by_position</code> returns the <code>SDLx::Layer</code> object at point <code>$x $y</code>, which is not fully transparent at this pixel.</p>

</div>
<h2 id="ahead">ahead</h2>
<div id="ahead_CONTENT">
<pre>  my @layers = @{ $layermanager-&gt;ahead( $index ) };

</pre>
<p>This method returns all layers that are ahead of the given layer indicated by <code>$index</code>.
Ahead means that a layer has a higher z-index and is blitted over the given layer.</p>
<p><strong>Note</strong>: This method doesn't check for transparency. This will change in future versions.</p>

</div>
<h2 id="behind">behind</h2>
<div id="behind_CONTENT">
<pre>  my @layers = @{ $layermanager-&gt;behind( $index ) };

</pre>
<p>This method returns all layers that are behind of the given layer indicated by <code>$index</code>.
Behind means that a layer has a lower z-index and is blitted before the given layer.</p>
<p><strong>Note</strong>: This method doesn't check for transparency. This will change in future versions.</p>

</div>
<h2 id="attach">attach</h2>
<div id="attach_CONTENT">

</div>
<h2 id="detach_xy">detach_xy</h2>
<div id="detach_xy_CONTENT">

</div>
<h2 id="detach_back">detach_back</h2>
<div id="detach_back_CONTENT">

</div>
<h2 id="foreground">foreground</h2>
<div id="foreground_CONTENT">

</div>
<h1 id="BUGS">BUGS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="BUGS_CONTENT">
<p>Report at sdlperl.ath.cx</p>

</div>
<h1 id="SUPPORT">SUPPORT</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SUPPORT_CONTENT">
<p>#sdl irc.perl.org</p>

</div>
<h1 id="AUTHORS">AUTHORS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="AUTHORS_CONTENT">
<p>See <b>AUTHORS</b> in <cite>SDL</cite>.</p>

</div>
<h1 id="COPYRIGHT">COPYRIGHT</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="COPYRIGHT_CONTENT">
<p>This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.</p>
<p>The full text of the license can be found in the
LICENSE file included with this module.</p>





</div>
<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SEE_ALSO_CONTENT">
<p>perl(1), SDL(2).</p>

</div>
</div>