| Class | Rubygame::Surface |
| In: |
lib/rubygame/rect.rb
ext/rubygame/rubygame_transform.c |
| Parent: | Object |
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.
The new surface retrieves the pixel format of the display window to use as its own. Because of this, the display window must be created before this method can be used.
This function takes these arguments:
| size: | requested surface size; an array of the form [width, height]. | ||||||||
| flags: | a 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 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. |
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.
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. |
Return the color [r,g,b,a] of the pixel at the given coordinate.
This method takes these argument:
The coordinate can also be given as two arguments, separate x and y positions.
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!)
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 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. |