/ 
SDL_Perl-v2.2.3
River stage zero No dependents
/ SDL::Tutorial::Drawing

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.