### Home Classes Methods

### In Files

- lib/rubygame/gfx.rb
- lib/rubygame/image.rb
- lib/rubygame/surface.rb

### Parent

Object

### Methods

- ::autoload
- ::load
- ::load_from_string
- ::load_image
- ::new
- ::rotozoom_size
- ::zoom_size
- #alpha
- #alpha=
- #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
- #make_rect
- #masks
- #pixels
- #rotozoom
- #savebmp
- #set_alpha
- #set_at
- #set_colorkey
- #size
- #to_display
- #to_display_alpha
- #to_s
- #w
- #width
- #zoom
- #zoom_to

### Included Modules

- Rubygame::NamedResource

### Files

- CREDITS
- LICENSE
- NEWS
- README
- ROADMAP
- custom_sdl_load_paths.rdoc
- getting_started.rdoc
- keyboard_symbols.rdoc
- macosx_install.rdoc
- managing_framerate.rdoc
- surface_palettes.rdoc
- windows_install.rdoc

### Class/Module Index

Quicksearch

- Rubygame
- Rubygame::ActiveEvent
- Rubygame::Clock
- Rubygame::Color
- Rubygame::Color::ColorBase
- Rubygame::Color::ColorHSL
- Rubygame::Color::ColorHSV
- Rubygame::Color::ColorRGB
- Rubygame::Color::Palette
- Rubygame::Event
- Rubygame::EventActions
- Rubygame::EventActions::BlockAction
- Rubygame::EventActions::MethodAction
- Rubygame::EventActions::MultiAction
- Rubygame::EventHandler
- Rubygame::EventHandler::HasEventHandler
- Rubygame::EventHook
- Rubygame::EventQueue
- Rubygame::EventTriggers
- Rubygame::EventTriggers::AndTrigger
- Rubygame::EventTriggers::AttrTrigger
- Rubygame::EventTriggers::BlockTrigger
- Rubygame::EventTriggers::InstanceOfTrigger
- Rubygame::EventTriggers::KeyPressTrigger
- Rubygame::EventTriggers::KeyReleaseTrigger
- Rubygame::EventTriggers::KindOfTrigger
- Rubygame::EventTriggers::MouseMoveTrigger
- Rubygame::EventTriggers::MousePressTrigger
- Rubygame::EventTriggers::MouseReleaseTrigger
- Rubygame::EventTriggers::OrTrigger
- Rubygame::EventTriggers::TickTrigger
- Rubygame::EventTriggers::YesTrigger
- Rubygame::Events
- Rubygame::Events::ClockTicked
- Rubygame::Events::InputFocusGained
- Rubygame::Events::InputFocusLost
- Rubygame::Events::JoystickAxisMoved
- Rubygame::Events::JoystickBallMoved
- Rubygame::Events::JoystickButtonEvent
- Rubygame::Events::JoystickButtonPressed
- Rubygame::Events::JoystickButtonReleased
- Rubygame::Events::JoystickHatMoved
- Rubygame::Events::KeyPressed
- Rubygame::Events::KeyReleased
- Rubygame::Events::KeyboardEvent
- Rubygame::Events::MouseButtonEvent
- Rubygame::Events::MouseFocusGained
- Rubygame::Events::MouseFocusLost
- Rubygame::Events::MouseMoved
- Rubygame::Events::MousePressed
- Rubygame::Events::MouseReleased
- Rubygame::Events::QuitRequested
- Rubygame::Events::WindowExposed
- Rubygame::Events::WindowMinimized
- Rubygame::Events::WindowResized
- Rubygame::Events::WindowUnminimized
- Rubygame::ExposeEvent
- Rubygame::Ftor
- Rubygame::GL
- Rubygame::Hotspot
- Rubygame::JoyAxisEvent
- Rubygame::JoyBallEvent
- Rubygame::JoyDownEvent
- Rubygame::JoyHatEvent
- Rubygame::JoyUpEvent
- Rubygame::Joystick
- Rubygame::Key
- Rubygame::KeyDownEvent
- Rubygame::KeyUpEvent
- Rubygame::MailQueue
- Rubygame::MediaBag
- Rubygame::Mixer
- Rubygame::Mixer::Music
- Rubygame::Mixer::Sample
- Rubygame::Mouse
- Rubygame::MouseDownEvent
- Rubygame::MouseMotionEvent
- Rubygame::MouseUpEvent
- Rubygame::Music
- Rubygame::NamedResource
- Rubygame::NamedResource::NamedResourceClassMethods
- Rubygame::QuitEvent
- Rubygame::Rect
- Rubygame::ResizeEvent
- Rubygame::SDLError
- Rubygame::SFont
- Rubygame::Screen
- Rubygame::Sound
- Rubygame::Sprites
- Rubygame::Sprites::DepthSortGroup
- Rubygame::Sprites::Group
- Rubygame::Sprites::LimitGroup
- Rubygame::Sprites::Sprite
- Rubygame::Sprites::UpdateGroup
- Rubygame::Surface
- Rubygame::TTF

No matching classes.

# Rubygame::Surface

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.

### Public Class Methods

autoload( name ) click to toggle source

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.

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

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

load( filename ) click to toggle source

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.

    # 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

load_from_string( data, type=nil ) click to toggle source

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.

    # 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

load_image( filename ) click to toggle source

Deprecated. Use Surface.load instead!

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

new( size, depth=0, flags=[] ) click to toggle source

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.

    # 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

rotozoom_size( size, angle, zoom ) click to toggle source

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

    # 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

zoom_size( size, zoom ) click to toggle source

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

    # 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

alpha() click to toggle source

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

    # File lib/rubygame/surface.rb, line 200
    def alpha
      @struct.format.alpha
    end

alpha=( alpha, flags=Rubygame::SRCALPHA ) click to toggle source
Alias for: set_alpha
blit( target, pos, src_rect=nil ) click to toggle source

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.

    # 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

clip() click to toggle source

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.

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

clip=( newclip ) click to toggle source

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.

    # 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

colorkey → [r,g,b] or nil click to toggle source

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.

    # 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 ) click to toggle source
Alias for: set_colorkey
convert( other=nil, flags=nil ) click to toggle source

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.

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

      if other.nil?
        begin
          other = Rubygame::Screen.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

depth() click to toggle source

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

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

draw_arc( center, radius, angles, color ) click to toggle source

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.

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

draw_arc_s( center, radius, angles, color ) click to toggle source

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.

    # 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

draw_box( point1, point2, color ) click to toggle source

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.

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

draw_box_s( point1, point2, color ) click to toggle source

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

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

draw_circle( center, radius, color ) click to toggle source

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.

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

draw_circle_a( center, radius, color ) click to toggle source

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.

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

draw_circle_s( center, radius, color ) click to toggle source

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.

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

draw_ellipse( center, radii, color ) click to toggle source

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.

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

draw_ellipse_a( center, radii, color ) click to toggle source

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.

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

draw_ellipse_s( center, radii, color ) click to toggle source

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.

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

draw_line( point1, point2, color ) click to toggle source

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.

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

draw_line_a( point1, point2, color ) click to toggle source

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.

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

draw_polygon( points, color ) click to toggle source

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.

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

draw_polygon_a( points, color ) click to toggle source

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.

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

draw_polygon_s( points, color ) click to toggle source

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.

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

fill( color, rect=nil ) click to toggle source

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.

    # 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

flags() click to toggle source

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

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

flip( horz, vert ) click to toggle source

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

    # 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

get_at( [x,y] ) click to toggle source
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.

    # 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

h() click to toggle source

Return the height (in pixels) of the surface.

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

Also aliased as: height
height() click to toggle source
Alias for: h
inspect() click to toggle source
Alias for: to_s
make_rect() click to toggle source

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

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

masks → [r,g,b,a] click to toggle source

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.

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

pixels() click to toggle source

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

    # 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

rotozoom( angle, zoom, smooth=false ) click to toggle source

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.

    # 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

savebmp( filename ) click to toggle source

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

    # 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_alpha( alpha, flags=Rubygame::SRCALPHA ) click to toggle source

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.

    # 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

Also aliased as: alpha=
set_at( [x,y], color ) click to toggle source

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.

    # 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_colorkey( color, flags=Rubygame::SRCCOLORKEY ) click to toggle source

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.

    # 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

Also aliased as: colorkey=
size → [w,h] click to toggle source

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

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

to_display() click to toggle source

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.

    # 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

to_display_alpha() click to toggle source

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.

    # 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

to_s() click to toggle source

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

Also aliased as: inspect
w() click to toggle source

Return the width (in pixels) of the surface.

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

Also aliased as: width
width() click to toggle source
Alias for: w
zoom( zoom, smooth=false ) click to toggle source

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.

    # 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

zoom_to( width, height, smooth=false ) click to toggle source

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.

    # 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]

Generated with the Darkfish Rdoc Generator 2.