NAME

SDL::Surface - Parrot class representing surfaces in Parrot SDL

SYNOPSIS

        # load this library
        load_bytecode 'library/SDL/Surface.pir'

        # set the surface's arguments
        .local pmc surface_args
        surface_args             = new PerlHash
        surface_args[ 'height' ] = 480
        surface_args[ 'width'  ] = 640

        # create a new SDL::Surface object
        .local pmc surface
        .local int surface_type

        find_type surface_type, 'SDL::Surface'
        surface = new surface_type, surface_args

        # ... blit to, fill, update, and flip this surface as necessary

DESCRIPTION

A SDL::Surface object represents a surface in SDL. All drawing operations draw to a surface (and most draw from a surface). You'll likely not instantiate this class directly, but all SDL::Image and SDL::Sprite objects operate on objects of this class, and you'll receive an SDL::Surface from the SDL::App constructor.

METHODS

All SDL::Surface objects have the following methods:

_new( surface_args )

Given a PerlHash of arguments, set the attributes of this surface. The keys of this hash are height and width, two integer values representing the height and width of this surface in pixels.

The name of this method may change, per discussion on p6i.

new_from_surface( raw_surface )

Given a raw_surface object, sometimes returned from raw SDL functions, create and return a new SDL::Surface object.

I'm not sure I like the name of this method. It may change. That may be okay; you have little reason to use it directly.

height()

Returns the height of this surface, in pixels. This is always an integer value.

width()

Returns the width of this surface, in pixels. This is always an integer value.

fill_rect( rect, color )

Given an SDL::Rect representing a portion of this surface and an SDL::Color representing a color, fills a portion of this surface with the given color.

update_rect( rect )

If this is a single-buffered surface (unless you've explicitly requested double buffering when intializing your SDL::App), updates the portion of this surface represented by the SDL::Rect.

Do this on the main surface to see your changes.

update_rects( array_of_rects )

Updates multiple areas represented by SDL::Rect objects within this surface all at once. Pass in an Array of rects to update.

flip()

Given a double-buffered surface (if you've explicitly enabled double-buffering when creating your SDL::App), flips the back buffer (to which you draw, in that case) to the main buffer, so you can see it.

blit( source_surface, source_rect, destination_rect )

Given a SDL::Surface to use as a source, a SDL::Rect representing the source within the source surface, and a SDL::Rect representing the destination within the current surface to which to draw, copies the appropriate region from the source to this surface.

That's a terrible sentence, but after you try it once or twice, you'll understand.

surface()

Returns the underlying surface this object represents. You should never need to use this directly.

color_key( color )

Sets the transparent pixel value for the surface. This signature may change, if I add flag options.

bpp()

Returns the bitdepth of the current surface.

lock()

Locks the surface for raw pixel drawing. Call this before calling draw_pixel() or any other pixel operation. Be careful what else you do while you hold the lock.

unlock()

Unlocks the surface after you've finished raw pixel operations.

draw_pixel( x, y, color )

Draws a pixel at the position represented by integers x and y with the given SDL::Color color.

If you want as much speed as possible, call color_for_surface on the SDL::Color and pass in the value you receive instead. This method will not have to perform a time-consuming conversion. This is a classic tradeoff between memory and speed. Happily, colors are (reasonably cheap) integers at heart.

convert_red()

A helper method to convert the red component of any color to work with this surface.

convert_green()

A helper method to convert the green component of any color to work with this surface.

convert_blue()

A helper method to convert the blue component of any color to work with this surface.

AUTHOR

Written and maintained by chromatic, <chromatic at wgz dot org>, with suggestions from Jens Rieks. Please send patches, feedback, and suggestions to the Perl 6 Internals mailing list.

COPYRIGHT

Copyright (c) 2004, The Perl Foundation.