Class: Rubygame::Screen

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, we 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 and the Draw functions. However, the Screen cannot have a colorkey or an alpha channel, so Surface#set_colorkey and Surface#set_alpha are not inherited.

Please note that only one Screen can exist, per application, at a time; this is a limitation of SDL. You must use Screen.set_mode to create the Screen or modify its properties.

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.

Methods

caption flip get_surface new set_caption set_mode show_cursor= show_cursor? update update_rects

Public Class methods

get_surface

Returns the current display window, or raises SDLError if it fails to get it (for example, if it doesn‘t exist yet).

new

A dummy function which will raise StandardError! You must instead use Screen.set_mode() to create or change the Screen mode!

Screen is a Singleton-style class, which means that only one may exist at a time (per application). You can create a Screen or change the existing one using Screen.set_mode, and get a reference to an existing Screen with Screen.get_surface

A Screen.new method would imply that more than one could be created, so to avoid confusion Screen has no such method.

(But, this annoying behavior feels like a really bad wart, so in the future, Screen.new will probably be an alias to set_mode. Let me know what you think about this.)

set_mode(size, depth=0, flags=[SWSURFACE])

Create a new Rubygame window if there is none, or modify the existing one. Returns the resulting Surface.

This method takes these arguments:

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.
RESIZABLE:	Create a resizable window. When the window is resized by the user, a ResizeEvent is generated and set_mode 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.

Public Instance methods

caption

Returns the current window title and icon caption for the Screen as an Array. See set_caption for a description of the window title/icon caption. By default, the title and icon caption are empty strings.

flip()

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

set_caption(title, icon_cap=nil)

Sets the window title and icon caption for the Screen.

This method takes these arguments:

title:	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.
icon_cap:	a String, (usually) displayed when the window is iconized (minimized), for example to the taskbar. If omitted on `nil`, `icon_cap` will be the same as `title`. How this string is displayed (if at all) is system-dependent.

show_cursor = value → true or false or nil

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?

show_cursor? → true or false

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

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 Display.set_mode), you should use Screen#flip instead.

This method takes these arguments:

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.

update_rects(rects)

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

This method takes these arguments:

rects:

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