Commit | Line | Data |
8fde61e3 |
1 | package SDL::Tutorial::Drawing; |
2 | |
3 | use Pod::ToDemo <<'END_HERE'; |
4 | use SDL::App; |
5 | use SDL::Rect; |
6 | use SDL::Color; |
7 | |
8 | # change these values as necessary |
9 | my $title = 'My SDL Rectangle-Drawing App'; |
10 | my ($width, $height, $depth) = ( 640, 480, 16 ); |
11 | my ($red, $green, $blue) = ( 0x00, 0x00, 0xff ); |
12 | my ($rect_width, $rect_height) = ( 100, 100 ); |
13 | my ($rect_x, $rect_y) = ( 270, 190 ); |
14 | |
15 | my $app = SDL::App->new( |
16 | -width => $width, |
17 | -height => $height, |
18 | -depth => $depth, |
19 | ); |
20 | |
21 | my $rect = SDL::Rect->new( |
22 | -height => $rect_height, |
23 | -width => $rect_width, |
24 | -x => $rect_x, |
25 | -y => $rect_y, |
26 | ); |
27 | |
28 | my $color = SDL::Color->new( |
29 | -r => $red, |
30 | -g => $green, |
31 | -b => $blue, |
32 | ); |
33 | |
34 | $app->fill( $rect, $color ); |
35 | $app->update( $rect ); |
36 | |
37 | # your code here; remove the next line |
38 | sleep 2; |
39 | END_HERE |
40 | |
41 | 1; |
42 | __END__ |
43 | |
44 | =head1 NAME |
45 | |
46 | SDL::Tutorial::Drawing - basic drawing with Perl SDL |
47 | |
48 | =head1 SYNOPSIS |
49 | |
50 | # to read this tutorial |
51 | $ perldoc SDL::Tutorial::Drawing |
52 | |
53 | # to create a bare-bones SDL app based on this tutorial |
54 | $ perl -MSDL::Tutorial::Drawing=basic_app.pl -e 1 |
55 | |
56 | =head1 DRAWING BASICS |
57 | |
58 | As explained in L<SDL::Tutorial>, all graphics in SDL live on a surface. |
59 | Consequently, all drawing operations operate on a surface, whether drawing on |
60 | it directly or blitting from another surface. The important modules for this |
61 | exercise are L<SDL::Rect> and L<SDL::Color>. |
62 | |
63 | As usual, we'll start by creating a L<SDL::App> object: |
64 | |
65 | use SDL::App; |
66 | |
67 | my $app = SDL::App->new( |
68 | -width => 640, |
69 | -height => 480, |
70 | -depth => 16, |
71 | ); |
72 | |
73 | =head2 Creating a New Surface with SDL::Rect |
74 | |
75 | A SDL::Rect object is an SDL surface, just as an SDL::App object is. As you'd |
76 | expect, you need to specify the size of this object as you create it. You can |
77 | also specify its coordinates relative to the origin. |
78 | |
79 | B<Note:> The origin, or coordinates 0, 0, is at the upper left of the screen. |
80 | |
81 | Here's how to create a square 100 pixels by 100 pixels centered in the window: |
82 | |
83 | use SDL::Rect; |
84 | |
85 | my $rect = SDL::Rect->new( |
86 | -height => 100, |
87 | -width => 100, |
88 | -x => 270, |
89 | -y => 390, |
90 | ); |
91 | |
92 | This won't actually display anything yet, it just creates a rectangular |
93 | surface. Of course, even if it did display, you wouldn't see anything, as it |
94 | defaults to the background color just as C<$app> does. That's where SDL::Color |
95 | comes in. |
96 | |
97 | =head2 A Bit About Color |
98 | |
99 | SDL::Color objects represent colors in the SDL world. These colors are |
100 | additive, so they're represented as mixtures of Red, Green, and Blue |
101 | components. The color values are traditionally given in hexadecimal numbers. |
102 | If you're exceedingly clever or really like the math, you can figure out which |
103 | values are possible by comparing them to your current bit depth. SDL does a |
104 | lot of autoconversion for you, though, so unless extreme speed or pedantic |
105 | detail are important, you can get by without worrying too much. |
106 | |
107 | Creating a color object is reasonably easy. As the color scheme is additive, |
108 | the lower the number for a color component, the less of that color. The higher |
109 | the number, the higher the component. Experimentation may be your best bet, as |
110 | these aren't exactly the primary colors you learned as a child (since that's a |
111 | subtractive scheme). |
112 | |
113 | Let's create a nice, full blue: |
114 | |
115 | use SDL::Color; |
116 | |
117 | my $color = SDL::Color->new( |
118 | -r => 0x00, |
119 | -g => 0x00, |
120 | -b => 0xff, |
121 | ); |
122 | |
123 | B<Note:> The numbers are in hex; if you've never used hex notation in Perl |
124 | before, the leading C<0x> just signifies that the rest of the number is in |
125 | base-16. In this case, the blue component has a value of 255 and the red and |
126 | green are both zero. |
127 | |
128 | =head2 Filling Part of a Surface |
129 | |
130 | The C<fill()> method of SDL::Surface fills a given rectangular section of the |
131 | surface with the given color. Since we already have a rect and a color, it's |
132 | as easy as saying: |
133 | |
134 | $app->fill( $rect, $color ); |
135 | |
136 | That's a little subtle; it turns out that the SDL::Rect created earlier |
137 | represents a destination within the surface of the main window. It's not |
138 | attached to anything else. We could re-use it later, as necessary. |
139 | |
140 | =head2 Updating the Surface |
141 | |
142 | If you try the code so far, you'll notice that it still doesn't display. Don't |
143 | fret. All that's left to do is to call C<update()> on the appropriate surface. |
144 | As usual, C<update()> takes a Rect to control which part of the surface to |
145 | update. In this case, that's: |
146 | |
147 | $app->update( $rect ); |
148 | |
149 | This may seem like a useless extra step, but it can be quite handy. While |
150 | drawing to the screen directly seems like the fastest way to go, the |
151 | intricacies of working with hardware with the appropriate timings is tricky. |
152 | |
153 | =head2 Working With The App |
154 | |
155 | You can, of course, create all sorts of Rects with different sizes and |
156 | coordinates as well as varied colors and experiment to your heart's content |
157 | drawing them to the window. It's more fun when you can animate them smoothly, |
158 | though. |
159 | |
160 | That, as usual, is another tutorial. |
161 | |
162 | =head1 SEE ALSO |
163 | |
164 | =over 4 |
165 | |
166 | =item L<SDL::Tutorial> |
167 | |
168 | the basics of Perl SDL. |
169 | |
170 | =item L<SDL::Tutorial::Animation> |
171 | |
172 | basic animation techniques |
173 | |
174 | =back |
175 | |
176 | =head1 AUTHOR |
177 | |
178 | chromatic, E<lt>chromatic@wgz.orgE<gt> |
179 | |
180 | Written for and maintained by the Perl SDL project, L<http://sdl.perl.org/>. |
181 | |
182 | =head1 BUGS |
183 | |
184 | No known bugs. |
185 | |
186 | =head1 COPYRIGHT |
187 | |
188 | Copyright (c) 2003 - 2004, chromatic. All rights reserved. This module is |
189 | distributed under the same terms as Perl itself, in the hope that it is useful |
190 | but certainly under no guarantee. |