Commit | Line | Data |
bfd90409 |
1 | #!/usr/bin/env perl |
2 | # |
3 | # Drawing.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 | |
02ddb292 |
31 | package SDL::Tutorial::Drawing; |
bfd90409 |
32 | |
33 | use strict; |
02ddb292 |
34 | use warnings; |
35 | |
bfd90409 |
36 | use SDL; |
37 | use SDL::App; |
38 | use SDL::Rect; |
39 | use SDL::Color; |
40 | |
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 ); |
47 | |
48 | my $app = SDL::App->new( |
49 | -width => $width, |
50 | -height => $height, |
51 | -depth => $depth, |
52 | ); |
53 | |
54 | my $rect = SDL::Rect->new( |
55 | -height => $rect_height, |
56 | -width => $rect_width, |
57 | -x => $rect_x, |
58 | -y => $rect_y, |
59 | ); |
60 | |
61 | my $color = SDL::Color->new( |
62 | -r => $red, |
63 | -g => $green, |
64 | -b => $blue, |
65 | ); |
66 | |
67 | $app->fill( $rect, $color ); |
68 | $app->update( $rect ); |
69 | |
70 | # your code here; remove the next line |
71 | sleep 2; |
bfd90409 |
72 | |
73 | 1; |
74 | __END__ |
75 | |
76 | =head1 NAME |
77 | |
78 | SDL::Tutorial::Drawing - basic drawing with Perl SDL |
79 | |
80 | =head1 SYNOPSIS |
81 | |
82 | # to read this tutorial |
83 | $ perldoc SDL::Tutorial::Drawing |
84 | |
85 | # to create a bare-bones SDL app based on this tutorial |
86 | $ perl -MSDL::Tutorial::Drawing=basic_app.pl -e 1 |
87 | |
88 | =head1 DRAWING BASICS |
89 | |
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>. |
94 | |
95 | As usual, we'll start by creating a L<SDL::App> object: |
96 | |
97 | use SDL::App; |
98 | |
99 | my $app = SDL::App->new( |
100 | -width => 640, |
101 | -height => 480, |
102 | -depth => 16, |
103 | ); |
104 | |
105 | =head2 Creating a New Surface with SDL::Rect |
106 | |
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. |
110 | |
111 | B<Note:> The origin, or coordinates 0, 0, is at the upper left of the screen. |
112 | |
113 | Here's how to create a square 100 pixels by 100 pixels centered in the window: |
114 | |
115 | use SDL::Rect; |
116 | |
117 | my $rect = SDL::Rect->new( |
118 | -height => 100, |
119 | -width => 100, |
120 | -x => 270, |
121 | -y => 390, |
122 | ); |
123 | |
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 |
127 | comes in. |
128 | |
129 | =head2 A Bit About Color |
130 | |
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. |
138 | |
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 |
143 | subtractive scheme). |
144 | |
145 | Let's create a nice, full blue: |
146 | |
147 | use SDL::Color; |
148 | |
149 | my $color = SDL::Color->new( |
150 | -r => 0x00, |
151 | -g => 0x00, |
152 | -b => 0xff, |
153 | ); |
154 | |
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 |
158 | green are both zero. |
159 | |
160 | =head2 Filling Part of a Surface |
161 | |
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 |
164 | as easy as saying: |
165 | |
166 | $app->fill( $rect, $color ); |
167 | |
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. |
171 | |
172 | =head2 Updating the Surface |
173 | |
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: |
178 | |
179 | $app->update( $rect ); |
180 | |
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. |
184 | |
185 | =head2 Working With The App |
186 | |
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, |
190 | though. |
191 | |
192 | That, as usual, is another tutorial. |
193 | |
194 | =head1 SEE ALSO |
195 | |
196 | =over 4 |
197 | |
198 | =item L<SDL::Tutorial> |
199 | |
200 | the basics of Perl SDL. |
201 | |
202 | =item L<SDL::Tutorial::Animation> |
203 | |
204 | basic animation techniques |
205 | |
206 | =back |
207 | |
208 | =head1 AUTHOR |
209 | |
210 | chromatic, E<lt>chromatic@wgz.orgE<gt> |
211 | |
212 | Written for and maintained by the Perl SDL project, L<http://sdl.perl.org/>. |
213 | |
214 | =head1 BUGS |
215 | |
216 | No known bugs. |
217 | |
218 | =head1 COPYRIGHT |
219 | |
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. |