sdl::tutorial(3) [suse man page]

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

NAME

       SDL::Tutorial - introduction to Perl SDL

SYNOPSIS

	       # to read this tutorial
	       $ perldoc SDL::Tutorial

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

SDL BASICS

       SDL, the Simple DirectMedia Layer, is a cross-platform multimedia library.  These are the Perl 5 bindings.  You can find out more about SDL
       at <http://www.libsdl.org/>.

       Creating an SDL application with Perl is easy.  You have to know a few basics, though.  Here's how to get up and running as quickly as
       possible.

   Surfaces
       All graphics in SDL live on a surface.  You'll need at least one.  That's what SDL::App provides.

       Of course, before you can get a surface, you need to initialize your video mode.  SDL gives you several options, including whether to run
       in a window or take over the full screen, the size of the window, the bit depth of your colors, and whether to use hardware acceleration.
       For now, we'll build something really simple.

   Initialization
       SDL::App makes it easy to initialize video and create a surface.  Here's how to ask for a windowed surface with 640x480x16 resolution:

	       use SDL::App;

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

       You can get more creative, especially if you use the "-title" and "-icon" attributes in a windowed application.	Here's how to set the
       window title of the application to "My SDL Program":

	       use SDL::App;

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

       Setting an icon is a little more involved -- you have to load an image onto a surface.  That's a bit more complicated, but see the "-name"
       parameter to "SDL::Surface-"new()> if you want to skip ahead.

   Working With The App
       Since $app from the code above is just an SDL surface with some extra sugar, it behaves much like SDL::Surface.	In particular, the all-
       important "blit" and "update" methods work.  You'll need to create SDL::Rect objects representing sources of graphics to draw onto the
       $app's surface, "blit" them there, then "update" the $app.

       Note:  "blitting" is copying a chunk of memory from one place to another.

       That, however, is another tutorial.

SEE ALSO

       SDL::Tutorial::Drawing
	   basic drawing with rectangles

       SDL::Tutorial::Animation
	   basic rectangle animation

       SDL::Tutorial::Images
	   image loading and animation

AUTHOR

       chromatic, <chromatic@wgz.org>.

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

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(3)

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)