lib/SDL/Tutorial/Drawing.pm

   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.