[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="#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_pixels">get_pixels</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="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">
<dl>
	<dt>SDL_ANYFORMAT</dt>
	<dd>
		<p>Allow any pixel-format *</p>
	</dd>
	<dt>SDL_ASYNCBLIT</dt>
	<dd>
		<p>Use asynchronous blit if possible</p>
	</dd>
	<dt>SDL_DOUBLEBUF</dt>
	<dd>
		<p>Double buffered *</p>
	</dd>
	<dt>SDL_HWACCEL</dt>
	<dd>
		<p>Use hardware acceleration blit</p>
	</dd>
	<dt>SDL_HWPALETTE</dt>
	<dd>
		<p>Have an exclusive palette</p>
	</dd>
	<dt>SDL_HWSURFACE</dt>
	<dd>
		<p>Stored in video memory</p>
	</dd>
	<dt>SDL_FULLSCREEN</dt>
	<dd>
		<p>Full screen surface *</p>
	</dd>
	<dt>SDL_OPENGL</dt>
	<dd>
		<p>Have an OpenGL context *</p>
	</dd>
	<dt>SDL_OPENGLBLIT</dt>
	<dd>
		<p>Support OpenGL blitting *. NOTE: This option is kept for compatibility only, and is not recommended for new code.</p>
	</dd>
	<dt>SDL_RESIZABLE</dt>
	<dd>
		<p>Resizable surface *</p>
	</dd>
	<dt>SDL_RLEACCEL</dt>
	<dd>
		<p>Accelerated colorkey blitting with RLE</p>
	</dd>
	<dt>SDL_SRCALPHA</dt>
	<dd>
		<p>Use alpha blending blit</p>
	</dd>
	<dt>SDL_SRCCOLORKEY</dt>
	<dd>
		<p>Use colorkey blitting</p>
	</dd>
	<dt>SDL_SWSURFACE</dt>
	<dd>
		<p>Stored in the system memory. SDL_SWSURFACE is not actually a flag (it is defined as 0). A lack of SDL_HWSURFACE implies SDL_SWSURFACE</p>
	</dd>
	<dt>SDL_PREALLOC</dt>
	<dd>
		<p>Use preallocated 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_pixels">get_pixels</h2>
<div id="get_pixels_CONTENT">
<pre> $surface-&gt;get_pixels( $offset )  

</pre>
<p>Returns the current integer value at (surface-&gt;pixels)[offset] </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 integer to $value at (surface-&gt;pixels)[offset]</p>

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

</pre>
<p>Note: $depth_in_bytes for 32 is 4, 16 is 2, 8 is 1;</p>
<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>
Commit	Line	Data
162a0989	1	<div class="pod">
	2	<!-- INDEX START -->
	3	<h3 id="TOP">Index</h3>
	4
c5cfaf97	5	<ul><li><a href="#NAME">NAME</a></li>
c5cfaf97	6	<li><a href="#CATEGORY">CATEGORY</a></li>
162a0989	7	<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
	8	<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
	9	<li><a href="#METHODS">METHODS</a>
	10	<ul><li><a href="#new_flags_width_height_depth_Rmask_G">new ( flags, width, height, depth, Rmask, Gmask, Bmask, Amask )</a></li>
	11	<li><a href="#new_from_surface_width_height_depth_">new_from ( surface, width, height, depth, Rmask, Gmask, Bmask, Amask )</a>
0d76f1af	12	<ul><li><a href="#Construtor_Parameters">Construtor Parameters</a>
	13	<ul><li><a href="#flags">flags</a></li>
	14	</ul>
	15	</li>
162a0989	16	</ul>
	17	</li>
	18	<li><a href="#w">w</a></li>
	19	<li><a href="#h">h</a></li>
0d76f1af	20	<li><a href="#format">format</a></li>
	21	<li><a href="#pitch">pitch</a></li>
	22	<li><a href="#clip_rect">clip_rect</a></li>
	23	</ul>
	24	</li>
	25	<li><a href="#Direct_Write_to_Surface_Pixel">Direct Write to Surface Pixel</a>
	26	<ul><li><a href="#get_pixels">get_pixels</a></li>
	27	<li><a href="#set_pixels">set_pixels</a>
	28	<ul><li><a href="#Usage">Usage</a></li>
	29	</ul>
	30	</li>
	31	<li><a href="#get_pixels_ptr">get_pixels_ptr</a></li>
162a0989	32	</ul>
	33	</li>
	34	<li><a href="#SEE_ALSO">SEE ALSO</a>
	35	</li>
	36	</ul><hr />
	37	<!-- INDEX END -->
	38
	39	<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
	40	<div id="NAME_CONTENT">
c5cfaf97	41	<p>SDL::Surface - Graphic surface structure.</p>
162a0989	42
162a0989	43	</div>
c5cfaf97	44	<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
bfdd9c2e	45	<div id="CATEGORY_CONTENT">
	46	<p>Core, Video, Structure</p>
	47
bfdd9c2e	48	</div>
162a0989	49	<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
162a0989	50	<div id="SYNOPSIS_CONTENT">
92e293d6	51	<p>The main surface (display) is provided by <a href="/SDL-Video.html#set_video_mode">SDL::Video::set_video_mode</a>.
162a0989	52	use SDL; #provides flags & constants
	53	use SDL::Video; #provides access to set_video_mode
	54	use SDL::Surface; #provides access to SDL_Surface struct internals</p>
	55	<pre> SDL::init(SDL_INIT_VIDEO);
	56	my $display = SDL::Video::set_video_mode();
	57
	58	</pre>
	59	<p>All surfaces constructed from now on are attached to the $display. There are two constructors available to do this.</p>
	60	<pre> my $surface = SDL::Surface->new ( ... );
	61	my $surface2 = SDL::Surface->new_from ( surface, ... );
	62
	63	</pre>
	64
	65	</div>
	66	<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
	67	<div id="DESCRIPTION_CONTENT">
	68	<p>An <code>SDL_Surface</code> defines a surfaceangular area of pixels.</p>
	69
	70	</div>
	71	<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
	72	<div id="METHODS_CONTENT">
	73
	74	</div>
	75	<h2 id="new_flags_width_height_depth_Rmask_G">new ( flags, width, height, depth, Rmask, Gmask, Bmask, Amask )</h2>
	76	<div id="new_flags_width_height_depth_Rmask_G-2">
	77	<p>The constructor creates a new surface with the specified parameter values.</p>
	78	<pre> my $surface = SDL::Surface->new( ... );
	79
	80	</pre>
	81
	82	</div>
	83	<h2 id="new_from_surface_width_height_depth_">new_from ( surface, width, height, depth, Rmask, Gmask, Bmask, Amask )</h2>
	84	<div id="new_from_surface_width_height_depth_-2">
	85	<p>The constructor creates a new surface with the specified parameter values. </p>
	86	<pre> my $surface = SDL::Surface->new_from( $old_surface, ... );
	87
ecabf8b7	88
	89
	90
162a0989	91	</pre>
162a0989	92
	93	</div>
	94	<h3 id="Construtor_Parameters">Construtor Parameters</h3>
	95	<div id="Construtor_Parameters_CONTENT">
	96
0d76f1af	97	</div>
	98	<h4 id="flags">flags</h4>
	99	<div id="flags_CONTENT">
	100	<dl>
	101	<dt>SDL_ANYFORMAT</dt>
	102	<dd>
	103	<p>Allow any pixel-format *</p>
	104	</dd>
	105	<dt>SDL_ASYNCBLIT</dt>
	106	<dd>
	107	<p>Use asynchronous blit if possible</p>
	108	</dd>
	109	<dt>SDL_DOUBLEBUF</dt>
	110	<dd>
	111	<p>Double buffered *</p>
	112	</dd>
	113	<dt>SDL_HWACCEL</dt>
	114	<dd>
	115	<p>Use hardware acceleration blit</p>
	116	</dd>
	117	<dt>SDL_HWPALETTE</dt>
	118	<dd>
	119	<p>Have an exclusive palette</p>
	120	</dd>
	121	<dt>SDL_HWSURFACE</dt>
	122	<dd>
	123	<p>Stored in video memory</p>
	124	</dd>
	125	<dt>SDL_FULLSCREEN</dt>
	126	<dd>
	127	<p>Full screen surface *</p>
	128	</dd>
	129	<dt>SDL_OPENGL</dt>
	130	<dd>
	131	<p>Have an OpenGL context *</p>
	132	</dd>
	133	<dt>SDL_OPENGLBLIT</dt>
	134	<dd>
	135	<p>Support OpenGL blitting *. NOTE: This option is kept for compatibility only, and is not recommended for new code.</p>
	136	</dd>
	137	<dt>SDL_RESIZABLE</dt>
	138	<dd>
	139	<p>Resizable surface *</p>
	140	</dd>
	141	<dt>SDL_RLEACCEL</dt>
	142	<dd>
	143	<p>Accelerated colorkey blitting with RLE</p>
	144	</dd>
	145	<dt>SDL_SRCALPHA</dt>
	146	<dd>
	147	<p>Use alpha blending blit</p>
	148	</dd>
	149	<dt>SDL_SRCCOLORKEY</dt>
	150	<dd>
	151	<p>Use colorkey blitting</p>
	152	</dd>
	153	<dt>SDL_SWSURFACE</dt>
	154	<dd>
	155	<p>Stored in the system memory. SDL_SWSURFACE is not actually a flag (it is defined as 0). A lack of SDL_HWSURFACE implies SDL_SWSURFACE</p>
	156	</dd>
	157	<dt>SDL_PREALLOC</dt>
	158	<dd>
	159	<p>Use preallocated memory</p>
	160	</dd>
161	</dl>
162a0989	162
	163
	164
	165
	166
	167	</div>
	168	<h2 id="w">w</h2>
	169	<div id="w_CONTENT">
	170	<p>SDL::Surface width are defined at construction. Thus the following is read only. </p>
	171	<pre> my $w = $surface->w;
	172
	173	</pre>
	174
	175	</div>
	176	<h2 id="h">h</h2>
	177	<div id="h_CONTENT">
	178	<p>SDL::Surface height are defined at construction. Thus the following is read only. </p>
	179	<pre> my $h = $surface->h;
	180
	181	</pre>
	182
	183	</div>
0d76f1af	184	<h2 id="format">format</h2>
0d76f1af	185	<div id="format_CONTENT">
55bbf7a2	186	<p>The format of the pixels stored in the surface. See <a href="SDL-PixelFormat.html">SDL::PixelFormat</a></p>
0d76f1af	187	<pre> my $format = $surface->format;
	188
	189	</pre>
	190
	191	</div>
	192	<h2 id="pitch">pitch</h2>
	193	<div id="pitch_CONTENT">
	194	<pre> my $pitch = $surface->pitch;
	195
	196	</pre>
	197	<p>SDL::Surface's scanline length in bytes</p>
	198
	199	</div>
	200	<h2 id="clip_rect">clip_rect</h2>
	201	<div id="clip_rect_CONTENT">
	202	<p>To get the surface's clip_rect we the following</p>
	203	<pre> my $clip_rect = SDL::Rect->new(0,0,0,0);
	204	SDL::Video::get_clip_rect($surface, $clip_rect);
	205
	206	</pre>
	207	<p>To set the surface's clip_rect use the following</p>
	208	<pre> my $clip_rect = SDL::Rect->new(2,23,23,542);
	209	SDL::Video::set_clip_rect($surface, $clip_rect);
	210
	211	</pre>
	212
	213	</div>
	214	<h1 id="Direct_Write_to_Surface_Pixel">Direct Write to Surface Pixel</h1><p><a href="#TOP" class="toplink">Top</a></p>
	215	<div id="Direct_Write_to_Surface_Pixel_CONTEN">
	216	<p>Disclaimer: This can be very slow, it is suitable for creating surfaces one time and not for animations</p>
	217
	218	</div>
	219	<h2 id="get_pixels">get_pixels</h2>
	220	<div id="get_pixels_CONTENT">
	221	<pre> $surface->get_pixels( $offset )
	222
	223	</pre>
	224	<p>Returns the current integer value at (surface->pixels)[offset] </p>
	225
	226	</div>
	227	<h2 id="set_pixels">set_pixels</h2>
	228	<div id="set_pixels_CONTENT">
	229	<pre> $surface->set_pixels( $offset, $value );
	230
	231	</pre>
	232	<p>Sets the current integer to $value at (surface->pixels)[offset]</p>
	233
	234	</div>
	235	<h3 id="Usage">Usage</h3>
	236	<div id="Usage_CONTENT">
	237	<pre> sub putpixel
	238	{
	239	my($x, $y, $color) = @_;
	240	my $lineoffset = $y * ($screen->pitch / $depth_in_bytes);
	241	$screen->set_pixels( $lineoffset+ $x, $color);
	242	}
	243
	244	</pre>
	245	<p>Note: $depth_in_bytes for 32 is 4, 16 is 2, 8 is 1;</p>
	246	<p>See also examples/sols/ch02.pl</p>
	247
	248	</div>
	249	<h2 id="get_pixels_ptr">get_pixels_ptr</h2>
	250	<div id="get_pixels_ptr_CONTENT">
251	<pre> $surface->get_pixels_ptr();
252
253	</pre>
254	<p>Returns the C ptr to this surfaces's pixels</p>
255
256
257
258
259
260
261
262
263	</div>
162a0989	264	<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
162a0989	265	<div id="SEE_ALSO_CONTENT">
55bbf7a2	266	<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>
162a0989	267
	268	</div>
	269	</div>