NAME ^

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

SYNOPSIS ^

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

        # create a new SDL::Surface object
        find_type surface_type, 'SDL::Surface'
        surface = new surface_type
        surface.'init'( 'height' => 480, 'width' => 640 )

        # ... 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:

init( surface_args )

Given a list of key-value pairs, the attributes of this surface. The valid keys are height and width, two integer values representing the height and width of this surface in pixels. Other keys are depth, the screen depth, flags, the SDL flags, and r, g, b, and a, representing the bit depth of each component.

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.

pixels()

Return the raw pixels array of the surface. It can be filled with raw colors like this:

  .local pmc surface, pixels
  .local int offset, x, y, raw_color
  pixels  = surface.'pixels'()
  offset  = surface.'width'()
  ...
  $I0 = offset * y
  $I0 .= x
  pixels[0; $I0] = raw_color       # pixels['array'; $O] = raw_color
Please note that the function returns an UnManagedStruct pointing to an array, therefore the double indexing is needed.

See also draw_pixels() above for locking/unlocking the surface and how to fetch raw colors.

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, 2006 The Perl Foundation.


 parrot