SDL::Tutorial::Drawing(3)				User Contributed Perl Documentation				 SDL::Tutorial::Drawing(3)

NAME

       SDL::Tutorial::Drawing - basic drawing with Perl SDL

SYNOPSIS

	       # to read this tutorial
	       $ perldoc SDL::Tutorial::Drawing

	       # to create a bare-bones SDL app based on this tutorial
	       $ perl -MSDL::Tutorial::Drawing=basic_app.pl -e 1

DRAWING BASICS

       As explained in SDL::Tutorial, all graphics in SDL live on a surface.  Consequently, all drawing operations operate on a surface, whether
       drawing on it directly or blitting from another surface.  The important modules for this exercise are SDL::Rect and SDL::Color.

       As usual, we'll start by creating a SDL::App object:

	       use SDL::App;

	       my $app = SDL::App->new(
		       -width  => 640,
		       -height => 480,
		       -depth  => 16,
	       );

   Creating a New Surface with SDL::Rect
       A SDL::Rect object is an SDL surface, just as an SDL::App object is.  As you'd expect, you need to specify the size of this object as you
       create it.  You can also specify its coordinates relative to the origin.

       Note:  The origin, or coordinates 0, 0, is at the upper left of the screen.

       Here's how to create a square 100 pixels by 100 pixels centered in the window:

	       use SDL::Rect;

	       my $rect = SDL::Rect->new(
		       -height => 100,
		       -width  => 100,
		       -x      => 270,
		       -y      => 390,
	       );

       This won't actually display anything yet, it just creates a rectangular surface.  Of course, even if it did display, you wouldn't see
       anything, as it defaults to the background color just as $app does.  That's where SDL::Color comes in.

   A Bit About Color
       SDL::Color objects represent colors in the SDL world.  These colors are additive, so they're represented as mixtures of Red, Green, and
       Blue components.  The color values are traditionally given in hexadecimal numbers.  If you're exceedingly clever or really like the math,
       you can figure out which values are possible by comparing them to your current bit depth.  SDL does a lot of autoconversion for you,
       though, so unless extreme speed or pedantic detail are important, you can get by without worrying too much.

       Creating a color object is reasonably easy.  As the color scheme is additive, the lower the number for a color component, the less of that
       color.  The higher the number, the higher the component.  Experimentation may be your best bet, as these aren't exactly the primary colors
       you learned as a child (since that's a subtractive scheme).

       Let's create a nice, full blue:

	       use SDL::Color;

	       my $color = SDL::Color->new(
		       -r => 0x00,
		       -g => 0x00,
		       -b => 0xff,
	       );

       Note:  The numbers are in hex; if you've never used hex notation in Perl before, the leading "0x" just signifies that the rest of the
       number is in base-16.  In this case, the blue component has a value of 255 and the red and green are both zero.

   Filling Part of a Surface
       The "fill()" method of SDL::Surface fills a given rectangular section of the surface with the given color.  Since we already have a rect
       and a color, it's as easy as saying:

	       $app->fill( $rect, $color );

       That's a little subtle; it turns out that the SDL::Rect created earlier represents a destination within the surface of the main window.
       It's not attached to anything else.  We could re-use it later, as necessary.

   Updating the Surface
       If you try the code so far, you'll notice that it still doesn't display.  Don't fret.  All that's left to do is to call "update()" on the
       appropriate surface.  As usual, "update()" takes a Rect to control which part of the surface to update.	In this case, that's:

	       $app->update( $rect );

       This may seem like a useless extra step, but it can be quite handy.  While drawing to the screen directly seems like the fastest way to go,
       the intricacies of working with hardware with the appropriate timings is tricky.

   Working With The App
       You can, of course, create all sorts of Rects with different sizes and coordinates as well as varied colors and experiment to your heart's
       content drawing them to the window.  It's more fun when you can animate them smoothly, though.

       That, as usual, is another tutorial.

SEE ALSO

       SDL::Tutorial
	   the basics of Perl SDL.

       SDL::Tutorial::Animation
	   basic animation techniques

AUTHOR

       chromatic, <chromatic@wgz.org>

       Written for and maintained by the Perl SDL project, <http://sdl.perl.org/>.

BUGS

       No known bugs.

COPYRIGHT

       Copyright (c) 2003 - 2004, chromatic.  All rights reserved.  This module is distributed under the same terms as Perl itself, in the hope
       that it is useful but certainly under no guarantee.

perl v5.12.1							    2010-07-05						 SDL::Tutorial::Drawing(3)