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