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