# DisplaySurface

The DisplaySurface is the surface that represents the window or the full screen that you will be drawing and blitting on. Since it is inherited from Surface, it can be used just like an ordinary surface. You will need to create a DisplaySurface to show anything on your screen.

## Initializers

#### new( size ) → DisplaySurface
new( size, flags ) → DisplaySurface
new( size, flags, depth ) → DisplaySurface

- size is the requested size for the new display in [w,h] format.
- flags is a combination of the following:
  - `SWSURFACE`, to create the display in normal memory,
  - `HWSURFACE`, to create the display in the memory of your video hardware, if possible,
  - `ASYNCBLIT`, to (i quote) "enable the use of asynchronous to the display surface. This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems."
  - `RESIZABLE`, to make a resizable display (see events to find the event that it sends),
  - `HWPALETTE`, to grab the system palette,
  - `DOUBLEBUF`, to enable double buffered hardware pageflipping. Use flip with this.
  - `FULLSCREEN`, attempts to grab all of the screen,
  - `NOFRAME`, leaves the frame off the window.
  - `OPENGL`, to create an OpenGL window.
- depth selects the bits per pixel value (8 is 256 colors, 16 is thousands of colors, 24 and 32 are millions of colors). If it is not supplied, a good one will be selected for you.

## Methods

#### destroy → nil

Destroys the display, removing the window or returning from fullscreen mode. Do not call methods on a destroyed DisplaySurface!

#### DisplaySurface.get → DisplaySurface or nil

Gets the current DisplaySurface, or nil if there isn't one.

#### driver → String

Returns the name of the videodriver that is being used.

#### flip → self

This will update the contents of the entire display. If your display mode is using the flags `HWSURFACE` and `DOUBLEBUF`, this will wait for a vertical retrace (if the video driver supports it) and swap the surfaces. If you are using a different type of display mode, it will simply update the entire contents of the surface.

When using an OpenGL display mode this will perform a gl buffer swap.

#### gamma=( [r,g,b] ) → boolean
gamma=( intensity ) → boolean

Sets the gamma value for the display when this is supported. intensity is a shortcut for values where r=g=b.

#### info

See best_mode_info

#### toggle_fullscreen

Toggles between fullscreen and windowed mode. The code is experimental and is known to crash in some cases, please report problems if found. It might be better to not use this at all and use DisplaySurface.destroy to dispose of the current DisplaySurface and create a new one with DisplaySurface.new with the FULLSCREEN flag toggled.

#### update → self
update( rect ) → self

This call will update a section (or sections) of the display screen. You must update an area of your display when you change its contents. rect is an array of rectangles. If passed with no arguments, this will update the entire display surface.

This call cannot be used on OpenGL displays, and will generate an exception.

## OpenGL

RUDL supports setting up an OpenGL window in a cross platform way. Several other methods apply. See flip and new.

#### VideoSurface.gl_get_attribute( name ) → Number

From the SDL documentation:

Get an attribute of the OpenGL subsystem from the windowing interface, such as glX. This is of course different from getting the values from SDL's internal OpenGL subsystem, which only stores the values you request before initialization.

Developers should track the values they pass into SDL_GL_SetAttribute themselves if they want to retrieve these values.

#### VideoSurface.gl_set_attribute( name, value ) → self

Set an attribute of the OpenGL subsystem before intialization.

## SurfacesLostException

This gruesome thing is thrown by Surface#blit when Windows manages to destroy all your surfaces. This might happen when switching to another application, for example. The only thing to rescue your application is by waiting for blit to stop throwing exceptions, then reloading all your surfaces.

## Video modes

#### best_mode_info

This method returns a hash filled with information about the video hardware.

These entries are true or false:

- hardware surfaces available
- window manager available
- hardware to hardware blits accelerated
- hardware to hardware colorkey blits accelerated
- hardware to hardware alpha blits accelerated
- software to hardware blits accelerated
- software to hardware colorkey blits accelerated
- software to hardware alpha blits accelerated
- color fills accelerated
- video memory (in kilobytes)

There is currently no difference between best_mode_info and info, except that one is a class method and the other an instance method, but there may be differences in the future.

#### DisplaySurface.mode_ok? → boolean

Like new, but doesn't set the mode, only returns true if the mode can be set, and false if it can't.

#### DisplaySurface.modes → [w,h] or nil
DisplaySurface.modes( bitdepth ) → [w,h] or nil
DisplaySurface.modes( bitdepth, flags ) → [w,h] or nil

Lists available modes for a certain bitdepth and optionally only those modes that can do flags. Flags are like those in DisplaySurface.new. No flags is the same as passing `FULLSCREEN`. Return value nil means any mode is ok, an empty array means no mode is supported.

## Windowing system

#### active? → boolean

Returns true if the application is active (i.e. not minimized).

#### caption → [String, String]

Returns the title and icontitle of the window.

#### iconify → boolean

Iconifies (minimizes) the application. Returns true if successful.

#### set_caption( title ) → self
set_caption( title, icontitle ) → self

Sets the title of the window (if the application runs in a window) to title. Supplying icontitle sets the title of the icon that shows when the application is iconified to icontitle, or title if icontitle is not supplied.

#### set_icon( icon_surface ) → nil
set_icon( icon_surface, mask_string ) → nil

Sets the icon for the display window.

The SDL docs say this must be called before calling DisplaySurface.new, but at least on Windows this is not true. This method exists also as a class method of DisplaySurface.

Win32 icons must be 32x32 to work properly.

If icon_surface has a colorkey set, that color will be transparent. (Since SDL currently handles that wrong, RUDL generates the mask instead, unless you supply nil for mask_string.) Alternatively, you can supply mask_string where each byte represents the visibility of 8 pixels (MSB is the leftmost pixel, 0 means transparent).

## Windowing system input event classes

ResizeEvent
  Contains size, which is a [w, h] array indicating the new size of the window.
ActiveEvent
  Contains gain and state.
QuitEvent
  This event signals that the user or the program itself has requested to be terminated. It is triggered when the close button of the window is pressed.
VideoExposeEvent
  Triggered when the screen has been modified outside of the application, usually by the window manager and needs to be redrawn.