Class | Rubygame::Surface
In: | lib/rubygame/surface.rb lib/rubygame/image.rb lib/rubygame/gfx.rb
Parent: | Object

Surface represents an image, a block of colored pixels arranged in a 2D grid. You can load image files to a new Surface with load, or create an empty one with Surface.new and draw shapes on it with draw_line, draw_circle, and all the rest.

One of the most important Surface concepts is blit, copying image data from one Surface onto another. By blitting Surfaces onto the Screen (which is a special type of Surface) and then using Screen#update, you can make images appear for the player to see.

As of Rubygame 2.3.0, Surface includes the Rubygame::NamedResource mixin module, which can perform autoloading of images on demand, among other things.

### Methods

alpha alpha= autoload blit clip clip= colorkey colorkey= convert depth draw_arc draw_arc_s draw_box draw_box_s draw_circle draw_circle_a draw_circle_s draw_ellipse draw_ellipse_a draw_ellipse_s draw_line draw_line_a draw_polygon draw_polygon_a draw_polygon_s fill flags flip get_at h height inspect load load_from_string load_image make_rect masks new pixels rotozoom rotozoom_size savebmp set_alpha set_at set_colorkey size to_display to_display_alpha to_s w width zoom zoom_size zoom_to

### Included Modules

Rubygame::NamedResource

### Public Class methods

autoload( name )

Searches each directory in Surface.autoload_dirs for a file with the given filename. If it finds that file, loads it and returns a Surface instance. If it doesn‘t find the file, returns nil.

See Rubygame::NamedResource for more information about this functionality.

load( filename )

IMPORTANT: this method only exists if SDL_image is available! Your code should check "defined?(Rubygame::Surface.load) != nil" to see if you can use this method, or be prepared to rescue from NameError.

Load an image file from the disk to a Surface. If the image has an alpha channel (e.g. PNG with transparency), the Surface will as well. If the image cannot be loaded (for example if the image format is unsupported), will raise SDLError.

This method takes this argument:

filename: | a string containing the relative or absolute path to the image file. The file must have the proper file extension, as it is used to determine image format.

These formats may be supported, but some may not be available on a particular system.

BMP: | "Windows Bitmap" format.
GIF: | "Graphics Interchange Format."
JPG: | "Independent JPEG Group" format.
LBM: | "Linear Bitmap" format (?)
PCX: | "PC Paintbrush" format
PNG: | "Portable Network Graphics" format.
PNM: | "Portable Any Map" format. (i.e., PPM, PGM, or PBM)
TGA: | "Truevision TARGA" format.
TIF: | "Tagged Image File Format"
XCF: | "eXperimental Computing Facility" (GIMP native format).
XPM: | "XPixMap" format.

load_from_string( data, type=nil )

IMPORTANT: this method only exists if SDL_image is available! Your code should check "defined?(Rubygame::Surface.load_from_string) != nil" to see if you can use this method, or be prepared to rescue from NameError.

Load an image file from memory (in the form of the given data) to a Surface. If the image has an alpha channel (e.g. PNG with transparency), the Surface will as well. If the image cannot be loaded (for example if the image format is unsupported), will raise SDLError.

This method takes these arguments:

data: | a string containing the data for the image, such as IO::read would return.
type: | The type of file that the image is (i.e. ‘TGA’). Case is not important. If absent, the library will try to automatically detect the type.

See Surface.load for a list of possible supported file types.

load_image( filename )

Deprecated. Use Surface.load instead!

new( size, depth=0, flags=[] )

Create and initialize a new Surface object.

A Surface is a grid of image data which you blit (i.e. copy) onto other Surfaces. Since the Rubygame display is also a Surface (see the Screen class), Surfaces can be blit to the screen; this is the most common way to display images on the screen.

This method may raise SDLError if the SDL video subsystem could not be initialized for some reason.

This function takes these arguments:

size: | requested surface size; an array of the form [width, height].
depth: | requested color depth (in bits per pixel). If depth is 0 (default), automatically choose a color depth: either the depth of the Screen mode (if one has been set), or the greatest color depth available on the system.
flags: | an Array or Bitwise-OR‘d list of zero or more of the following flags (located in the Rubygame module, e.g. Rubygame::SWSURFACE). This argument may be omitted, in which case the Surface will be a normal software surface (this is not necessarily a bad thing).
SWSURFACE: | (default) request a software surface.
HWSURFACE: | request a hardware-accelerated surface (using a graphics card), if available. Creates a software surface if hardware surfaces are not available.
SRCCOLORKEY: | request a colorkeyed surface. set_colorkey will also enable colorkey as needed. For a description of colorkeys, see set_colorkey.
SRCALPHA: | request an alpha channel. set_alpha will also enable alpha. as needed. For a description of alpha, see alpha.

rotozoom_size( size, angle, zoom )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:rotozoom_size)" to see if you can use this method, or be prepared to rescue from NameError.

Return the dimensions of the surface that would be returned if rotozoom were called on a Surface of the given size, with the same angle and zoom factors.

This method takes these arguments:

size: | an Array with the hypothetical Surface width and height (pixels)
angle: | degrees to rotate counter-clockwise (negative for clockwise).
zoom: | scaling factor(s). A number (to scale X and Y by the same factor) or an array of 2 numbers (to scale X and Y by different factors). NOTE: Due to a quirk in SDL_gfx, if angle is not 0, the image is zoomed by the X factor on both X and Y, and the Y factor is only used for flipping (if it‘s negative).

zoom_size( size, zoom )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:zoom_size)" to see if you can use this method, or be prepared to rescue from NameError.

Return the dimensions of the surface that would be returned if zoom were called on a Surface of the given size, with the same zoom factors.

This method takes these arguments:

size: | an Array with the hypothetical Surface width and height (pixels)
zoom: | scaling factor(s). A number (to scale X and Y by the same factor) or an array of 2 numbers (to scale X and Y by different factors).

### Public Instance methods

alpha()

Return the per-surface alpha (opacity; non-transparency) of the surface. It can range from 0 (full transparent) to 255 (full opaque).

alpha=( alpha, flags=Rubygame::SRCALPHA )

Alias for set_alpha

blit( target, pos, src_rect=nil )

Blit (copy) all or part of the surface‘s image to another surface, at a given position. Returns a Rect representing the area of `target` which was affected by the blit.

This method takes these arguments:

target: | the target Surface on which to paste the image.
pos: | the coordinates of the top-left corner of the blit. Affects the area of `target` the image data is /pasted/ over. Can also be a Rect or an Array larger than 2, but width and height will be ignored.
src_rect: | a Rect representing the area of the source surface to get data from. Affects where the image data is /copied/ from. Can also be an Array of no less than 4 values.

clip()

Return the clipping area for this Surface. See also clip=.

The clipping area of a Surface is the only part which can be drawn upon by other Surface‘s blits. By default, the clipping area is the entire area of the Surface.

clip=( newclip )

Set the current clipping area of the Surface. See also clip.

The clipping area of a Surface is the only part which can be drawn upon by other Surface‘s blits. The clipping area will be clipped to the edges of the surface so that the clipping area for a Surface can never fall outside the edges of the Surface.

By default, the clipping area is the entire area of the Surface. You may set clip to `nil`, which will reset the clipping area to cover the entire Surface.

colorkey → [r,g,b] or nil

Return the colorkey of the surface in the form [r,g,b] (or `nil` if there is no key). The colorkey of a surface is the exact color which will be ignored when the surface is blitted, effectively turning that color transparent. This is often used to make a blue (for example) background on an image seem transparent.

colorkey=( color, flags=Rubygame::SRCCOLORKEY )

Alias for set_colorkey

convert( other=nil, flags=nil )

Copies the Surface to a new Surface with the pixel format of another Surface, for fast blitting. May raise SDLError if a problem occurs.

This method takes these arguments:

other: | The Surface to match pixel format against. If `nil`, the display surface (i.e. Screen) is used, if available; if no display surface is available, raises SDLError.
flags: | An array of flags to pass when the new Surface is created. See Surface#new.

depth()

Return the color depth (in bits per pixel) of the surface.

draw_arc( center, radius, angles, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_arc)" to see if you can use this method, or be prepared to rescue from NameError.

Draw a non-solid arc (part of a circle), given the coordinates of its center, radius, and starting/ending angles. See also draw_arc_s

This method takes these arguments:

center: | the coordinates of circle‘s center, [x,y].
radius: | the radius (pixels) of the circle.
angles: | the start and end angles (in degrees) of the arc, [start,end]. Angles are given CLOCKWISE from the positive x (remember that the positive Y direction is down, rather than up).
color: | the color of the shape. [r,g,b] or [r,g,b,a] (0-255), color name, or Rubygame::Color.

draw_arc_s( center, radius, angles, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_arc_s)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_arc, but the shape is solid, instead of an outline.

draw_box( point1, point2, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_box)" to see if you can use this method, or be prepared to rescue from NameError.

Draw a non-solid box (rectangle) on the Surface, given the coordinates of its top-left corner and bottom-right corner. See also draw_box_s

This method takes these arguments:

point1: | the coordinates of top-left corner, [x1,y1].
point2: | the coordinates of bottom-right corner, [x2,y2].
color: | the color of the shape. [r,g,b] or [r,g,b,a] (0-255), color name, or Rubygame::Color.

draw_box_s( point1, point2, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_box_s)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_box, but the shape is solid, instead of an outline. (You may find using fill to be more convenient and perhaps faster than this method.)

draw_circle( center, radius, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_circle)" to see if you can use this method, or be prepared to rescue from NameError.

Draw a non-solid circle on the Surface, given the coordinates of its center and its radius. See also draw_circle_a and draw_circle_s

This method takes these arguments:

center: | the coordinates of circle‘s center, [x,y].
radius: | the radius (pixels) of the circle.
color: | the color of the shape. [r,g,b] or [r,g,b,a] (0-255), color name, or Rubygame::Color.

draw_circle_a( center, radius, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_circle_a)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_circle, but the outline is anti-aliased.

draw_circle_s( center, radius, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_circle_s)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_circle, but the shape is solid, instead of an outline.

draw_ellipse( center, radii, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_ellipse)" to see if you can use this method, or be prepared to rescue from NameError.

Draw a non-solid ellipse (oval) on the Surface, given the coordinates of its center and its horizontal and vertical radii. See also draw_ellipse_a and draw_ellipse_s

This method takes these arguments:

center: | the coordinates of ellipse‘s center, [x,y].
radii: | the x and y radii (pixels), [rx,ry].
color: | the color of the shape. [r,g,b] or [r,g,b,a] (0-255), color name, or Rubygame::Color.

draw_ellipse_a( center, radii, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_ellipse_a)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_ellipse, but the ellipse border is anti-aliased.

draw_ellipse_s( center, radii, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_ellipse_s)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_ellipse, but the shape is solid, instead of an outline.

draw_line( point1, point2, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_line)" to see if you can use this method, or be prepared to rescue from NameError.

Draw a line segment between two points on the Surface. See also draw_line_a

This method takes these arguments:

point1: | the coordinates of one end of the line, [x1,y1].
point2: | the coordinates of the other end of the line, [x2,y2].
color: | the color of the shape. [r,g,b] or [r,g,b,a] (0-255), color name, or Rubygame::Color.

draw_line_a( point1, point2, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_line_a)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_line, but the line will be anti-aliased.

draw_polygon( points, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_polygon)" to see if you can use this method, or be prepared to rescue from NameError.

Draw a non-solid polygon, given the coordinates of its vertices, in the order that they are connected. This is essentially a series of connected dots. See also draw_polygon_a and draw_polygon_s.

This method takes these arguments:

points: | an Array containing the coordinate pairs for each vertex of the polygon, in the order that they are connected, e.g. [x1,y1], [x2,y2], …, [xn,yn ].
color: | the color of the shape. [r,g,b] or [r,g,b,a] (0-255), color name, or Rubygame::Color.

draw_polygon_a( points, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_polygon_a)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_polygon, but the lines are anti-aliased.

draw_polygon_s( points, color )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:draw_polygon_s)" to see if you can use this method, or be prepared to rescue from NameError.

Like draw_polygon, but the shape is solid, instead of an outline.

fill( color, rect=nil )

Fill all or part of a Surface with a color.

This method takes these arguments:

color: | color to fill with, in the form +[r,g,b]+ or +[r,g,b,a]+ (for partially transparent fills).
rect: | a Rubygame::Rect representing the area of the surface to fill with color. Omit to fill the entire surface.

flags()

Return any flags the surface was initialized with (as a bitwise OR‘d integer).

flip( horz, vert )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:flip)" to see if you can use this method, or be prepared to rescue from NameError.

Flips the source surface horizontally (if `horz` is true), vertically (if `vert` is true), or both (if both are true).

get_at( [x,y] )
get_at( x,y )

Return the color [r,g,b,a] (0-255) of the pixel at [x,y]. If the Surface does not have a per-pixel alpha channel (i.e. not 32-bit), alpha will always be 255. The Surface‘s overall alpha value (from set_alpha) does not affect the returned alpha value.

Raises IndexError if the coordinates are out of bounds.

h()

Return the height (in pixels) of the surface.

height()

Alias for h

inspect()

Alias for to_s

make_rect()

Return a Rect with the same width and height as the Surface, with topleft = [0,0].

masks → [r,g,b,a]

Return the color masks [r,g,b,a] of the surface. Almost everyone can ignore this function. Color masks are used to separate an integer representation of a color into its seperate channels.

pixels()

Return a string of pixel data for the Surface. Most users will not need to use this method. If you want to convert a Surface into an OpenGL texture, pass the returned string to the TexImage2D method of the ruby-opengl library. (See samples/demo_gl_tex.rb for an example.)

(Please note that the dimensions of OpenGL textures must be powers of 2 (e.g. 64x128, 512x512), so if you want to use a Surface as an OpenGL texture, the Surface‘s dimensions must also be powers of 2!)

rotozoom( angle, zoom, smooth=false )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:rotozoom)" to see if you can use this method, or be prepared to rescue from NameError.

Return a rotated and/or zoomed version of the given surface. Note that rotating a Surface anything other than a multiple of 90 degrees will cause the new surface to be larger than the original to accomodate the corners (which would otherwise extend beyond the surface).

May raise Rubygame::SDLError if the rotozoom fails.

angle: | degrees to rotate counter-clockwise (negative for clockwise).
zoom: | scaling factor(s). A number (to scale X and Y by the same factor) or an array of 2 numbers (to scale X and Y by different factors). Negative numbers flip the image. NOTE: Due to a quirk in SDL_gfx, if angle is not 0, the image is zoomed by the X factor on both X and Y, and the Y factor is only used for flipping (if it‘s negative).
smooth: | whether to anti-alias the new surface. By the way, if true, the new surface will be 32bit RGBA.

savebmp( filename )

Save the Surface as a Windows Bitmap (BMP) file with the given filename. May raise SDLError if a problem occurs.

set_alpha( alpha, flags=Rubygame::SRCALPHA )

Set the per-surface alpha (opacity; non-transparency) of the surface. You can do the same thing with alpha= if you don‘t care about flags.

This function takes these arguments:

alpha: | requested opacity of the surface. Alpha must be from 0 (fully transparent) to 255 (fully opaque).
flags: | 0 or Rubygame::SRCALPHA (default). Most people will want the default, in which case this argument can be omitted. For advanced users: this flag affects the surface as described in the docs for the SDL C function, SDL_SetAlpha.

Returns self.

set_at( [x,y], color )

Set the color of the pixel at [x,y]. If no alpha value is given, or if the Surface does not have a per-pixel alpha channel (i.e. not 32-bit), the pixel will be set at full opacity.

color can be one of:

- an Array, [r,g,b] or [r,g,b,a] with each component in 0-255.
- an instance of Rubygame::ColorRGB, Rubygame::ColorHSV, etc.
- the name of a color in Rubygame::Color, as a Symbol or String

Raises IndexError if the coordinates are out of bounds.

set_colorkey( color, flags=Rubygame::SRCCOLORKEY )

Set the colorkey of the surface. See Surface#colorkey for a description of colorkeys.

This method takes these arguments:

color: | color to use as the key, in the form [r,g,b]. Can be `nil` to un-set the colorkey.
flags: | 0 or Rubygame::SRCCOLORKEY (default) or Rubygame::SRCCOLORKEY|Rubygame::SDL_RLEACCEL. Most people will want the default, in which case this argument can be omitted. For advanced users: this flag affects the surface as described in the docs for the SDL C function, SDL_SetColorkey.

size → [w,h]

Return the surface‘s width and height (in pixels) in an Array.

to_display()

Copies the Surface to a new Surface with the pixel format of the display, suitable for fast blitting to the display surface (i.e. Screen). May raise SDLError if a problem occurs.

If you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function.

to_display_alpha()

Like to_display except the Surface has an extra channel for alpha (i.e. opacity). May raise SDLError if a problem occurs.

This function can be used to convert a colorkey to an alpha channel, if the SRCCOLORKEY flag is set on the surface. The generated surface will then be transparent (alpha=0) where the pixels match the colorkey, and opaque (alpha=255) elsewhere.

to_s()
w()

Return the width (in pixels) of the surface.

width()

Alias for w

zoom( zoom, smooth=false )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:zoom)" to see if you can use this method, or be prepared to rescue from NameError.

Return a zoomed version of the Surface.

This method takes these arguments:

zoom: | a Numeric factor to scale by in both x and y directions, or an Array with separate x and y scale factors.
smooth: | whether to anti-alias the new surface. By the way, if true, the new surface will be 32bit RGBA.

zoom_to( width, height, smooth=false )

IMPORTANT: this method only exists if SDL_gfx is available! Your code should check "surface.respond_to?(:zoom_to)" to see if you can use this method, or be prepared to rescue from NameError.

Return a version of the Surface zoomed to a new size.

This method takes these arguments:

width: | the desired width. If nil, the width will stay the same.
height: | the desired height. If nil, the height will stay the same.
smooth: | whether to anti-alias the new surface. This option can be omitted, in which case the surface will not be anti-aliased. If true, the new surface will be 32bit RGBA.

[Validate]