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

Included Modules

Rubygame::NamedResource

Public Class methods

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.

[Source]

# File lib/rubygame/image.rb, line 38
    def autoload( name )
      path = find_file( name )

      if( path )
        return load( path )
      else
        return nil
      end
    end

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.

[Source]

# File lib/rubygame/image.rb, line 78
    def load( filename )
      surf = SDL::Image.Load( filename )

      if( surf.pointer.null? )
        raise( Rubygame::SDLError, "Couldn't load image \"%s\": %s"%\
               [filename, SDL.GetError()] )
      end

      return self.new(surf)
    end

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.

[Source]

# File lib/rubygame/image.rb, line 118
    def load_from_string( data, type=nil )
      raw = FFI::Buffer.new(:char, data.length)
      raw.put_bytes(0, data)

      rw = SDL.RWFromMem( raw, data.length )

      surf = if type
               SDL::Image.LoadTyped_RW(rw, 1, type)
             else
               SDL::Image.Load_RW(rw, 1)
             end
      
      if surf.pointer.null?
        raise( Rubygame::SDLError,
               "Couldn't load image from string: #{SDL.GetError()}" )
      end

      return new(surf)
    end

Deprecated. Use Surface.load instead!

[Source]

# File lib/rubygame/image.rb, line 91
    def load_image( filename )
      Rubygame.deprecated( "Rubygame::Surface.load_image", "3.0" )
      load( filename )
    end

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.

[Source]

# File lib/rubygame/surface.rb, line 83
  def initialize( size, depth=0, flags=[] )

    # Cheating a bit. First arg can be a SDL::Surface to wrap it.
    #
    if( size.kind_of? SDL::Surface )
      surf = size
      if( surf.pointer.null? )
        raise Rubygame::SDLError, "Surface cannot wrap NULL Surface!"
      else
        @struct = surf
      end
      return
    end

    unless size.kind_of? Array
      raise TypeError, "Surface size is not an Array: #{size.inspect}"
    end

    unless size.length == 2 and size.all?{ |n| n.kind_of? Numeric }
      raise ArgumentError, "Invalid Surface size: #{size.inspect}"
    end


    pixformat = nil

    vs = SDL.GetVideoSurface()

    unless( vs.pointer.null? )
      # Pixel format is retrieved from the video surface.
      pixformat = vs.format
    else
      # We can only get the system color depth when the
      # video system has been initialized.
      if( Rubygame.init_video_system == 0 )
        pixformat = SDL.GetVideoInfo().vfmt
      else
        raise(Rubygame::SDLError,
              "Could not initialize SDL video subsystem.")
      end
    end

    rmask = pixformat.Rmask
    gmask = pixformat.Gmask
    bmask = pixformat.Bmask
    amask = pixformat.Amask

    if( depth <= 0 )
      depth = pixformat.BitsPerPixel
    end

    w, h = size

    flags = Rubygame.collapse_flags(flags)

    @struct = SDL.CreateRGBSurface(flags, w, h, depth,
                                   rmask, gmask, bmask, amask)
  end

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

[Source]

# File lib/rubygame/gfx.rb, line 459
  def self.rotozoom_size( size, angle, zoom )
    w, h = size

    case zoom
    when Array
      zx, zy = zoom.collect { |n| n.to_f }
      SDL::Gfx.rotozoomSurfaceSizeXY(w, h, angle, zx, zy)
    when Numeric
      zoom = zoom.to_f
      SDL::Gfx.rotozoomSurfaceSize(w, h, angle, zoom)
    else
      raise ArgumentError, "Invalid zoom factor: #{zoom.inspect}"
    end
  end

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

[Source]

# File lib/rubygame/gfx.rb, line 525
  def self.zoom_size( size, zoom )
    w, h = size

    case zoom
    when Array
      zx, zy = zoom.collect { |n| n.to_f }
      SDL::Gfx.zoomSurfaceSize(w, h, zx, zy)
    when Numeric
      zoom = zoom.to_f
      SDL::Gfx.zoomSurfaceSize(w, h, zoom, zoom)
    else
      raise ArgumentError, "Invalid zoom factor: #{zoom.inspect}"
    end
  end

Public Instance methods

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

[Source]

# File lib/rubygame/surface.rb, line 200
  def alpha
    @struct.format.alpha
  end
alpha=( alpha, flags=Rubygame::SRCALPHA )

Alias for set_alpha

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.

[Source]

# File lib/rubygame/surface.rb, line 285
  def blit( target, pos, src_rect=nil )
    unless target.kind_of? Rubygame::Surface
      raise TypeError, "blit target must be a Surface"
    end

    src_x, src_y, src_w, src_h =
      case src_rect
      when SDL::Rect
        [src_rect.x, src_rect.y, src_rect.w, src_rect.h]
      when Array
        src_rect
      when nil
        [0, 0] + self.size
      end

    src_rect  = SDL::Rect.new([src_x,  src_y,  src_w, src_h])
    blit_x, blit_y = pos
    blit_rect = SDL::Rect.new([blit_x, blit_y, src_w, src_h])

    SDL.BlitSurface( @struct, src_rect, target.struct, blit_rect )

    return Rubygame::Rect.new( blit_rect.to_ary )
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 471
  def clip
    Rubygame::Rect.new( SDL.GetClipRect(@struct).to_ary )
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 487
  def clip=( newclip )
    newclip = case newclip
              when nil, SDL::Rect
                newclip         # no change
              when Rubygame::Rect
                newclip.to_sdl
              when Array
                Rubygame::Rect.new(newclip).to_sdl
              end

    SDL.SetClipRect(@struct, newclip)
    return self
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 235
  def colorkey
    if( (@struct.flags & Rubygame::SRCCOLORKEY) == Rubygame::SRCCOLORKEY )
      SDL::GetRGB(@struct.format.colorkey, @struct.format)
    else
      nil
    end 
  end
colorkey=( color, flags=Rubygame::SRCCOLORKEY )

Alias for set_colorkey

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.

[Source]

# File lib/rubygame/surface.rb, line 514
  def convert( other=nil, flags=nil )

    if other.nil?
      begin
        other = Rubygame::ScreenFFI.get_surface
      rescue Rubygame::SDLError
        raise( Rubygame::SDLError, "Cannot convert Surface with no target " +
               "given and no Screen made: #{SDL.GetError()}" )
      end
    end

    flags = Rubygame.collapse_flags(flags)

    newsurf =
      if( Rubygame.init_video_system() == 0 )
        SDL.ConvertSurface( @struct, other.struct.format, flags )
      else
        nil
      end

    if( newsurf.nil? or newsurf.pointer.null?)
      raise( Rubygame::SDLError,
             "Could not convert the Surface: #{SDL.GetError()}" )
    end

    # Wrap it
    return self.class.new( newsurf )
  end

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

[Source]

# File lib/rubygame/surface.rb, line 171
  def depth
    @struct.format.BitsPerPixel
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 300
  def draw_arc( center, radius, angles, color )
    _draw_arc( center, radius, angles, color, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 313
  def draw_arc_s( center, radius, angles, color )
    _draw_arc( center, radius, angles, color, true )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 115
  def draw_box( point1, point2, color )
    _draw_box( point1, point2, color, false )
    return self
  end

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

[Source]

# File lib/rubygame/gfx.rb, line 130
  def draw_box_s( point1, point2, color )
    _draw_box( point1, point2, color, true )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 169
  def draw_circle( center, radius, color )
    _draw_circle( center, radius, color, false, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 181
  def draw_circle_a( center, radius, color )
    _draw_circle( center, radius, color, true, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 194
  def draw_circle_s( center, radius, color )
    _draw_circle( center, radius, color, false, true )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 234
  def draw_ellipse( center, radii, color )
    _draw_ellipse( center, radii, color, false, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 246
  def draw_ellipse_a( center, radii, color )
    _draw_ellipse( center, radii, color, true, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 259
  def draw_ellipse_s( center, radii, color )
    _draw_ellipse( center, radii, color, false, true )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 66
  def draw_line( point1, point2, color )
    _draw_line( point1, point2, color, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 78
  def draw_line_a( point1, point2, color )
    _draw_line( point1, point2, color, true )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 361
  def draw_polygon( points, color )
    _draw_polygon( points, color, false, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 374
  def draw_polygon_a( points, color )
    _draw_polygon( points, color, true, false )
    return self
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 387
  def draw_polygon_s( points, color )
    _draw_polygon( points, color, false, true )
    return self
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 318
  def fill( color, rect=nil )
    unless rect.nil? or rect.kind_of? Array
      raise TypeError, "invalid fill Rect: #{rect.inspect}"
    end

    color = _map_sdl_color( color )
    rect = SDL::Rect.new( rect.to_ary ) unless rect.nil?
    SDL.FillRect( @struct, rect, color )
    return self
  end

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

[Source]

# File lib/rubygame/surface.rb, line 179
  def flags
    @struct.flags
  end

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

[Source]

# File lib/rubygame/gfx.rb, line 578
  def flip( horz, vert )
    self.zoom( [ (horz ? -1.0 : 1.0), (vert ? -1.0 : 1.0)], false )
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 349
  def get_at( *args )
    x,y = case args.length
          when 1; args[0].to_ary.collect { |n| n.round }
          when 2; [args[0].round, args[1].round]
          else
            raise( ArgumentError,
                   "wrong number of arguments (#{args.length} for 1)" )
          end

    if( x < 0 or x >= @struct.w or y < 0 or y >= @struct.h)
      raise( IndexError, "point [%d,%d] is out of bounds for %dx%d Surface"%\
             [x, y, @struct.w, @struct.h] )
    end

    SDL.LockSurface(@struct)

    bpp = @struct.format.BytesPerPixel
    ptr = @struct.pixels + (y * @struct.pitch + x * bpp)

    pixel =
      case bpp
      when 1
        ptr.get_uint8(0)
      when 2
        ptr.get_uint16(0)
      when 3
        if( FFI::Platform::BYTE_ORDER == FFI::Platform::BIG_ENDIAN )
          (ptr.get_uint8(0) << 16)|(ptr.get_uint8(1) << 8)|ptr.get_uint8(2)
        else
          ptr.get_uint8(0)|(ptr.get_uint8(1) << 8)|(ptr.get_uint8(2) << 16)
        end
      when 4
        ptr.get_uint32(0)
      end

    SDL.UnlockSurface(@struct)

    return SDL::GetRGBA(pixel, @struct.format) 
  end

Return the height (in pixels) of the surface.

[Source]

# File lib/rubygame/surface.rb, line 153
  def h
    @struct.h
  end
height()

Alias for h

inspect()

Alias for to_s

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

[Source]

# File lib/rubygame/surface.rb, line 333
  def make_rect()
    return Rubygame::Rect.new( 0, 0, self.w, self.h )
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 191
  def masks
    fmt = @struct.format
    [fmt.Rmask, fmt.Gmask, fmt.Bmask, fmt.Amask]
  end

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!)

[Source]

# File lib/rubygame/surface.rb, line 455
  def pixels
    len = @struct.pitch * @struct.h
    SDL.LockSurface(@struct)
    pix = @struct.pixels.get_bytes(0, len)
    SDL.UnlockSurface(@struct)
    return pix
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 417
  def rotozoom( angle, zoom, smooth=false )
    smooth = smooth ? 1 : 0

    surf = case zoom
           when Array
             zx, zy = zoom.collect { |n| n.to_f }
             SDL::Gfx.rotozoomSurfaceXY(@struct, angle, zx, zy, smooth)
           when Numeric
             zoom = zoom.to_f
             SDL::Gfx.rotozoomSurface(@struct, angle, zoom, smooth)
           else
             raise ArgumentError, "Invalid zoom factor: #{zoom.inspect}"
           end

    if( surf.pointer.null? )
      raise( Rubygame::SDLError,
             "Rotozoom failed: " + SDL.GetError() )
    end

    return self.class.new(surf)
  end

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

[Source]

# File lib/rubygame/surface.rb, line 603
  def savebmp( filename )
    result = SDL.SaveBMP( @struct, filename )
    if(result != 0)
      raise( Rubygame::SDLError, "Couldn't save surface to file %s: %s"%\
             [filename, SDL.GetError()] )
    end
    nil
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 217
  def set_alpha( alpha, flags=Rubygame::SRCALPHA )
    result = SDL.SetAlpha(@struct, flags, alpha.to_i)
    raise Rubygame::SDLError, SDL.GetError() unless result == 0
    return self
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 404
  def set_at( pos, color )
    x,y = pos.to_ary.collect { |n| n.round }

    if( x < 0 or x >= @struct.w or y < 0 or y >= @struct.h)
      raise( IndexError, "point [%d,%d] is out of bounds for %dx%d Surface"%\
             [x, y, @struct.w, @struct.h] )
    end

    color = _map_sdl_color( color )

    SDL.LockSurface(@struct)

    bpp = @struct.format.BytesPerPixel
    ptr = @struct.pixels + (y * @struct.pitch + x * bpp)

    case bpp
    when 1
      ptr.put_uint8(0, color)
    when 2
      ptr.put_uint16(0, color)
    when 3
      if( FFI::Platform::BYTE_ORDER == FFI::Platform::BIG_ENDIAN )
        ptr.put_uint8(0, (color >> 16) & 0xff)
        ptr.put_uint8(1, (color >> 8)  & 0xff)
        ptr.put_uint8(2, color & 0xff)
      else
        ptr.put_uint8(0, color & 0xff)
        ptr.put_uint8(1, (color >> 8)  & 0xff)
        ptr.put_uint8(2, (color >> 16) & 0xff)
      end
    when 4
      ptr.put_uint32(0, color)
    end

    SDL.UnlockSurface(@struct)

    return
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 256
  def set_colorkey( color, flags=Rubygame::SRCCOLORKEY )
    if color.nil?
      color, flags = 0, 0
    else
      color = _map_sdl_color( color )
    end

    result = SDL.SetColorKey(@struct, flags, color)
    raise Rubygame::SDLError, SDL.GetError() unless result == 0
    return self
  end

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

[Source]

# File lib/rubygame/surface.rb, line 164
  def size
    [@struct.w, @struct.h]
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 553
  def to_display
    newsurf =
      if( Rubygame.init_video_system() == 0 )
        SDL.DisplayFormat( @struct )
      else
        nil
      end

    if( newsurf.nil? or newsurf.pointer.null?)
      raise( Rubygame::SDLError,
             "Could not convert the Surface to display format: %s"%\
             SDL.GetError() )
    end

    # Wrap it
    return self.class.new( newsurf )
  end

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.

[Source]

# File lib/rubygame/surface.rb, line 581
  def to_display_alpha
    newsurf =
      if( Rubygame.init_video_system() == 0 )
        SDL.DisplayFormatAlpha( @struct )
      else
        nil
      end

    if( newsurf.nil? or newsurf.pointer.null?)
      raise( Rubygame::SDLError,
             "Could not convert the Surface to display format "+
             "with alpha channel: #{SDL.GetError()}" )
    end

    # Wrap it
    return self.class.new( newsurf )
  end

[Source]

# File lib/rubygame/surface.rb, line 613
  def to_s
    "#<%s:%#.x>"%[self.class.name, self.object_id]
  end

Return the width (in pixels) of the surface.

[Source]

# File lib/rubygame/surface.rb, line 145
  def w
    @struct.w
  end
width()

Alias for w

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.

[Source]

# File lib/rubygame/gfx.rb, line 488
  def zoom( zoom, smooth=false )
    smooth = smooth ? 1 : 0

    surf = case zoom
           when Array
             zx, zy = zoom.collect { |n| n.to_f }
             SDL::Gfx.zoomSurface(@struct, zx, zy, smooth)
           when Numeric
             zoom = zoom.to_f
             SDL::Gfx.zoomSurface(@struct, zoom, zoom, smooth)
           else
             raise ArgumentError, "Invalid zoom factor: #{zoom.inspect}"
           end

    if( surf.pointer.null? )
      raise( Rubygame::SDLError, "Zoom failed: " + SDL.GetError() )
    end

    return self.class.new(surf)
  end

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.

[Source]

# File lib/rubygame/gfx.rb, line 555
  def zoom_to( width, height, smooth=false )
    zoomx = case width
            when nil;      1.0
            when Numeric;  width.to_f / @struct.w
            end
             
    zoomy = case height
            when nil;      1.0
            when Numeric;  height.to_f / @struct.h
            end

    return self.zoom( [zoomx, zoomy], smooth )
  end

[Validate]