lib/SDL/Tutorial/.svn/text-base/Drawing.pm.svn-base

   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.