Class | Rubygame::Surface |
In: |
ext/rubygame/rubygame_mixer.c
lib/rubygame/rect.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_image, 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.
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 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 is only usable if Rubygame was compiled with the SDL_image library; you can check Rubygame::VERSIONS[:sdl_image] to see if it was.
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 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 is only usable if Rubygame was compiled with the SDL_image library; you can check Rubygame::VERSIONS[:sdl_image] to see if it was.
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. |
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. |
**NOTE:** This method name is DEPRECATED and will be removed in Rubygame 3.0. Please use the Surface.load instead.
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 is only usable if Rubygame was compiled with the SDL_image library; you can check Rubygame::VERSIONS[:sdl_image] to see if it was.
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. |
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).
|
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.
If Rubygame was compiled with SDL_gfx-2.0.13 or greater, zoom can be an Array of 2 Numerics for separate X and Y scaling. Also, it can be negative to indicate flipping horizontally or vertically.
Will return nil if you attempt to use separate X and Y zoom factors or negative zoom factors with an unsupported version of SDL_gfx.
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 single positive Numeric, unless you have SDL_gfx-2.0.13 or greater (see above). |
Return the dimensions of the surface that would be returned if zoom were called with a surface of the given size and zoom factors.
This method takes these arguments:
size: | an Array with the hypothetical surface width and height (pixels) |
zoom: | the factor to scale by in both x and y directions, or an Array with separate x and y scale factors. |
Return the per-surface alpha (opacity; non-transparency) of the surface. It can range from 0 (full transparent) to 255 (full opaque).
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. |
dest: | the coordinates of the top-left corner of the blit. Affects the area of other the image data is /pasted/ over. Can also be a Rect or an Array larger than 2, but width and height will be ignored. |
source: | 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. |
Set the current clipping area of the Surface. See also cliprect.
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.
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.
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
*IMPORTANT:* This method will only be defined if Rubygame was compiled with SDL_gfx-2.0.11 or greater. (Note: draw_arc_s does not have this requirement.)
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,a]. If alpha is omitted, it is drawn at full opacity. |
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,a]. If alpha is omitted, it is drawn at full opacity. |
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,a]. If alpha is omitted, it is drawn at full opacity. |
Like draw_circle, but the shape is solid, instead of an outline.
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,a]. If alpha is omitted, it is drawn at full opacity. |
Like draw_ellipse, but the shape is solid, instead of an outline.
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,a]. If alpha is omitted, it is drawn at full opacity. |
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] ]. To draw a closed shape, the final coordinate pair should match the first. |
color: | the color of the shape, [r,g,b,a]. If alpha is omitted, it is drawn at full opacity. |
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. |
Flips the source surface horizontally (if horz is true), vertically (if vert is true), or both (if both are true). This operation is non-destructive; the original image can be perfectly reconstructed by flipping the resultant image again.
This operation does NOT require SDL_gfx.
A similar effect can (supposedly) be achieved by giving X or Y zoom factors of -1 to rotozoom (only if compiled with SDL_gfx 2.0.13 or greater). Your mileage may vary.
Return the color [r,g,b,a] of the pixel at the given coordinate.
Raises IndexError if the coordinates are out of bounds.
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!)
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).
If Rubygame was compiled with SDL_gfx-2.0.13 or greater, zoom can be an Array of 2 Numerics for separate X and Y scaling. Also, it can be negative to indicate flipping horizontally or vertically.
Will raise SDLError if you attempt to use separate X and Y zoom factors or negative zoom factors with an unsupported version of SDL_gfx.
This method takes these arguments:
angle: | degrees to rotate counter-clockwise (negative for clockwise). |
zoom: | scaling factor(s). A single positive Numeric, unless you have SDL_gfx-2.0.13 or greater (see above). |
smooth: | whether to anti-alias the new surface. By the way, if true, the new surface will be 32bit RGBA. |
Set the per-surface alpha (opacity; non-transparency) of the surface.
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::SRC_ALPHA (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. |
Set the color of the pixel at the given coordinate.
color can be one of:
Raises IndexError if the coordinates are out of bounds.
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::SRC_COLORKEY (default) or Rubygame::SRC_COLORKEY|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. |
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.
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.
Return a zoomed version of the Surface.
This method takes these arguments:
width: | the width to scale to. If nil is given, will keep x axis unscaled. |
height: | the height to scale to. If nil is given, will keep x axis unscaled. |
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. |