/lib/pods/SDLx/Surface.pod

  1
  2=pod
  3
  4=head1 NAME
  5
  6SDLx::Surface - Graphic surface matrix extension
  7
  8=head1 CATEGORY
  9
 10Extension
 11
 12=head1 SYNOPSIS
 13
 14 use SDL;
 15 use SDL::Video;
 16 use SDLx::Surface;
 17
 18 # Create the main surface (display)
 19 SDL::init(SDL_INIT_VIDEO);
 20 my $display = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
 21
 22 my $surf_matrix = SDLx::Surface->new( surface => $display);
 23 
 24 $surf_matrix->[10][10] = 0xFFFF; #for 16bpp write white at x = 10 and y=10
 25
 26 $surf_matrix->surface( $new_surface );
 27
 28 my $orig_surface = $surf_matrix->surface();
 29
 30=head1 DESCRIPTION
 31
 32An C<SDLx::Surface> allows matrix read and write to a surface, safely. 
 33
 34=head1 CONSTRUCTOR 
 35
 36=head2 new
 37
 38Takes a SDL::Surface in hash format.
 39
 40If a surface is passed to 'surface =>' that is loaded. Otherwise you can define at least a width and a height. 
 41
 42	SDLx::Surface->new(  surface => $surface) # The $surface is loaded
 43
 44	SDLx::Surface->new( width=> 400, height=>200) 
 45		# A SDL::Surface->new( SDL_ANYFORMAT, 400, 200, 32) is loaded
 46
 47	SDLx::Surface->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>24 ) 
 48	  	# A SDL::Surface->new( SDL_SWSURFACE, 400, 200, 24) is loaded 
 49
 50	SDLx::Surface->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>32, greenmask=>0xFF000000 )
 51		# A SDL::Surface->new( SDL_ANYFORMAT, 400, 200, 32, 0, 0xFF000000,0, 0, 0 ) is loaded
 52	SDLx::Surface->new( w => 1, h => 1, color => 0xFF0000FF )
 53		# A SDL::Surface->new( SDL_ANYFORMAT, 1, 1, 32, 0, 0, 0, 0 ) is loaded
 54		all pixels are colored with color (red)
 55
 56=head2 display
 57
 58If L<SDLx::App::new|SDLx::App/"new"> or L<SDL::Video::get_video_mode|SDL::Video/"get_video_mode"> called before then:
 59
 60 my $appx = SDLx::Surface::display(); 
 61
 62gets the display if it is already made. Passed options are ignored. Otherwise you can quickly make the display with :
 63
 64 SDLx::Surface::display( width => 20, height => 20) #depth => 32 and SDL_ANYFORMAT used
 65
 66or you can also pass flags and depth. 
 67
 68 SDLx::Surface::display( width => 20, height => 20, flags=> SDL_HWSURFACE, depth=>24) 
 69
 70You can also use the keys C<w> and C<h> in place of C<width> and C<height>, as with C<new>.
 71
 72Get or create the main display surface and attach to a C<SDLx::Surface>.
 73
 74=head2 duplicate
 75
 76Does a attributes only, no pixel, copy of another SDLx::Surface. 
 77
 78=head1 ATTRIBUTES
 79
 80=head2 surface
 81
 82If a SDL::Surface is passed it is attached to the matrix. Returns the SDL::Surface that is currently attached to this SDLx::Surface
 83
 84=head2 w, h, format, pitch, flags
 85
 86Returns the inner SDL::Surface's respective attribute. See C<SDL::Surface>.
 87
 88=head2 clip_rect
 89
 90Sets the passed C<SDL::Rect> as the new clip_rect for the surface. Returns the SDL::Surface's clip_rect. See 
 91L<SDL::Video::get_clip_rect|SDL::Video/"get_clip_rect"> and L<SDL::Video::set_clip_rect|SDL::Video/"set_clip_rect">.
 92=head1 EXTENSIONS
 93
 94=head2 load
 95
 96 my $surface = SDLx::Surface->load( 'hero.png' );
 97 my $surface = SDLx::Surface->load( 'hero.dat', 'bmp' );
 98
 99Loads the given image file into a I<new> SDLx::Surface surface. A new
100surface is B<always> created, even if you call it from an already crafted
101object. Croaks on errors such as no support built for that image extension
102or a file reading error (the error message is SDL::get_error and should
103give more details).
104
105Note that load() will automatically figure out the extension based on the
106filename you provide. If you wish to force an extension for whatever reason
107(like having a filename with a different extension or none at all), you can
108optionally pass the file type as a second parameter. Case is not relevant.
109
110If you don't have SDL_image in your build, only bitmap images will be
111supported.
112
113Returns the new Surface.
114
115
116=head2 blit 
117
118 $sdlx_surface->blit( $dest, $src_rect, $dest_rect );
119
120Blits C<SDLx::Surface> onto $dest surface. 
121$src_rect or $dest_rect are optional. If $src_rect is omitted, it will be the size of the entire surface. If $dest_rect is omitted, 
122it will be blitted at C<(0, 0)>. $src_rect or $dest_rect can be array refs or C<SDL::Rect>. $dest can be C<SDLx::Surface> or C<SDL::Surface>.
123
124Note that the final blit rectangle is stored in $dest_rect after clipping is performed.
125
126Returns $self
127
128=head2 blit_by
129
130 $sdlx_surface->blit_by( $src, $src_rect, $dest_rect );
131
132Does the same as C<blit> but the C<SDLx::Surface> is the one being blitted to.
133This is useful when the surface you have isn't an C<SDLx::Surface>, but the surface it is being blitted to is.
134
135Note that the final blit rectangle is stored in $dest_rect after clipping is performed.
136
137=head2 flip
138
139Applies L<SDL::Video::flip|SDL::Video/"flip"> to the Surface, with error checking.
140
141Returns $self
142
143=head2 update
144
145 $sdlx_surface->update(); # whole surface is updated
146 $sdlx_surface->update([0,0,1,1]); # only that area (0,0,1,1) is updated
147 
148 $sdlx_surface->update( [ SDL::Rect->new(0,0,1,2) ... ]); # defined rects are updated
149
150Applies L<SDL::Video::update_rect|SDL::Video/"update_rect"> for no rect or 1 array ref. Applies 
151L<SDL::Video::update_rects|SDL::Video/"update_rects"> for array of L<SDL::Rect>s. 
152
153Returns $self
154
155
156=head2 draw_rect
157
158 $sdlx_surface->draw_rect( [$x,$y,$w,$h], 0xFFFF00FF );
159 $sdlx_surface->draw_rect( SDL::Rect->new($x,$y,$w,$h), 0xFFFF00FF );
160
161Draws a rect on the surface with the given color. If the rect is omitted, the colored rect will be drawn to the entire surface.
162
163Returns $self
164
165=head2 draw_line
166
167 $sdlx_surface->draw_line( [$x1, $y1], [$x2, $y2], $color, $antialias); # $color is a number
168 $sdlx_surface->draw_line( [$x1, $y1], [$x2, $y2], \@color, $antialias); # 
169
170Draws a line on the surface. Antialias is turned on if $antialias is true. 
171
172Returns $self
173
174=head2 draw_circle
175
176 $sdlx_surface->draw_circle( [$x1, $y1], $radius, \@color, $antialias ); 
177
178Draws an unfilled circle at C<($x1,$y1)> of size $radius and $color.
179Antialias is turned on if $antialias is true. 
180Returns $self
181
182=head2 draw_circle_filled
183
184 $sdlx_surface->draw_circle_filled( [$x1, $y1], $radius, \@color );
185
186Draws an B<filled> circle at C<($x1,$y1)> of size $radius and $color.
187Antialias is turned on automatically. 
188Returns $self
189
190=head2 draw_trigon
191
192 $sdlx_surface->draw_trigon( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color, $antialias );
193
194Draws an unfilled trigon (triangle) with vertices C<($x1,$y1)>, C<($x2,$y2)>,
195C<($x3,$y3)> and $color.
196Antialias is turned on if $antialias is true.
197Returns $self
198
199=head2 draw_trigon_filled
200
201 $sdlx_surface->draw_trigon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \@color );
202
203Draws an B<filled> trigon (triangle) with vertices C<($x1,$y1)>, C<($x2,$y2)>,
204C<($x3,$y3)> and $color.
205Antialias is turned on automatically.
206Returns $self
207
208=head2 draw_polygon
209
210 $sdlx_surface->draw_polygon( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color, $antialias );
211
212Draws an unfilled polygon with vertices C<($xN,$yN)> and $color.
213Antialias is turned on if $antialias is true.
214Returns $self
215
216=head2 draw_polygon_filled
217
218 $sdlx_surface->draw_polygon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \@color );
219
220Draws an B<filled> polygon with vertices C<($xN,$yN)> and $color.
221Antialias is turned on automatically.
222Returns $self
223
224=head2 draw_arc
225
226 $sdlx_surface->draw_arc( [ $x, $y ], $radius, $start, $end, $color );
227
228Draws an arc around C<($x,$y)> with $radius, $start radius, $end radius
229and $color.
230
231Returns $self
232
233=head2 draw_ellipse
234
235 $sdlx_surface->draw_ellipse( [ $x, $y ], $rx, $ry, $color );
236
237Draws an unfilled ellipse centered at C<($x,$y)> with horizontal radius $rx,
238vertical radius $ry and $color.
239Antialias is turned on if $antialias is true.
240
241Returns $self
242
243=head2 draw_ellipse_filled
244
245 $sdlx_surface->draw_ellipse_filled( [ $x, $y ], $rx, $ry, $color );
246
247Draws an B<filled> ellipse centered at C<($x,$y)> with horizontal radius $rx,
248vertical radius $ry and $color.
249Antialias is turned on automatically.
250
251Returns $self
252
253=head2 draw_bezier
254
255 $sdlx_surface->draw_bezier( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], $s, $color );
256
257Draws a bezier curve of points C<($xN,$yN)> using $s steps for
258interpolation and $color.
259Antialias is turned on automatically.
260
261Returns $self
262
263=head2 draw_gfx_text
264
265Draw text using gfx (not pretty but fast) at give vector, color.
266
267 $surf->draw_gfx_text( [0,0], 0xffffffff, "fooo");
268 $surf->draw_gfx_text( [10,10], [20,20,20,20], "fooo");
269
270You can also set the gfx font but passing a hash reference as shown below.
271
272 my $f = '';
273 open( my $FH, '<', 'test/data/5x7.fnt');
274 binmode ($FH);
275 read($FH, $f, 4096);
276 close ($FH);
277 
278 my $font =  {data=>$f, cw => 5, ch => 7};
279 $surf->draw_gfx_text( [0,0], 0xffffffff, "fooo", $font );
280
281Returns $self
282
283=head1 AUTHORS
284
285See L<SDL/AUTHORS>.
286