.\" -*- 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::SDL::Cookbook::PDL 3pm"
.TH pods::SDL::Cookbook::PDL 3pm 2024-03-28 "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
SDL::CookBook::PDL \-\- CookBook for SDL + PDL
.PP
PDL provides great number crunching capabilities to Perl and SDL provides game\-developer quality real\-time bitmapping and sound.  You can use PDL and SDL ''together'' to create real\-time, responsive animations and simulations.  In this section we will go through the pleasures and pitfalls of working with both powerhouse libraries.
.SS CATEGORY
.IX Subsection "CATEGORY"
Cookbook
.SH "Creating a SDL Surface piddle"
.IX Header "Creating a SDL Surface piddle"
PDL's core type is a piddle. Once a piddle is provided to PDL it can go do a numerous amounts of things. Please see the example in 'examples/cookbook/pdl.pl' that came with this module.
.SS "Creating a simple piddle"
.IX Subsection "Creating a simple piddle"
First lets get the right modules.
.PP
.Vb 5
\&  use PDL;
\&  use SDL::Rect;
\&  use SDL::Video;
\&  use SDL::Surface;
\&  use SDL::PixelFormat;
.Ve
.PP
Suppose you want a surface of size (200,400) and 32 bit (RGBA).
.PP
.Vb 1
\&   my ( $bytes_per_pixel, $width, $height ) = ( 4, 200, 400 );
.Ve
.PP
Define the \f(CW$width\fR, \f(CW$height\fR and \f(CW$bytes_per_pixel\fR. Your \f(CW$bytes_per_pixel\fR is the number of bits (in this case 32) divided by 8 bits per byte. Therefore for our 32 bpp we have 4 Bpp;
.PP
.Vb 1
\&   my $piddle  = zeros( byte, $bytes_per_pixel, $width, $height );
.Ve
.PP
Create a normal \f(CW$piddle\fR with zeros, byte format and the Bpp x width x height dimensions.
.PP
.Vb 1
\&   my $pointer = $piddle\->get_dataref();
.Ve
.PP
Here is where we get the actual data the piddle is pointing to. We will have SDL create a new surface from this function.
.PP
.Vb 2
\&   my $surface = SDL::Surface\->new_from( $pointer, $width, $height, 32,
\&        $width * $bytes_per_pixel );
.Ve
.PP
Using the same dimensions we create the surface using new_form. The width *  Bpp is the scanline (pitch) of the surface in bytes.
.PP
.Vb 2
\&   warn "Made surface of $width, $height and ". $surface\->format\->BytesPerPixel;
\&   return ( $piddle, $surface );
.Ve
.PP
Finally make sure that the surface actually has the correct dimensions we gave.
.PP
\&\fBNOTE:\fR \f(CW$surface\fR\->format\->BytesPerPixel must return 1,2,3,4. !!
.PP
Now you can blit and use the surface as needed; and do PDL operations as required.
.SS "Operating on the Surface safely"
.IX Subsection "Operating on the Surface safely"
To make sure SDL is in sync with the data. You must call SDL::Video::lock \fBbefore\fR doing PDL operations on the piddle.
.PP
.Vb 1
\&    SDL::Video::lock_surface($surface);
\&
\&    $piddle\->mslice( \*(AqX\*(Aq, [ rand(400), rand(400), 1 ], [ rand(200), rand(200), 1 ] )
\&        .= pdl( rand(225), rand(225), rand(255), 255 );
.Ve
.PP
After that you can unlock the surface to blit.
.PP
.Vb 1
\&    SDL::Video::unlock_surface($surface);
.Ve
.SS "Error due to BPP at blitting"
.IX Subsection "Error due to BPP at blitting"
When blitting the new surface check for the return value to see if there has been a problem.
.PP
.Vb 4
\&    my $b = SDL::Video::blit_surface(
\&        $surface,  SDL::Rect\->new( 0, 0, $surface\->w, $surface\->h ),
\&        $app, SDL::Rect\->new(  ( $app\->w \- $surface\->w ) / 2, ( $app\->h \- $surface\->h ) / 2, $app\->w, $app\->h )
\&       );
\&
\&    die "Could not blit: " . SDL::get_error() if ( $b == \-1 );
.Ve
.PP
If the error message is 'Blit combination not supported' that means that the BPP is incorrect or inconsistent with the dimensions.
After that a simple update_rect will so your new surface on the screen.
.SH AUTHORS
.IX Header "AUTHORS"
See "AUTHORS" in SDL.