6d151f743b9dd1518d63061614f37867b860808f
[sdlgit/SDL_perl.git] / lib / SDL / Tutorial.pm
1 #!/usr/bin/env perl
2 #
3 # Tutorial.pm
4 #
5 # Copyright (C) 2005 David J. Goehrig <dgoehrig@cpan.org>
6 #
7 # ------------------------------------------------------------------------------
8 #
9 # This library is free software; you can redistribute it and/or
10 # modify it under the terms of the GNU Lesser General Public
11 # License as published by the Free Software Foundation; either
12 # version 2.1 of the License, or (at your option) any later version.
13
14 # This library is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 # Lesser General Public License for more details.
18
19 # You should have received a copy of the GNU Lesser General Public
20 # License along with this library; if not, write to the Free Software
21 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
22 #
23 # ------------------------------------------------------------------------------
24 #
25 # Please feel free to send questions, suggestions or improvements to:
26 #
27 #       David J. Goehrig
28 #       dgoehrig@cpan.org
29 #
30
31 package SDL::Tutorial;
32
33 use strict;
34 use SDL;
35 use SDL::App;
36
37 # change these values as necessary
38 my  $title                   = 'My SDL App';
39 my ($width, $height, $depth) = ( 640, 480, 16 );
40
41 my $app = SDL::App->new(
42         -width  => $width,
43         -height => $height,
44         -depth  => $depth,
45         -title  => $title,
46 );
47
48 # your code here; remove the next line
49 sleep 2;
50 END_HERE
51
52 1;
53
54 __END__
55
56 =head1 NAME
57
58 SDL::Tutorial - introduction to Perl SDL
59
60 =head1 SYNOPSIS
61
62         # to read this tutorial
63         $ perldoc SDL::Tutorial
64
65         # to create a bare-bones SDL app based on this tutorial
66         $ perl -MSDL::Tutorial=basic_app.pl -e 1
67
68 =head1 SDL BASICS
69
70 SDL, the Simple DirectMedia Layer, is a cross-platform multimedia library.
71 These are the Perl 5 bindings.  You can find out more about SDL at
72 L<http://www.libsdl.org/>.
73
74 Creating an SDL application with Perl is easy.  You have to know a few basics,
75 though.  Here's how to get up and running as quickly as possible.
76
77 =head2 Surfaces
78
79 All graphics in SDL live on a surface.  You'll need at least one.  That's what
80 L<SDL::App> provides.
81
82 Of course, before you can get a surface, you need to initialize your video
83 mode.  SDL gives you several options, including whether to run in a window or
84 take over the full screen, the size of the window, the bit depth of your
85 colors, and whether to use hardware acceleration.  For now, we'll build
86 something really simple.
87
88 =head2 Initialization
89
90 SDL::App makes it easy to initialize video and create a surface.  Here's how to
91 ask for a windowed surface with 640x480x16 resolution:
92
93         use SDL::App;
94
95         my $app = SDL::App->new(
96                 -width  => 640,
97                 -height => 480,
98                 -depth  => 16,
99         );
100
101 You can get more creative, especially if you use the C<-title> and C<-icon>
102 attributes in a windowed application.  Here's how to set the window title of
103 the application to C<My SDL Program>:
104
105         use SDL::App;
106
107         my $app = SDL::App->new(
108                 -height => 640,
109                 -width  => 480,
110                 -depth  => 16,
111                 -title  => 'My SDL Program',
112         );
113
114 Setting an icon is a little more involved -- you have to load an image onto a
115 surface.  That's a bit more complicated, but see the C<-name> parameter to
116 C<SDL::Surface->new()> if you want to skip ahead.
117
118 =head2 Working With The App
119
120 Since C<$app> from the code above is just an SDL surface with some extra sugar,
121 it behaves much like L<SDL::Surface>.  In particular, the all-important C<blit>
122 and C<update> methods work.  You'll need to create L<SDL::Rect> objects
123 representing sources of graphics to draw onto the C<$app>'s surface, C<blit>
124 them there, then C<update> the C<$app>.
125
126 B<Note:>  "blitting" is copying a chunk of memory from one place to another.
127
128 That, however, is another tutorial.
129
130 =head1 SEE ALSO
131
132 =over 4
133
134 =item L<SDL::Tutorial::Drawing>
135
136 basic drawing with rectangles
137
138 =item L<SDL::Tutorial::Animation>
139
140 basic rectangle animation
141
142 =item L<SDL::Tutorial::Images>
143
144 image loading and animation
145
146 =back
147
148 =head1 AUTHOR
149
150 chromatic, E<lt>chromatic@wgz.orgE<gt>.  
151
152 Written for and maintained by the Perl SDL project, L<http://sdl.perl.org/>.
153
154 =head1 COPYRIGHT
155
156 Copyright (c) 2003 - 2004, chromatic.  All rights reserved.  This module is
157 distributed under the same terms as Perl itself, in the hope that it is useful
158 but certainly under no guarantee.