Back to index



Class Methods

 new  load_new  to_surface  shared_new

Instance Methods

 share  immodest_export  destroy  blit  convert  convert_alpha  convert!  convert_alpha!  lock  must_lock  unlock  locked?  save_bmp  w  h  size  rect  colorkey  unset_colorkey  set_colorkey  fill  pitch  bitsize  bytesize  flags  losses  shifts  masks  palette  set_palette  alpha  unset_alpha  set_alpha  clip  unset_clip  clip=  contained_images  get  []  rows  get_row  set_row  each_row { |.. }  each_row! { |.. }  columns  get_column  set_column  each_column { |.. }  each_column! { |.. }  pixels  pixels=


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.

Class Methods size ) size, surface ) size, flags ) size, flags, surface ) size, flags, depth ) size, flags, depth, masks )

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, quoted from SDL's documentation:

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)







Normally this shouldn't have to be of interest.

Surface.load_new( filename )

This creates a Surface with an image in it, loaded from disk from filename by using load_new or loaded by treating String as the image data when using to_surface. In the last case, the string should be in some supported format, just like the file for load_new should be. 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.

Surface.shared_new( 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!

Instance Methods

Surface#share( other_surface )

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

Returns self.

Surface#immodest_export( other_surface )

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

Returns self.


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

Returns nil.

Surface#blit( source, coordinate )
Surface#blit( source, coordinate, sourceRect )

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 Surface that was changed.


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.

Returns the converted surface.


Like convert and convert_alpha, but these change the surface itself.

Returns self.


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 Surfaces locked for as short a time as possible.

Surface#save_bmp( filename )

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. It returns self.


These methods return the size of the surface. w returns width, h returns height, size returns [w, h] and rect returns an array of [0, 0, w, h].

Surface#set_colorkey( color )
Surface#set_colorkey( color, flags )

These methods control the color that will be completely transparent (it will not be copied to the destination surface.) The only flag is "RLEACCEL" which will encode the bitmap in a more efficient way for blitting, by skipping the transparent pixels.

colorkey returns the current colorkey color. The others return self;

Surface#fill( color )
Surface#fill( color, rect )

Fills rectangle rect in the surface with color.

Returns self.


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


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.


Returns the number of bytes used to store each pixel.


Returns the current state flags for the surface.


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)

Returns an array of [redloss, greenloss, blueloss, alphaloss]


Returns the bitshifts [redshift, greenshift, blueshift, alphashift] used for each color plane. The shift is determine how many bits left-shifted a colorplane value is in a mapped color value.


Returns the bitmasks [redmask, greenmask, bluemask, alphamask] 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)

Surface#set_palette( first, colors )

These methods return or set the 256 color palette that is part of 8 bit Surfaces. 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]]

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

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.

Surface#clip=( rect )

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


Returns an array of surfaces that are found by parsing this surface in a certain way. An example is in the samples directory, in crapola.rbw. This is not part of SDL, it is RUDL-specific.

Surface#get( coordinate )
Surface#[ x, y ]

These methods read single pixels on a surface. get or [] get the color of a pixel. These methods require the surface to be locked if neccesary. []= and [] are the only methods in RUDL that take a seperate x and y coordinate.

Surface#get_row( y )
Surface#set_row( y, pixels )
Surface#each_row { |row_of_pixels| ... }
Surface#each_row! { |row_of_pixels| ... }

These methods manipulate rows of pixels. Surface#rows returns an array of strings with one row of imagedata each. get_row and set_row get and set a single such row. each_row and each_row! iterate through the rows, passing each of them to the supplied codeblock. For more info, see Surface#pixels.

Surface#get_column( x )
Surface#set_column( x, pixels )
Surface#each_column { |column_of_pixels| ... }
Surface#each_column! { |column_of_pixels| ... }

These methods manipulate columns of pixels. Surface#columns returns an array of strings with one column of imagedata each. get_column and set_column get and set a single such column. each_column and each_column! iterate through the columns, passing each of them to the supplied codeblock. For more info, see Surface#pixels.

Surface#pixels=( pixeldata )

These methods get and set all image data at once. 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.

Back to index