# Surface

A Surface is a two dimensional array of pixels with some information about those pixels. This might not seem like much, but it is just about the most important class in RUDL.

## Alpha methods

Gets or sets the overall transparency for the Surface. An alpha of 0 is fully transparent, an alpha of 255 is fully opaque. If your surface has a pixel alpha channel, it will override the overall surface transparency. You'll need to change the actual pixel transparency to make changes. If your image also has pixel alpha values and will be used repeatedly, you will probably want to pass the `RLEACCEL` flag to the call. This will take a short time to compile your surface, and increase the blitting speed. Note that the per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.

#### alpha

#### set_alpha( alpha )
set_alpha( alpha, flags )

set_alpha(nil) removes the per-surface alpha, same as unset_alpha.

#### unset_alpha

## Batch pixel access

These methods manipulate the pixels in the Surface. The transport medium is a string with binary data in it. The data is raw, no fancy color arrays here. If bytesize (the amount of bytes used to describe the color of a pixel) is four, for example, a (({Surface})) of 5x5 pixels will return a string of length (5x5x4). If the colorformat is specified as BGRA, then character zero will be the B component, character one the G component etc. Eight bit color surfaces store one byte indexes into the palette. These methods perform best when the surface's pitch is equal to its width. There is not much errorchecking so beware of crashes.

#### columns

Returns an array of strings with one column of imagedata each.

#### each_column { |column_of_pixels| ... }
each_column! { |column_of_pixels| ... }

each_column and each_column! iterate through the columns, passing each of them to the supplied codeblock.

#### each_row { |row_of_pixels| ... }
each_row! { |row_of_pixels| ... }

each_row and each_row! iterate through the rows, passing each of them to the supplied codeblock.

#### get_column( x )

Get a column.

#### get_row( y )

Get a single row.

#### pixels
pixels=( pixeldata )

These methods get and set all image data at once.

#### rows

Returns an array of strings with one row of imagedata each.

#### set_column( x, pixels )

Set a column

#### set_row( y, pixels )

Set a single row.

## Clipping

#### clip
clip=( rect )

Retrieves, removes or sets the clipping rectangle for surfaces that are blitted to this surface.

#### unset_clip

## Colorkey methods

These methods control the color that will be completely transparent (it will not be copied to the destination surface.)

#### colorkey → Array[R,G,B]

#### set_colorkey( color ) → self
set_colorkey( color, flags ) → self

The only flag for flags is `RLEACCEL` which will encode the bitmap in a more efficient way for blitting, by skipping the transparent pixels. set_colorkey(nil) removes the color key, same as unset_colorkey .

#### unset_colorkey → self

## Drawing

Many of the methods here are from SDL_gfx. They were written by Andreas Schiffler. For these methods, "antialiased" means that drawing is done with many shades of the requested color to simulate

#### [ x, y ]= color → self
[ coordinate ]= color → self
[ x, y ]
[ coordinate ]

These methods access single pixels on a surface. plot or []= set the color of a pixel. The coordinate can be given as an [x,y] array or two separate numbers. plot is an alias for []=. These methods require the surface to be locked if necessary. []= and [] are the only methods in RUDL that take separate x and y coordinates. See also: Surface.get, Surface.[] See get

#### fill( color ) → self
fill( color, rect ) → self

Fills rectangle rect in the surface with color.

#### get( x, y )
get( coordinate )

These methods read single pixels on a surface. get or [] get the color of a pixel. The coordinate can be given as an [x,y] array or two separate numbers. get is an alias for []. These methods require the surface to be locked if necessary. []= and [] are the only methods in RUDL that take separate x and y coordinates. See also: Surface.plot, Surface.[]=

#### plot( x, y, color ) → self
plot( coordinate, color ) → self

#### print( coord, text, color ) → self

Puts text on the surface in a monospaced 8x8 standard old ASCII font.

## Drawing: Circles

#### antialiased_circle( coord, radius, color ) → self

#### antialiased_ellipse( coord, radius_x, radius_y, color ) → self

#### circle( coord, radius, color ) → self

#### ellipse( coord, radius_x, radius_y, color ) → self

#### filled_circle( coord, radius, color ) → self

#### filled_ellipse( coord, radius_x, radius_y, color ) → self

#### filled_pie( coord, radius, start, end, color ) → self

## Drawing: Polygons

The polygon methods take an array of [x,y], like [[10,10],[40,60],[16,66]].

#### antialiased_polygon( coord_list, color) → self

#### filled_polygon( coord_list, color ) → self

#### polygon( coord_list, color ) → self

## Drawing: Straight stuff

#### antialiased_line( coord1, coord2, color ) → self

#### filled_rectangle( rect, color ) → self

Filled_rectangle is a lot like fill. Fill comes from SDL, filled_rectangle from SDL_gfx, choose whichever you like best.

#### horizontal_line( coord, endx, color ) → self

#### line( coord1, coord2, color )

#### rectangle( rect, color ) → self

#### vertical_line( coord, endy, color ) → self

## Information

#### bitsize

Returns the number of bits used to represent each pixel. This value may not exactly fill the number of bytes used per pixel. For example a 15 bit Surface still requires a full 2 bytes.

#### bytesize

Returns the number of bytes used to store each pixel.

#### flags

Returns the current state flags for the surface.

#### losses → Array[redloss, greenloss, blueloss, alphaloss]

Returns the bitloss for each color plane. The loss is the number of bits removed for each colorplane from a full 8 bits of resolution. A value of 8 usually indicates that colorplane is not used (like the alpha plane)

#### masks → Array[redmask, greenmask, bluemask, alphamask]

Returns the bitmasks for each color plane. The bitmask is used to isolate each colorplane value from a mapped color value. A value of zero means that colorplane is not used (like alpha)

#### pitch

The surface pitch is the number of bytes used in each scanline. This function should rarely needed, mainly for any special-case debugging.

#### shifts → Array[redshift, greenshift, blueshift, alphashift]

Returns the bitshifts used for each color plane. The shift is determine how many bits left-shifted a colorplane value is in a mapped color value.

## Initializers

#### load_new( filename ) → Surface

This creates a Surface with an image in it, loaded from disk from filename by using load_new. The file should be in a supported file format. If the SDL_image library was found during RUDL's installation, it will load the following formats: BMP, PNM, XPM, XCF, PCX, GIF, JPEG, TIFF, PNG, TGA and LBM. If the SDL_image library was not found, only simple BMP loading is supported. Simple means: not all BMP files can be loaded.

#### new( size ) → Surface
new( size, surface ) → Surface
new( size, flags ) → Surface
new( size, flags, surface ) → Surface
new( size, flags, depth ) → Surface
new( size, flags, depth, masks ) → Surface

All these methods create a new Surface with size = [w, h]. If only size is supplied, the rest of the arguments will be set to reasonable values. If a surface is supplied, it is used to copy the values from that aren't given.

flags is, according to SDL's documentation:

- SWSURFACE: SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.
- HWSURFACE: SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video->Video blits (which are often accelerated).
- SRCCOLORKEY: This flag turns on colourkeying for blits from this surface. If HWSURFACE is also specified and colourkeyed blits are hardware-accelerated, then SDL will attempt to place the surface in video memory. Use Surface#set_colorkey to set or clear this flag after surface creation.
- SRCALPHA: This flag turns on alpha-blending for blits from this surface. If HWSURFACE is also specified and alpha-blending blits are hardware-accelerated, then the surface will be placed in video memory if possible. Use Surface#set_alpha to set or clear this flag after surface creation. For a 32 bitdepth surface, an alpha mask will automatically be added, in other cases, you will have to specify a mask.

depth is bitdepth, like 8, 15, 16, 24 or 32.

masks describes the format for the pixels and is an array of [R, G, B, A] containing 32 bit values with bits set where the colorcomponent should be stored. For example: [0xFF000000, 0x00FF0000, 0x0000FF00, 0x000000FF] describes a 32 bit color with red in the highest values and an alpha channel. If it is not specified, the following defaults are used:

    ........ ........ ........ .RRGGGBB (8bpp)
    ........ ........ ....RRRR GGGGBBBB (12bpp)
    ........ ........ .RRRRRGG GGGBBBBB (15bpp)
    ........ ........ RRRRRGGG GGGBBBBB (16bpp)
    ........ RRRRRRRR GGGGGGGG BBBBBBBB (24 bpp)
    ........ RRRRRRRR GGGGGGGG BBBBBBBB (32 bpp)
    RRRRRRRR GGGGGGGG BBBBBBBB AAAAAAAA (32 bpp, SRCALPHA set)

Normally this shouldn't have to be of interest.

#### shared_new( surface ) → Surface

This method is two things:

1. a way to share the same bunch of data (width, height, bpp, pixeldata) between two Surface objects. Please don't use it this way if there isn't a very good reason for it.
2. a way to import foreign objects that wrap an SDL_Surface*. If that doesn't mean anything to you, please ignore this point. It takes the pointer from the foreign object and creates a new Surface that wraps it.

Garbage collection problems should be prevented by giving the new surface a reference to surface

Note that if the original surface is destroyed by a call to Surface.destroy, the shared ones will be invalidated too!

#### String.to_surface → Surface

This creates a Surface with an image in it, loaded by treating String as the image data when using to_surface. The string should be in a supported file format, just like the file for load_new should be.

## Locking

These methods control the locking of surfaces. If you ever encounter a locking error, you might try these out. Locking errors are expected when trying to access video hardware. Keep a Surface locked for as short a time as possible.

#### lock → self

Locks the surface.

#### locked? → boolean

Returns true when the surface is locked.

#### must_lock → boolean

Returns true when a surface needs locking for pixel access.

#### unlock → self

Unlocks a surface that was locked with lock and returns self.

## Methods

#### blit( source, coordinate ) → Array
blit( source, coordinate, sourceRect ) → Array

This method blits (copies, pastes, draws) source onto the surface it is called on. coordinate is the position [x, y] where source will end up in the destination surface. sourcerect is the area in the source bitmap that you want blitted. Not supplying it will blit the whole source.

Returns the rectangle array ([x,y,w,h]) in the surface that was changed.

#### convert → Surface
convert! → self

Creates a new version of the surface in the current display's format, making it faster to blit.

#### convert_alpha → Surface
convert_alpha! → self

Like convert, creates a new version of the surface in the current display's format, making it faster to blit. The alpha version optimizes for fast alpha blitting.

#### destroy → nil

Frees memory used by this surface. The surface is no longer useable after this call.

#### immodest_export( other_surface ) → self

Like Surface.share, but this works the other way around. It will destroy the other_surface then make it share the data in itself and setting a reference on other_surface back to self. It's called immodest because it interferes with another object, bluntly assuming it contains a SDL_Surface pointer and changing it to something else...

#### save_bmp( filename ) → self

This is the only method in RUDL which stores surface data. Pass save_bmp the filename and the surface data will be saved to that file.

#### share( other_surface ) → self

Like Surface.shared_new, but this works on an existing surface. It will destroy this surface, then make it share other_surface 's data.

## Palette manipulation

#### palette → Array[[R,G,B], [R,G,B],....]

#### set_palette( first, colors ) → self

These methods return or set the 256 color palette that is part of 8 bit Surface s. first is the first color to change. colors and the return value of palette are arrays of colors like [[50,80,120], [255,255,0]] =end

## Scaling, Flipping and Rotating

#### mirror_x → Surface

Mirrors the surface horizontally into a new Surface.

#### mirror_y → Surface

Mirrors the surface vertically into a new Surface.

#### rotozoom( angle, zoom, smooth ) → Surface

Returns a new surface that is rotated angle degrees and zoomed zoom times (fractions are OK). This method returns a 32 bit surface. Exception: for now it returns an 8 bit surface when fed an 8 bit surface. If smooth is true and the surface is not 8 bits, bilinear interpolation will be applied, resulting in a smoother image.

#### scale2x → Surface
scale2x( dest_surface ) → Surface
scale2x( dest_surface, coordinate ) → Surface

Scales the surface to double size with the Scale2x algorithm developed by Andrea Mazzoleni. See the project page.

Creates a new surface to hold the result, or reuses dest_surface, which must be at least twice as wide and twice as high as this surface, and have the same depth.

coordinate is the [x, y] coordinate where you want the scaled image positioned. This way you can draw it directly on screen at the wanted position, without having to use a temporary Surface.

#### zoom( zoom_horizontal, zoom_vertical, smooth ) → Surface

Returns a new surface that is zoomed. 1.0 doesn't zoom, bigger than 1.0 zooms in, smaller than 1.0 zooms out. This method returns a 32 bit surface. Exception: for now it returns an 8 bit surface when fed an 8 bit surface. If smooth is true and the surface is not 8 bits, bilinear interpolation will be applied, resulting in a smoother image. (The last two methods are from Andreas Schiffler's SDL_rotozoom, aschiffler@home.com)

## Size methods

These methods return the size of the surface.

#### h → Number

Returns height in pixels.

#### rect → Array[0, 0, w, h]

#### size → Array[w,h]

#### w → Number

Returns width in pixels.