lib/SDL/Tutorial/Drawing.pm

   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 warnings;
  35
  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;
  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.