X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Fdocs%2FTutorial.pod;fp=lib%2Fdocs%2FTutorial.pod;h=bd9f6e075894584a52554f272f35525b4bcb7047;hb=896b04ee008898e1c1edbdd432bedaa8643400dc;hp=0000000000000000000000000000000000000000;hpb=b3cdeb39a431b026168c4060bf74001fcee07493;p=sdlgit%2FSDL_perl.git

diff --git a/lib/docs/Tutorial.pod b/lib/docs/Tutorial.pod
new file mode 100644
index 0000000..bd9f6e0
--- /dev/null
+++ b/lib/docs/Tutorial.pod
@@ -0,0 +1,103 @@
+=head1 NAME
+
+SDL::Tutorial - introduction to Perl SDL
+
+=head1 SYNOPSIS
+
+	# to read this tutorial
+	$ perldoc SDL::Tutorial
+
+	# to create a bare-bones SDL app based on this tutorial
+	$ perl -MSDL::Tutorial -e 1
+
+=head1 SDL BASICS
+
+SDL, the Simple DirectMedia Layer, is a cross-platform multimedia library.
+These are the Perl 5 bindings.  You can find out more about SDL at
+L<http://www.libsdl.org/>.
+
+Creating an SDL application with Perl is easy.  You have to know a few basics,
+though.  Here's how to get up and running as quickly as possible.
+
+=head2 Surfaces
+
+All graphics in SDL live on a surface.  You'll need at least one.  That's what
+L<SDL::App> provides.
+
+Of course, before you can get a surface, you need to initialize your video
+mode.  SDL gives you several options, including whether to run in a window or
+take over the full screen, the size of the window, the bit depth of your
+colors, and whether to use hardware acceleration.  For now, we'll build
+something really simple.
+
+=head2 Initialization
+
+SDL::App makes it easy to initialize video and create a surface.  Here's how to
+ask for a windowed surface with 640x480x16 resolution:
+
+	use SDL::App;
+
+	my $app = SDL::App->new(
+		-width  => 640,
+		-height => 480,
+		-depth  => 16,
+	);
+
+You can get more creative, especially if you use the C<-title> and C<-icon>
+attributes in a windowed application.  Here's how to set the window title of
+the application to C<My SDL Program>:
+
+	use SDL::App;
+
+	my $app = SDL::App->new(
+		-height => 640,
+		-width  => 480,
+		-depth  => 16,
+		-title  => 'My SDL Program',
+	);
+
+Setting an icon is a little more involved -- you have to load an image onto a
+surface.  That's a bit more complicated, but see the C<-name> parameter to
+C<SDL::Surface->new()> if you want to skip ahead.
+
+=head2 Working With The App
+
+Since C<$app> from the code above is just an SDL surface with some extra sugar,
+it behaves much like L<SDL::Surface>.  In particular, the all-important C<blit>
+and C<update> methods work.  You'll need to create L<SDL::Rect> objects
+representing sources of graphics to draw onto the C<$app>'s surface, C<blit>
+them there, then C<update> the C<$app>.
+
+B<Note:>  "blitting" is copying a chunk of memory from one place to another.
+
+That, however, is another tutorial.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<SDL::Tutorial::Drawing>
+
+basic drawing with rectangles
+
+=item L<SDL::Tutorial::Animation>
+
+basic rectangle animation
+
+=item L<SDL::Tutorial::Images>
+
+image loading and animation
+
+=back
+
+=head1 AUTHOR
+
+chromatic, E<lt>chromatic@wgz.orgE<gt>.  
+
+Written for and maintained by the Perl SDL project, L<http://sdl.perl.org/>.
+
+=head1 COPYRIGHT
+
+Copyright (c) 2003 - 2004, chromatic.  All rights reserved.  This module is
+distributed under the same terms as Perl itself, in the hope that it is useful
+but certainly under no guarantee.