/lib/pods/SDLx/Surface.pod

http://github.com/PerlGameDev/SDL · Unknown · 286 lines · 169 code · 117 blank · 0 comment · 0 complexity · 0575fb5cec1ada09f6be2b9118e83fde MD5 · raw file

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