updated docs and path to my repo

[sdlgit/SDL-Site.git] / pages / SDL-Surface.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="#CONSTANTS">CONSTANTS</a></li>
<li><a href="#METHODS">METHODS</a>
<ul><li><a href="#new_flags_width_height_depth_Rmask_G">new ( flags, width, height, depth, Rmask, Gmask, Bmask, Amask )</a></li>
<li><a href="#new_from_surface_width_height_depth_">new_from ( surface, width, height, depth, Rmask, Gmask, Bmask, Amask )</a>
<ul><li><a href="#Construtor_Parameters">Construtor Parameters</a>
<ul><li><a href="#flags">flags</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#w">w</a></li>
<li><a href="#h">h</a></li>
<li><a href="#format">format</a></li>
<li><a href="#pitch">pitch</a></li>
<li><a href="#clip_rect">clip_rect</a></li>
</ul>
</li>
<li><a href="#Direct_Write_to_Surface_Pixel">Direct Write to Surface Pixel</a>
<ul><li><a href="#get_pixel">get_pixel</a></li>
<li><a href="#set_pixels">set_pixels</a>
<ul><li><a href="#Usage">Usage</a></li>
</ul>
</li>
<li><a href="#get_pixels_ptr">get_pixels_ptr</a></li>
</ul>
</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>SDL::Surface - Graphic surface structure.</p>

</div>
<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="CATEGORY_CONTENT">
<p>Core, Video, Structure</p>

</div>
<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SYNOPSIS_CONTENT">
<p>The main surface (display) is provided by <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>.
  use SDL; #provides flags &amp; constants
  use SDL::Video; #provides access to set_video_mode
  use SDL::Surface; #provides access to SDL_Surface struct internals</p>
<pre>  SDL::init(SDL_INIT_VIDEO); 
  my $display = SDL::Video::set_video_mode(); 

</pre>
<p>All surfaces constructed from now on are attached to the $display. There are two constructors available to do this.</p>
<pre>  my $surface  = SDL::Surface-&gt;new ( ... ); 
  my $surface2 = SDL::Surface-&gt;new_from ( surface, ... ); 

</pre>

</div>
<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="DESCRIPTION_CONTENT">
<p>An <code>SDL_Surface</code> defines a surfaceangular area of pixels.</p>

</div>
<h1 id="CONSTANTS">CONSTANTS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="CONSTANTS_CONTENT">
<p>The constants are exported by default. You can avoid this by doing:</p>
<pre> use SDL::Video ();

</pre>
<p>and access them directly:</p>
<pre> SDL::Video::SDL_SWSURFACE;

</pre>
<p>Available constants: see <a href="#flags">flags</a></p>

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

</div>
<h2 id="new_flags_width_height_depth_Rmask_G">new ( flags, width, height, depth, Rmask, Gmask, Bmask, Amask )</h2>
<div id="new_flags_width_height_depth_Rmask_G-2">
<p>The constructor creates a new surface with the specified parameter values.</p>
<pre>    my $surface = SDL::Surface-&gt;new( ... );

</pre>

</div>
<h2 id="new_from_surface_width_height_depth_">new_from ( surface, width, height, depth, Rmask, Gmask, Bmask, Amask )</h2>
<div id="new_from_surface_width_height_depth_-2">
<p>The constructor creates a new surface with the specified parameter values. </p>
<pre>    my $surface = SDL::Surface-&gt;new_from( $old_surface, ... );




</pre>

</div>
<h3 id="Construtor_Parameters">Construtor Parameters</h3>
<div id="Construtor_Parameters_CONTENT">

</div>
<h4 id="flags">flags</h4>
<div id="flags_CONTENT">
<p>Available flags for new() are exported by SDL::Video</p>
<dl>
	<dt>SDL_ASYNCBLIT</dt>
	<dd>
		<p>Use asynchronous blit if possible</p>
	</dd>
	<dt>SDL_SWSURFACE</dt>
	<dd>
		<p>Stored in the system memory.</p>
	</dd>
	<dt>SDL_HWSURFACE</dt>
	<dd>
		<p>Stored in video memory</p>
	</dd>
</dl>

</div>
<h2 id="w">w</h2>
<div id="w_CONTENT">
<p>SDL::Surface width are defined at construction. Thus the following is read only. </p>
<pre>  my $w = $surface-&gt;w; 

</pre>

</div>
<h2 id="h">h</h2>
<div id="h_CONTENT">
<p>SDL::Surface height are defined at construction. Thus the following is read only. </p>
<pre>  my $h = $surface-&gt;h; 

</pre>

</div>
<h2 id="format">format</h2>
<div id="format_CONTENT">
<p>The format of the pixels stored in the surface. See <a href="SDL-PixelFormat.html">SDL::PixelFormat</a></p>
<pre> my $format = $surface-&gt;format;

</pre>

</div>
<h2 id="pitch">pitch</h2>
<div id="pitch_CONTENT">
<pre> my $pitch = $surface-&gt;pitch;

</pre>
<p>SDL::Surface's scanline length in bytes</p>

</div>
<h2 id="clip_rect">clip_rect</h2>
<div id="clip_rect_CONTENT">
<p>To get the surface's clip_rect we the following</p>
<pre> my $clip_rect = SDL::Rect-&gt;new(0,0,0,0);
 SDL::Video::get_clip_rect($surface, $clip_rect);

</pre>
<p>To set the surface's clip_rect use the following</p>
<pre> my $clip_rect = SDL::Rect-&gt;new(2,23,23,542);
 SDL::Video::set_clip_rect($surface, $clip_rect);

</pre>

</div>
<h1 id="Direct_Write_to_Surface_Pixel">Direct Write to Surface Pixel</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="Direct_Write_to_Surface_Pixel_CONTEN">
<p>Disclaimer: This can be very slow, it is suitable for creating surfaces one time and not for animations</p>

</div>
<h2 id="get_pixel">get_pixel</h2>
<div id="get_pixel_CONTENT">
<pre> my $pixel = $surface-&gt;get_pixel( $offset )  

</pre>
<p>Returns the pixel value for the given <code>$offset</code>. The pixel value depends on current pixel format.</p>
<p><strong>Note</strong>: For surfaces with a palette (1 byte per pixel) the palette index is returned instead of color values.</p>

</div>
<h2 id="set_pixels">set_pixels</h2>
<div id="set_pixels_CONTENT">
<pre> $surface-&gt;set_pixels( $offset, $value );

</pre>
<p>Sets the current pixel <code>$value</code> to the given <code>$offset</code>. The pixel value must fit the pixel format of the surface.</p>
<p><strong>Note</strong>: For surfaces with a palette (1 byte per pixel) the palette index must be passed instead of color values.</p>

</div>
<h3 id="Usage">Usage</h3>
<div id="Usage_CONTENT">
<pre> sub putpixel
 {
     my($x, $y, $color) = @_;
     $screen-&gt;set_pixels( $x + $y * $screen-&gt;w, $color);
 }

</pre>
<p>See also examples/sols/ch02.pl</p>

</div>
<h2 id="get_pixels_ptr">get_pixels_ptr</h2>
<div id="get_pixels_ptr_CONTENT">
<pre> $surface-&gt;get_pixels_ptr();

</pre>
<p>Returns the C ptr to this surfaces's pixels</p>








</div>
<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SEE_ALSO_CONTENT">
<p><a href="SDL.html">SDL</a>, <a href="SDL-PixelFormat.html">SDL::PixelFormat</a>, <a href="SDL-Video.html">SDL::Video</a>, <a href="SDL-Rect.html">SDL::Rect</a></p>

</div>
</div>