.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "pods::SDLx::Surface 3pm"
.TH pods::SDLx::Surface 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SDLx::Surface \- Graphic surface matrix extension
.SH CATEGORY
.IX Header "CATEGORY"
Extension
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\& use SDL;
\& use SDL::Video;
\& use SDLx::Surface;
\&
\& # Create the main surface (display)
\& SDL::init(SDL_INIT_VIDEO);
\& my $display = SDL::Video::set_video_mode(640, 480, 16, SDL_SWSURFACE);
\&
\& my $surf_matrix = SDLx::Surface\->new( surface => $display);
\& 
\& $surf_matrix\->[10][10] = 0xFFFF; #for 16bpp write white at x = 10 and y=10
\&
\& $surf_matrix\->surface( $new_surface );
\&
\& my $orig_surface = $surf_matrix\->surface();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
An \f(CW\*(C`SDLx::Surface\*(C'\fR allows matrix read and write to a surface, safely.
.SH CONSTRUCTOR
.IX Header "CONSTRUCTOR"
.SS new
.IX Subsection "new"
Takes a SDL::Surface in hash format.
.PP
If a surface is passed to 'surface =>' that is loaded. Otherwise you can define at least a width and a height.
.PP
.Vb 1
\&        SDLx::Surface\->new(  surface => $surface) # The $surface is loaded
\&
\&        SDLx::Surface\->new( width=> 400, height=>200) 
\&                # A SDL::Surface\->new( SDL_ANYFORMAT, 400, 200, 32) is loaded
\&
\&        SDLx::Surface\->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>24 ) 
\&                # A SDL::Surface\->new( SDL_SWSURFACE, 400, 200, 24) is loaded 
\&
\&        SDLx::Surface\->new( width=> 400, height=>200, flags=> SDL_SWSURFACE, depth=>32, greenmask=>0xFF000000 )
\&                # A SDL::Surface\->new( SDL_ANYFORMAT, 400, 200, 32, 0, 0xFF000000,0, 0, 0 ) is loaded
\&        SDLx::Surface\->new( w => 1, h => 1, color => 0xFF0000FF )
\&                # A SDL::Surface\->new( SDL_ANYFORMAT, 1, 1, 32, 0, 0, 0, 0 ) is loaded
\&                all pixels are colored with color (red)
.Ve
.SS display
.IX Subsection "display"
If SDLx::App::new or SDL::Video::get_video_mode called before then:
.PP
.Vb 1
\& my $appx = SDLx::Surface::display();
.Ve
.PP
gets the display if it is already made. Passed options are ignored. Otherwise you can quickly make the display with :
.PP
.Vb 1
\& SDLx::Surface::display( width => 20, height => 20) #depth => 32 and SDL_ANYFORMAT used
.Ve
.PP
or you can also pass flags and depth.
.PP
.Vb 1
\& SDLx::Surface::display( width => 20, height => 20, flags=> SDL_HWSURFACE, depth=>24)
.Ve
.PP
You can also use the keys \f(CW\*(C`w\*(C'\fR and \f(CW\*(C`h\*(C'\fR in place of \f(CW\*(C`width\*(C'\fR and \f(CW\*(C`height\*(C'\fR, as with \f(CW\*(C`new\*(C'\fR.
.PP
Get or create the main display surface and attach to a \f(CW\*(C`SDLx::Surface\*(C'\fR.
.SS duplicate
.IX Subsection "duplicate"
Does a attributes only, no pixel, copy of another SDLx::Surface.
.SH ATTRIBUTES
.IX Header "ATTRIBUTES"
.SS surface
.IX Subsection "surface"
If a SDL::Surface is passed it is attached to the matrix. Returns the SDL::Surface that is currently attached to this SDLx::Surface
.SS "w, h, format, pitch, flags"
.IX Subsection "w, h, format, pitch, flags"
Returns the inner SDL::Surface's respective attribute. See \f(CW\*(C`SDL::Surface\*(C'\fR.
.SS clip_rect
.IX Subsection "clip_rect"
Sets the passed \f(CW\*(C`SDL::Rect\*(C'\fR as the new clip_rect for the surface. Returns the SDL::Surface's clip_rect. See 
SDL::Video::get_clip_rect and SDL::Video::set_clip_rect.
=head1 EXTENSIONS
.SS load
.IX Subsection "load"
.Vb 2
\& my $surface = SDLx::Surface\->load( \*(Aqhero.png\*(Aq );
\& my $surface = SDLx::Surface\->load( \*(Aqhero.dat\*(Aq, \*(Aqbmp\*(Aq );
.Ve
.PP
Loads the given image file into a \fInew\fR SDLx::Surface surface. A new
surface is \fBalways\fR created, even if you call it from an already crafted
object. Croaks on errors such as no support built for that image extension
or a file reading error (the error message is SDL::get_error and should
give more details).
.PP
Note that \fBload()\fR will automatically figure out the extension based on the
filename you provide. If you wish to force an extension for whatever reason
(like having a filename with a different extension or none at all), you can
optionally pass the file type as a second parameter. Case is not relevant.
.PP
If you don't have SDL_image in your build, only bitmap images will be
supported.
.PP
Returns the new Surface.
.SS blit
.IX Subsection "blit"
.Vb 1
\& $sdlx_surface\->blit( $dest, $src_rect, $dest_rect );
.Ve
.PP
Blits \f(CW\*(C`SDLx::Surface\*(C'\fR onto \f(CW$dest\fR surface. 
\&\f(CW$src_rect\fR or \f(CW$dest_rect\fR are optional. If \f(CW$src_rect\fR is omitted, it will be the size of the entire surface. If \f(CW$dest_rect\fR is omitted, 
it will be blitted at \f(CW\*(C`(0, 0)\*(C'\fR. \f(CW$src_rect\fR or \f(CW$dest_rect\fR can be array refs or \f(CW\*(C`SDL::Rect\*(C'\fR. \f(CW$dest\fR can be \f(CW\*(C`SDLx::Surface\*(C'\fR or \f(CW\*(C`SDL::Surface\*(C'\fR.
.PP
Note that the final blit rectangle is stored in \f(CW$dest_rect\fR after clipping is performed.
.PP
Returns \f(CW$self\fR
.SS blit_by
.IX Subsection "blit_by"
.Vb 1
\& $sdlx_surface\->blit_by( $src, $src_rect, $dest_rect );
.Ve
.PP
Does the same as \f(CW\*(C`blit\*(C'\fR but the \f(CW\*(C`SDLx::Surface\*(C'\fR is the one being blitted to.
This is useful when the surface you have isn't an \f(CW\*(C`SDLx::Surface\*(C'\fR, but the surface it is being blitted to is.
.PP
Note that the final blit rectangle is stored in \f(CW$dest_rect\fR after clipping is performed.
.SS flip
.IX Subsection "flip"
Applies SDL::Video::flip to the Surface, with error checking.
.PP
Returns \f(CW$self\fR
.SS update
.IX Subsection "update"
.Vb 2
\& $sdlx_surface\->update(); # whole surface is updated
\& $sdlx_surface\->update([0,0,1,1]); # only that area (0,0,1,1) is updated
\& 
\& $sdlx_surface\->update( [ SDL::Rect\->new(0,0,1,2) ... ]); # defined rects are updated
.Ve
.PP
Applies SDL::Video::update_rect for no rect or 1 array ref. Applies 
SDL::Video::update_rects for array of SDL::Rects.
.PP
Returns \f(CW$self\fR
.SS draw_rect
.IX Subsection "draw_rect"
.Vb 2
\& $sdlx_surface\->draw_rect( [$x,$y,$w,$h], 0xFFFF00FF );
\& $sdlx_surface\->draw_rect( SDL::Rect\->new($x,$y,$w,$h), 0xFFFF00FF );
.Ve
.PP
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.
.PP
Returns \f(CW$self\fR
.SS draw_line
.IX Subsection "draw_line"
.Vb 2
\& $sdlx_surface\->draw_line( [$x1, $y1], [$x2, $y2], $color, $antialias); # $color is a number
\& $sdlx_surface\->draw_line( [$x1, $y1], [$x2, $y2], \e@color, $antialias); #
.Ve
.PP
Draws a line on the surface. Antialias is turned on if \f(CW$antialias\fR is true.
.PP
Returns \f(CW$self\fR
.SS draw_circle
.IX Subsection "draw_circle"
.Vb 1
\& $sdlx_surface\->draw_circle( [$x1, $y1], $radius, \e@color, $antialias );
.Ve
.PP
Draws an unfilled circle at \f(CW\*(C`($x1,$y1)\*(C'\fR of size \f(CW$radius\fR and \f(CW$color\fR.
Antialias is turned on if \f(CW$antialias\fR is true. 
Returns \f(CW$self\fR
.SS draw_circle_filled
.IX Subsection "draw_circle_filled"
.Vb 1
\& $sdlx_surface\->draw_circle_filled( [$x1, $y1], $radius, \e@color );
.Ve
.PP
Draws an \fBfilled\fR circle at \f(CW\*(C`($x1,$y1)\*(C'\fR of size \f(CW$radius\fR and \f(CW$color\fR.
Antialias is turned on automatically. 
Returns \f(CW$self\fR
.SS draw_trigon
.IX Subsection "draw_trigon"
.Vb 1
\& $sdlx_surface\->draw_trigon( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \e@color, $antialias );
.Ve
.PP
Draws an unfilled trigon (triangle) with vertices \f(CW\*(C`($x1,$y1)\*(C'\fR, \f(CW\*(C`($x2,$y2)\*(C'\fR,
\&\f(CW\*(C`($x3,$y3)\*(C'\fR and \f(CW$color\fR.
Antialias is turned on if \f(CW$antialias\fR is true.
Returns \f(CW$self\fR
.SS draw_trigon_filled
.IX Subsection "draw_trigon_filled"
.Vb 1
\& $sdlx_surface\->draw_trigon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3] ], \e@color );
.Ve
.PP
Draws an \fBfilled\fR trigon (triangle) with vertices \f(CW\*(C`($x1,$y1)\*(C'\fR, \f(CW\*(C`($x2,$y2)\*(C'\fR,
\&\f(CW\*(C`($x3,$y3)\*(C'\fR and \f(CW$color\fR.
Antialias is turned on automatically.
Returns \f(CW$self\fR
.SS draw_polygon
.IX Subsection "draw_polygon"
.Vb 1
\& $sdlx_surface\->draw_polygon( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \e@color, $antialias );
.Ve
.PP
Draws an unfilled polygon with vertices \f(CW\*(C`($xN,$yN)\*(C'\fR and \f(CW$color\fR.
Antialias is turned on if \f(CW$antialias\fR is true.
Returns \f(CW$self\fR
.SS draw_polygon_filled
.IX Subsection "draw_polygon_filled"
.Vb 1
\& $sdlx_surface\->draw_polygon_filled( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], \e@color );
.Ve
.PP
Draws an \fBfilled\fR polygon with vertices \f(CW\*(C`($xN,$yN)\*(C'\fR and \f(CW$color\fR.
Antialias is turned on automatically.
Returns \f(CW$self\fR
.SS draw_arc
.IX Subsection "draw_arc"
.Vb 1
\& $sdlx_surface\->draw_arc( [ $x, $y ], $radius, $start, $end, $color );
.Ve
.PP
Draws an arc around \f(CW\*(C`($x,$y)\*(C'\fR with \f(CW$radius\fR, \f(CW$start\fR radius, \f(CW$end\fR radius
and \f(CW$color\fR.
.PP
Returns \f(CW$self\fR
.SS draw_ellipse
.IX Subsection "draw_ellipse"
.Vb 1
\& $sdlx_surface\->draw_ellipse( [ $x, $y ], $rx, $ry, $color );
.Ve
.PP
Draws an unfilled ellipse centered at \f(CW\*(C`($x,$y)\*(C'\fR with horizontal radius \f(CW$rx\fR,
vertical radius \f(CW$ry\fR and \f(CW$color\fR.
Antialias is turned on if \f(CW$antialias\fR is true.
.PP
Returns \f(CW$self\fR
.SS draw_ellipse_filled
.IX Subsection "draw_ellipse_filled"
.Vb 1
\& $sdlx_surface\->draw_ellipse_filled( [ $x, $y ], $rx, $ry, $color );
.Ve
.PP
Draws an \fBfilled\fR ellipse centered at \f(CW\*(C`($x,$y)\*(C'\fR with horizontal radius \f(CW$rx\fR,
vertical radius \f(CW$ry\fR and \f(CW$color\fR.
Antialias is turned on automatically.
.PP
Returns \f(CW$self\fR
.SS draw_bezier
.IX Subsection "draw_bezier"
.Vb 1
\& $sdlx_surface\->draw_bezier( [ [$x1, $y1], [$x2, $y2], [$x3, y3], ... ], $s, $color );
.Ve
.PP
Draws a bezier curve of points \f(CW\*(C`($xN,$yN)\*(C'\fR using \f(CW$s\fR steps for
interpolation and \f(CW$color\fR.
Antialias is turned on automatically.
.PP
Returns \f(CW$self\fR
.SS draw_gfx_text
.IX Subsection "draw_gfx_text"
Draw text using gfx (not pretty but fast) at give vector, color.
.PP
.Vb 2
\& $surf\->draw_gfx_text( [0,0], 0xffffffff, "fooo");
\& $surf\->draw_gfx_text( [10,10], [20,20,20,20], "fooo");
.Ve
.PP
You can also set the gfx font but passing a hash reference as shown below.
.PP
.Vb 5
\& my $f = \*(Aq\*(Aq;
\& open( my $FH, \*(Aq<\*(Aq, \*(Aqtest/data/5x7.fnt\*(Aq);
\& binmode ($FH);
\& read($FH, $f, 4096);
\& close ($FH);
\& 
\& my $font =  {data=>$f, cw => 5, ch => 7};
\& $surf\->draw_gfx_text( [0,0], 0xffffffff, "fooo", $font );
.Ve
.PP
Returns \f(CW$self\fR
.SH AUTHORS
.IX Header "AUTHORS"
See "AUTHORS" in SDL.