5 # Copyright (C) 2005 David J. Goehrig <dgoehrig@cpan.org>
7 # ------------------------------------------------------------------------------
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.
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.
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
23 # ------------------------------------------------------------------------------
25 # Please feel free to send questions, suggestions or improvements to:
31 package SDL::Tutorial:Drawing;
39 # change these values as necessary
40 my $title = 'My SDL Rectangle-Drawing App';
41 my ($width, $height, $depth) = ( 640, 480, 16 );
42 my ($red, $green, $blue) = ( 0x00, 0x00, 0xff );
43 my ($rect_width, $rect_height) = ( 100, 100 );
44 my ($rect_x, $rect_y) = ( 270, 190 );
46 my $app = SDL::App->new(
52 my $rect = SDL::Rect->new(
53 -height => $rect_height,
54 -width => $rect_width,
59 my $color = SDL::Color->new(
65 $app->fill( $rect, $color );
66 $app->update( $rect );
68 # your code here; remove the next line
77 SDL::Tutorial::Drawing - basic drawing with Perl SDL
81 # to read this tutorial
82 $ perldoc SDL::Tutorial::Drawing
84 # to create a bare-bones SDL app based on this tutorial
85 $ perl -MSDL::Tutorial::Drawing=basic_app.pl -e 1
89 As explained in L<SDL::Tutorial>, all graphics in SDL live on a surface.
90 Consequently, all drawing operations operate on a surface, whether drawing on
91 it directly or blitting from another surface. The important modules for this
92 exercise are L<SDL::Rect> and L<SDL::Color>.
94 As usual, we'll start by creating a L<SDL::App> object:
98 my $app = SDL::App->new(
104 =head2 Creating a New Surface with SDL::Rect
106 A SDL::Rect object is an SDL surface, just as an SDL::App object is. As you'd
107 expect, you need to specify the size of this object as you create it. You can
108 also specify its coordinates relative to the origin.
110 B<Note:> The origin, or coordinates 0, 0, is at the upper left of the screen.
112 Here's how to create a square 100 pixels by 100 pixels centered in the window:
116 my $rect = SDL::Rect->new(
123 This won't actually display anything yet, it just creates a rectangular
124 surface. Of course, even if it did display, you wouldn't see anything, as it
125 defaults to the background color just as C<$app> does. That's where SDL::Color
128 =head2 A Bit About Color
130 SDL::Color objects represent colors in the SDL world. These colors are
131 additive, so they're represented as mixtures of Red, Green, and Blue
132 components. The color values are traditionally given in hexadecimal numbers.
133 If you're exceedingly clever or really like the math, you can figure out which
134 values are possible by comparing them to your current bit depth. SDL does a
135 lot of autoconversion for you, though, so unless extreme speed or pedantic
136 detail are important, you can get by without worrying too much.
138 Creating a color object is reasonably easy. As the color scheme is additive,
139 the lower the number for a color component, the less of that color. The higher
140 the number, the higher the component. Experimentation may be your best bet, as
141 these aren't exactly the primary colors you learned as a child (since that's a
144 Let's create a nice, full blue:
148 my $color = SDL::Color->new(
154 B<Note:> The numbers are in hex; if you've never used hex notation in Perl
155 before, the leading C<0x> just signifies that the rest of the number is in
156 base-16. In this case, the blue component has a value of 255 and the red and
159 =head2 Filling Part of a Surface
161 The C<fill()> method of SDL::Surface fills a given rectangular section of the
162 surface with the given color. Since we already have a rect and a color, it's
165 $app->fill( $rect, $color );
167 That's a little subtle; it turns out that the SDL::Rect created earlier
168 represents a destination within the surface of the main window. It's not
169 attached to anything else. We could re-use it later, as necessary.
171 =head2 Updating the Surface
173 If you try the code so far, you'll notice that it still doesn't display. Don't
174 fret. All that's left to do is to call C<update()> on the appropriate surface.
175 As usual, C<update()> takes a Rect to control which part of the surface to
176 update. In this case, that's:
178 $app->update( $rect );
180 This may seem like a useless extra step, but it can be quite handy. While
181 drawing to the screen directly seems like the fastest way to go, the
182 intricacies of working with hardware with the appropriate timings is tricky.
184 =head2 Working With The App
186 You can, of course, create all sorts of Rects with different sizes and
187 coordinates as well as varied colors and experiment to your heart's content
188 drawing them to the window. It's more fun when you can animate them smoothly,
191 That, as usual, is another tutorial.
197 =item L<SDL::Tutorial>
199 the basics of Perl SDL.
201 =item L<SDL::Tutorial::Animation>
203 basic animation techniques
209 chromatic, E<lt>chromatic@wgz.orgE<gt>
211 Written for and maintained by the Perl SDL project, L<http://sdl.perl.org/>.
219 Copyright (c) 2003 - 2004, chromatic. All rights reserved. This module is
220 distributed under the same terms as Perl itself, in the hope that it is useful
221 but certainly under no guarantee.