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;
41 # change these values as necessary
42 my $title = 'My SDL Rectangle-Drawing App';
43 my ($width, $height, $depth) = ( 640, 480, 16 );
44 my ($red, $green, $blue) = ( 0x00, 0x00, 0xff );
45 my ($rect_width, $rect_height) = ( 100, 100 );
46 my ($rect_x, $rect_y) = ( 270, 190 );
48 my $app = SDL::App->new(
54 my $rect = SDL::Rect->new(
55 -height => $rect_height,
56 -width => $rect_width,
61 my $color = SDL::Color->new(
67 $app->fill( $rect, $color );
68 $app->update( $rect );
70 # your code here; remove the next line
78 SDL::Tutorial::Drawing - basic drawing with Perl SDL
82 # to read this tutorial
83 $ perldoc SDL::Tutorial::Drawing
85 # to create a bare-bones SDL app based on this tutorial
86 $ perl -MSDL::Tutorial::Drawing=basic_app.pl -e 1
90 As explained in L<SDL::Tutorial>, all graphics in SDL live on a surface.
91 Consequently, all drawing operations operate on a surface, whether drawing on
92 it directly or blitting from another surface. The important modules for this
93 exercise are L<SDL::Rect> and L<SDL::Color>.
95 As usual, we'll start by creating a L<SDL::App> object:
99 my $app = SDL::App->new(
105 =head2 Creating a New Surface with SDL::Rect
107 A SDL::Rect object is an SDL surface, just as an SDL::App object is. As you'd
108 expect, you need to specify the size of this object as you create it. You can
109 also specify its coordinates relative to the origin.
111 B<Note:> The origin, or coordinates 0, 0, is at the upper left of the screen.
113 Here's how to create a square 100 pixels by 100 pixels centered in the window:
117 my $rect = SDL::Rect->new(
124 This won't actually display anything yet, it just creates a rectangular
125 surface. Of course, even if it did display, you wouldn't see anything, as it
126 defaults to the background color just as C<$app> does. That's where SDL::Color
129 =head2 A Bit About Color
131 SDL::Color objects represent colors in the SDL world. These colors are
132 additive, so they're represented as mixtures of Red, Green, and Blue
133 components. The color values are traditionally given in hexadecimal numbers.
134 If you're exceedingly clever or really like the math, you can figure out which
135 values are possible by comparing them to your current bit depth. SDL does a
136 lot of autoconversion for you, though, so unless extreme speed or pedantic
137 detail are important, you can get by without worrying too much.
139 Creating a color object is reasonably easy. As the color scheme is additive,
140 the lower the number for a color component, the less of that color. The higher
141 the number, the higher the component. Experimentation may be your best bet, as
142 these aren't exactly the primary colors you learned as a child (since that's a
145 Let's create a nice, full blue:
149 my $color = SDL::Color->new(
155 B<Note:> The numbers are in hex; if you've never used hex notation in Perl
156 before, the leading C<0x> just signifies that the rest of the number is in
157 base-16. In this case, the blue component has a value of 255 and the red and
160 =head2 Filling Part of a Surface
162 The C<fill()> method of SDL::Surface fills a given rectangular section of the
163 surface with the given color. Since we already have a rect and a color, it's
166 $app->fill( $rect, $color );
168 That's a little subtle; it turns out that the SDL::Rect created earlier
169 represents a destination within the surface of the main window. It's not
170 attached to anything else. We could re-use it later, as necessary.
172 =head2 Updating the Surface
174 If you try the code so far, you'll notice that it still doesn't display. Don't
175 fret. All that's left to do is to call C<update()> on the appropriate surface.
176 As usual, C<update()> takes a Rect to control which part of the surface to
177 update. In this case, that's:
179 $app->update( $rect );
181 This may seem like a useless extra step, but it can be quite handy. While
182 drawing to the screen directly seems like the fastest way to go, the
183 intricacies of working with hardware with the appropriate timings is tricky.
185 =head2 Working With The App
187 You can, of course, create all sorts of Rects with different sizes and
188 coordinates as well as varied colors and experiment to your heart's content
189 drawing them to the window. It's more fun when you can animate them smoothly,
192 That, as usual, is another tutorial.
198 =item L<SDL::Tutorial>
200 the basics of Perl SDL.
202 =item L<SDL::Tutorial::Animation>
204 basic animation techniques
210 chromatic, E<lt>chromatic@wgz.orgE<gt>
212 Written for and maintained by the Perl SDL project, L<http://sdl.perl.org/>.
220 Copyright (c) 2003 - 2004, chromatic. All rights reserved. This module is
221 distributed under the same terms as Perl itself, in the hope that it is useful
222 but certainly under no guarantee.