Class: Rubygame::Screen

Inherits:
Surface show all
Defined in:
lib/rubygame/screen.rb

Overview

Screen represents the display window for the game. The Screen is a special Surface that is displayed to the user. By changing and then updating the Screen many times per second, you can create the illusion of continous motion.

Screen inherits most of the Surface methods, and can be passed to methods which expect a Surface, including Surface#blit. However, the Screen cannot have an alpha channel or a colorkey, so Surface#alpha=, Surface#set_alpha, Surface#colorkey=, and Surface#set_colorkey are not inherited.

Please note that only one Screen can exist at a time, per application; this is a limitation of SDL. Use Screen.new (or its alias, Screen.open) to create or modify the Screen.

Also note that no changes to the Screen will be seen until it is refreshed. See #update, #update_rects, and #flip for ways to refresh all or part of the Screen.

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Surface

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

Methods included from NamedResource

included, #name, #name=

Constructor Details

#initialize(size, depth = 0, flags = [Rubygame::SWSURFACE]) ⇒ Screen

Create a new Rubygame window if there is none, or modify the existing one. You cannot create more than one Screen; the existing one will be replaced. (This is a limitation of SDL.)

Returns the resulting Screen.

size

requested window size (in pixels), in the form [width,height]

depth

requested color depth (in bits per pixel). If 0 (default), the current system color depth.

flags

an Array of zero or more of the following flags (located under the Rubygame module).

SWSURFACE

Create the video surface in system memory.

HWSURFACE

Create the video surface in video memory.

ASYNCBLIT

Enables the use of asynchronous updates of the display surface. This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.

ANYFORMAT

Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, Rubygame will emulate one with a shadow surface. Passing ANYFORMAT prevents this and causes Rubygame to use the video surface regardless of its depth.

DOUBLEBUF

Enable hardware double buffering; only valid with HWSURFACE. Calling #flip will flip the buffers and update the screen. All drawing will take place on the surface that is not displayed at the moment. If double buffering could not be enabled then #flip will just update the entire screen.

FULLSCREEN

Rubygame will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason), the next higher resolution will be used and the display window centered on a black background.

OPENGL

Create an OpenGL rendering context. You must set proper OpenGL video attributes with GL#set_attrib before calling this method with this flag. You can then use separate opengl libraries (for example rbogl) to do all OpenGL-related functions. Please note that you can’t blit or draw regular SDL Surfaces onto an OpenGL-mode screen; you must use OpenGL functions.

RESIZABLE

Create a resizable window. When the window is resized by the user, a ResizeEvent is generated and this method can be called again with the new size.

NOFRAME

If possible, create a window with no title bar or frame decoration. Fullscreen modes automatically have this flag set.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/rubygame/screen.rb', line 207

def initialize(  size, depth=0, flags=[Rubygame::SWSURFACE] )

  # 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, "Screen cannot wrap NULL Surface!"
    elsif( surf.pointer != SDL.GetVideoSurface().pointer )
      raise Rubygame::SDLError, "Screen can only wrap the video Surface!"
    else
      @struct = surf
    end
    return
  end


  w,h = size
  flags = Rubygame.collapse_flags(flags)

  @struct = SDL.SetVideoMode( w, h, depth, flags )

  if( @struct.pointer.null? )
    @struct = nil
    raise( Rubygame::SDLError,
           "Couldn't set [%d x %d] %d bpp video mode: %s"%\
           [w, h, depth, SDL.GetError()] )
  end

end

Class Method Details

.close ⇒ Object

Close the Screen, making the Rubygame window disappear. This method also exits from fullscreen mode, if needed.

After calling this method, you should discard any references to the old Screen surface, as it is no longer valid, even if you call Screen.new again.

(Note: You do not need to close the Screen to change its size or flags, you can simply call Screen.new while already open.)



91
92
93
94
 
# File 'lib/rubygame/screen.rb', line 91

def close
  SDL.QuitSubSystem( SDL::INIT_VIDEO )
  nil
end

.get_resolution ⇒ Object

Returns the pixel dimensions of the user’s display (i.e. monitor). (That is not the same as Screen#size, which only measures the Rubygame window.) You can use this information to detect how large of a Screen can fit on the user’s display.

This method can only be used when there is no open Screen instance. This method raises SDLError if there is a Screen instance (i.e. you have done Screen.new before). This is a limitation of the SDL function SDL_GetVideoInfo, which behaves differently when a Screen is open than when it is closed.

This method will also raise SDLError if it cannot get the display size for some other reason.



134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/rubygame/screen.rb', line 134

def get_resolution
  if( Rubygame.init_video_system() != 0 )
    raise(Rubygame::SDLError, "Could not initialize SDL video subsystem.")
  end

  unless SDL.GetVideoSurface().pointer.null?
    raise( Rubygame::SDLError, "You cannot get resolution when there " +
           "is an open Screen. See the docs for the reason." )
  end

  info = SDL::GetVideoInfo()
  if( info.pointer.null? )
    raise Rubygame::SDLError, "Couldn't get video info: #{SDL.GetError()}"
  end

  return [info.current_w, info.current_h]
end

.get_surface ⇒ Object

Returns the currently open Screen, or raises SDLError if it fails to get it (for example, if it doesn’t exist yet).



108
109
110
111
112
113
114
115
116
117
 
# File 'lib/rubygame/screen.rb', line 108

def get_surface
  s = SDL.GetVideoSurface()

  if s.pointer.null?
    raise( Rubygame::SDLError,
           "Couldn't get video surface: #{SDL.GetError()}" )
  end

  return self.new( s )
end

.instance(size, depth = 0, flags = [Rubygame::SWSURFACE]) ⇒ Object

Deprecated alias for Screen.new. This method will be REMOVED in Rubygame 3.0. You should use Screen.new (or its alias, Screen.open) instead.



76
77
78
79
 
# File 'lib/rubygame/screen.rb', line 76

def instance( size, depth=0, flags=[Rubygame::SWSURFACE] )
  Rubygame.deprecated("Rubygame::Screen.instance", "3.0")
  new( size, depth, flags )
end

.open? ⇒ Boolean

True if there is an open Rubygame window. See Screen.new and Screen.close.

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/rubygame/screen.rb', line 100

def open?
  (not SDL.GetVideoSurface().pointer.null?)
end

.set_mode(size, depth = 0, flags = [Rubygame::SWSURFACE]) ⇒ Object

Deprecated alias for Screen.new. This method will be REMOVED in Rubygame 3.0. You should use Screen.new (or its alias, Screen.open) instead.



67
68
69
70
 
# File 'lib/rubygame/screen.rb', line 67

def set_mode( size, depth=0, flags=[Rubygame::SWSURFACE] )
  Rubygame.deprecated("Rubygame::Screen.set_mode", "3.0")
  new( size, depth, flags )
end

Instance Method Details

#flip ⇒ Object

If the Rubygame display is double-buffered (see Screen.new), flips the buffers and updates the whole screen. Otherwise, just updates the whole screen.



244
245
246
247
 
# File 'lib/rubygame/screen.rb', line 244

def flip
  SDL.Flip( @struct )
  self
end

#icon=(surface) ⇒ Object

Sets the window icon for the Screen.

icon

a Rubygame::Surface to be displayed at the top of the Rubygame window (when not in fullscreen mode), and in other OS-specific areas (like the taskbar entry). If omitted or nil, no icon will be shown at all.

NOTE: The SDL docs state that icons on Win32 systems must be 32x32 pixels. That may or may not be true anymore, but you might want to consider it when creating games to run on Windows.



328
329
330
331
 
# File 'lib/rubygame/screen.rb', line 328

def icon=( surface )
  SDL.WM_SetIcon( surface.struct, nil )
  return self
end

#show_cursor=(value) ⇒ Object

Set whether the mouse cursor is displayed or not. If value is true, the cursor will be shown; if false, it will be hidden. See also #show_cursor?



347
348
349
350
 
# File 'lib/rubygame/screen.rb', line 347

def show_cursor=( value )
  value = value ? SDL::ENABLE : SDL::DISABLE
  return ( SDL.ShowCursor(value) == SDL::ENABLE )
end

#show_cursor? ⇒ Boolean

Returns true if the mouse cursor is shown, or false if hidden. See also #show_cursor=

Returns:

  • (Boolean) 


338
339
340
 
# File 'lib/rubygame/screen.rb', line 338

def show_cursor?
  return ( SDL.ShowCursor(SDL::QUERY) == 1 )
end

#title ⇒ Object

Returns the current window title for the Screen. The default is an empty string.



357
358
359
 
# File 'lib/rubygame/screen.rb', line 357

def title
  return SDL.WM_GetCaption()[0]
end

#title=(newtitle) ⇒ Object

Sets the window title for the Screen.

newtitle

a string, (usually) displayed at the top of the Rubygame window (when not in fullscreen mode). If omitted or nil, title will be an empty string. How this string is displayed (if at all) is system-dependent.



369
370
371
 
# File 'lib/rubygame/screen.rb', line 369

def title=( newtitle )
  SDL.WM_SetCaption( newtitle, newtitle )
end

#update(*args) ⇒ Object

call-seq:

update
update( rect )
update( x,y,w,h )

Updates (refreshes) all or part of the Rubygame window, revealing to the user any changes that have been made since the last update. If you’re using a double-buffered display (see Screen.new), you should use Screen#flip instead.

rect

a Rubygame::Rect representing the area of the screen to update. Can also be an length-4 Array, or given as 4 separate arguments. If omitted or nil, the entire screen is updated.



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/rubygame/screen.rb', line 264

def update( *args )
  r = case args[0]
      when nil
        # Update the whole screen. Skip the stuff below.
        SDL.UpdateRect( @struct, 0, 0, 0, 0 );
        return self
      when SDL::Rect
        Rubygame::Rect.new( args[0].to_ary )
      when Array
        Rubygame::Rect.new( args[0] )
      when Numeric
        Rubygame::Rect.new( args[0,4] )
      else
        raise( ArgumentError,
               "Invalid args for #{self.class}#update: #{args.inspect}" )
      end

  SDL.UpdateRect( @struct, *(r.clip!( self.make_rect ).to_sdl) );

  return self
end

#update_rects(rects) ⇒ Object

Updates (as Screen#update does) several areas of the screen.

rects

an Array containing any number of Rect objects, each rect representing a portion of the screen to update.



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
 
# File 'lib/rubygame/screen.rb', line 293

def update_rects( rects )
  my_rect = self.make_rect

  rects.collect! do |r|
    r = case r
        when SDL::Rect
          Rubygame::Rect.new( r.to_ary )
        when Array
          Rubygame::Rect.new( r )
        else
          raise( ArgumentError,
                 "Invalid rect for #{self.class}#update_rects: #{r.inspect}" )
        end

    r.clip!(my_rect).to_sdl
  end

  SDL.UpdateRects( @struct, rects )

  return self
end