gosu 0.7.48 → 0.7.49

data/GosuImpl/Graphics/Image.cpp

@@ -38,7 +38,7 @@ Gosu::Image::Image(Graphics& graphics, const Bitmap& source,
 {
 }
 
-Gosu::Image::Image(std::auto_ptr<ImageData> data)
+Gosu::Image::Image(GOSU_UNIQUE_PTR<ImageData> data)
 :   data(data.release())
 {
     if (this->data.get() == 0)

data/GosuImpl/Graphics/LargeImageData.hpp

@@ -4,6 +4,7 @@
 #include <Gosu/Fwd.hpp>
 #include <Gosu/ImageData.hpp>
 #include <Gosu/TR1.hpp>
+#include <Gosu/Platform.hpp>
 #include <stdexcept>
 #include <vector>
 
@@ -32,9 +33,9 @@ namespace Gosu
             return 0;
         }
         
-        std::auto_ptr<ImageData> subimage(int x, int y, int w, int h) const
+        GOSU_UNIQUE_PTR<ImageData> subimage(int x, int y, int w, int h) const
         {
-            return std::auto_ptr<ImageData>();
+            return GOSU_UNIQUE_PTR<ImageData>();
         }
         
         Bitmap toBitmap() const;

data/GosuImpl/Graphics/Macro.hpp

@@ -4,6 +4,7 @@
 #include <Gosu/Fwd.hpp>
 #include <Gosu/ImageData.hpp>
 #include <Gosu/TR1.hpp>
+#include <Gosu/Platform.hpp>
 #include "Common.hpp"
 #include "DrawOpQueue.hpp"
 #include <cmath>
@@ -48,7 +49,7 @@ class Gosu::Macro : public Gosu::ImageData
         
         // Since this matrix is relatively sparse, we unroll all three solving paths.
         
-        static const Transform nullTransform = { 0 };
+        static const Transform nullTransform = {{ 0 }};
         
         // Row 7 is completely useless
         if (x2 == x4 && x3 == x4)
@@ -154,12 +155,12 @@ class Gosu::Macro : public Gosu::ImageData
         
         // Let's hope I never have to debug/understand this again! :D
         
-        Transform result = {
+        Transform result = {{
             c[0], c[3], 0, c[6],
             c[1], c[4], 0, c[7],
             0, 0, 1, 0,
             c[2], c[5], 0, 1
-        };
+        }};
         return result;
     }
     
@@ -211,7 +212,7 @@ public:
         double x4, double y4, Color c4,
         ZPos z, AlphaMode mode) const
     {
-        if (c1 != 0xffffffff || c2 != 0xffffffff || c3 != 0xffffffff || c4 != 0xffffffff)
+        if (c1 != Color::WHITE || c2 != Color::WHITE || c3 != Color::WHITE || c4 != Color::WHITE)
             throw std::invalid_argument("Macros cannot be tinted with colors yet");
         std::tr1::function<void()> f = std::tr1::bind(&Macro::drawVertexArrays, this, x1, y1, x2, y2, x3, y3, x4, y4);
         graphics.scheduleGL(f, z);
@@ -227,9 +228,9 @@ public:
         throw std::logic_error("Gosu::Macro cannot be rendered as Gosu::Bitmap yet");
     }
     
-    std::auto_ptr<ImageData> subimage(int x, int y, int width, int height) const
+    GOSU_UNIQUE_PTR<ImageData> subimage(int x, int y, int width, int height) const
     {
-        return std::auto_ptr<ImageData>();
+        return GOSU_UNIQUE_PTR<ImageData>();
     }
     
     void insert(const Bitmap& bitmap, int x, int y)

data/GosuImpl/Graphics/TexChunk.cpp

@@ -76,9 +76,9 @@ Gosu::Bitmap Gosu::TexChunk::toBitmap() const
     return texture->toBitmap(x, y, w, h);
 }
 
-std::auto_ptr<Gosu::ImageData> Gosu::TexChunk::subimage(int x, int y, int width, int height) const
+GOSU_UNIQUE_PTR<Gosu::ImageData> Gosu::TexChunk::subimage(int x, int y, int width, int height) const
 {
-    return std::auto_ptr<Gosu::ImageData>(new TexChunk(*this, x, y, width, height));
+    return GOSU_UNIQUE_PTR<Gosu::ImageData>(new TexChunk(*this, x, y, width, height));
 }
 
 void Gosu::TexChunk::insert(const Bitmap& original, int x, int y)

data/GosuImpl/Graphics/TexChunk.hpp

@@ -50,7 +50,7 @@ public:
         
     const GLTexInfo* glTexInfo() const;
     Gosu::Bitmap toBitmap() const;
-    std::auto_ptr<ImageData> subimage(int x, int y, int width, int height) const;
+    GOSU_UNIQUE_PTR<ImageData> subimage(int x, int y, int width, int height) const;
     void insert(const Bitmap& bitmap, int x, int y);
 };
 

data/GosuImpl/Graphics/Texture.cpp

@@ -63,11 +63,11 @@ GLuint Gosu::Texture::texName() const
     return name;
 }
 
-std::auto_ptr<Gosu::TexChunk>
+GOSU_UNIQUE_PTR<Gosu::TexChunk>
     Gosu::Texture::tryAlloc(Graphics& graphics, DrawOpQueueStack& queues,
         std::tr1::shared_ptr<Texture> ptr, const Bitmap& bmp, unsigned padding)
 {
-    std::auto_ptr<Gosu::TexChunk> result;
+    GOSU_UNIQUE_PTR<Gosu::TexChunk> result;
     
     BlockAllocator::Block block;
     if (!allocator.alloc(bmp.width(), bmp.height(), block))
@@ -80,7 +80,7 @@ std::auto_ptr<Gosu::TexChunk>
     glTexSubImage2D(GL_TEXTURE_2D, 0, block.left, block.top, block.width, block.height,
                  Color::GL_FORMAT, GL_UNSIGNED_BYTE, bmp.data());
 
-    return result;
+    return GOSU_MOVE_UNIQUE_PTR(result);
 }
 
 void Gosu::Texture::block(unsigned x, unsigned y, unsigned width, unsigned height)

data/GosuImpl/Graphics/Texture.hpp

@@ -21,7 +21,7 @@ namespace Gosu
         ~Texture();
         unsigned size() const;
         GLuint texName() const;
-        std::auto_ptr<TexChunk> 
+        GOSU_UNIQUE_PTR<TexChunk>
             tryAlloc(Graphics& graphics, DrawOpQueueStack& queues,
                 std::tr1::shared_ptr<Texture> ptr, const Bitmap& bmp, unsigned padding);
         void block(unsigned x, unsigned y, unsigned width, unsigned height);

data/GosuImpl/Iconv.hpp

@@ -3,12 +3,7 @@
 
 #include <Gosu/Platform.hpp>
 
-#ifdef __APPLE__
-#include </usr/include/iconv.h> // We want Apple's iconv
-#else
 #include <iconv.h>
-#endif
-//#endif
 #include <errno.h>
 
 namespace Gosu

data/GosuImpl/InputTouch.mm

@@ -2,7 +2,6 @@
 #include <Gosu/TextInput.hpp>
 
 #include "MacUtility.hpp"
-#include "Orientation.hpp"
 #include "Input/AccelerometerReader.hpp"
 #import <UIKit/UIKit.h>
 
@@ -27,16 +26,7 @@ struct Gosu::Input::Impl
     Touch translateTouch(UITouch* uiTouch)
     {
         CGPoint point = [uiTouch locationInView: view];
-        Touch touch = { uiTouch, point.y, point.x };
-        switch (currentOrientation())
-        {
-        case orLandscapeLeft:
-            touch.y = [view bounds].size.width - touch.y;
-            break;
-        default:
-            touch.x = [view bounds].size.height - touch.x;
-            break;
-        }
+        Touch touch = { uiTouch, point.x, point.y };
         touch.x *= factorX, touch.y *= factorY;
         return touch;
     }
@@ -77,7 +67,7 @@ void Gosu::Input::feedTouchEvent(int type, void* touches)
         [pimpl->currentTouchesSet.get() minusSet: uiTouches], f = &onTouchEnded;
     for (UITouch* uiTouch in uiTouches)
         if (*f)
-            (*f)(pimpl->translateTouch(uiTouch));        
+            (*f)(pimpl->translateTouch(uiTouch));
 }
 
 wchar_t Gosu::Input::idToChar(Button btn)

data/GosuImpl/WindowTouch.mm

@@ -8,6 +8,10 @@
 #import <CoreGraphics/CoreGraphics.h>
 #import <UIKit/UIKit.h>
 #import <OpenGLES/EAGL.h>
+#import <QuartzCore/QuartzCore.h>
+
+#include <OpenAL/alc.h>
+#include <AudioToolbox/AudioSession.h>
 
 using namespace std::tr1::placeholders;
 
@@ -28,6 +32,17 @@ namespace Gosu
     {
         return screenRect().size.height;
     }
+    
+    ALCcontext *sharedContext();
+}
+
+static void handleAudioInterruption(void *unused, UInt32 inInterruptionState)
+{
+    if (inInterruptionState == kAudioSessionBeginInterruption) {
+        alcMakeContextCurrent(NULL);
+    } else if (inInterruptionState == kAudioSessionEndInterruption) {
+        alcMakeContextCurrent(Gosu::sharedContext());
+    }
 }
 
 int main(int argc, char *argv[])
@@ -51,7 +66,6 @@ struct Gosu::Window::Impl
     ObjRef<UIWindow> window;
     ObjRef<GosuViewController> controller;
     std::auto_ptr<Graphics> graphics;
-    std::auto_ptr<Audio> audio;
     std::auto_ptr<Input> input;
     double interval;
 };
@@ -67,36 +81,43 @@ namespace
     GosuView* gosuView = nil;
     bool pausedSong = false;
     bool paused = false;
-}
-
-@implementation GosuAppDelegate
-// Required according to docs...
-- (void)applicationProtectedDataWillBecomeUnavailable:(UIApplication *)application {
-}
 
-// Required according to docs...
-- (void)applicationProtectedDataDidBecomeAvailable:(UIApplication *)application {
+    id timerOrDisplayLink = nil;
 }
 
-// Required according to docs...
-- (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
+@implementation GosuAppDelegate
+- (void)setupTimerOrDisplayLink
+{
+    if (timerOrDisplayLink)
+        return;
+    
+    NSInteger targetFPS = round(1000.0 / windowInstance().updateInterval());
+        
+    if (60 % targetFPS != 0) {
+        NSTimer *timer = [NSTimer scheduledTimerWithTimeInterval:windowInstance().updateInterval() / 1000.0 target:self selector:@selector(doTick:) userInfo:nil repeats:YES];
+        
+        timerOrDisplayLink = [timer retain];
+    }
+    else {
+        CADisplayLink *displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(doTick:)];
+        displayLink.frameInterval = 60 / targetFPS;
+        [displayLink addToRunLoop:[NSRunLoop mainRunLoop] forMode:NSRunLoopCommonModes];
+        
+        timerOrDisplayLink = [displayLink retain];
+    }
 }
 
-- (void)applicationDidFinishLaunching:(UIApplication *)application {
-    [UIDevice.currentDevice beginGeneratingDeviceOrientationNotifications];
-    //UIApplication.sharedApplication.idleTimerDisabled = YES;
-    UIApplication.sharedApplication.statusBarOrientation = UIInterfaceOrientationLandscapeRight;
-        
-    [[NSTimer scheduledTimerWithTimeInterval: windowInstance().updateInterval() / 1000.0
-              target: self
-              selector: @selector(doTick:)
-              userInfo: nil
-              repeats: YES] retain];
+- (void)applicationDidFinishLaunching:(UIApplication *)application
+{
+    [UIApplication sharedApplication].statusBarHidden = YES;
+    [self setupTimerOrDisplayLink];
+    
+    AudioSessionInitialize(NULL, NULL, handleAudioInterruption, NULL);
 }
 
-- (void)applicationWillResignActive:(UIApplication *)application {
-	if (Gosu::Song::currentSong())
-    {
+- (void)applicationWillResignActive:(UIApplication *)application
+{
+	if (Gosu::Song::currentSong()) {
         Gosu::Song::currentSong()->pause();
         pausedSong = true;
     }
@@ -104,9 +125,9 @@ namespace
     windowInstance().loseFocus();
 }
 
-- (void)applicationDidBecomeActive:(UIApplication *)application {
-	if (pausedSong)
-    {
+- (void)applicationDidBecomeActive:(UIApplication *)application
+{
+	if (pausedSong) {
         if (Gosu::Song::currentSong())
             Gosu::Song::currentSong()->play();
         pausedSong = false;
@@ -114,7 +135,20 @@ namespace
     paused = false;
 }
 
-- (void)doTick:(NSTimer*)timer {
+- (void)applicationDidEnterBackground:(UIApplication *)application
+{
+    [timerOrDisplayLink invalidate];
+    [timerOrDisplayLink release];
+    timerOrDisplayLink = nil;
+}
+
+- (void)applicationWillEnterForeground:(UIApplication *)application
+{
+    [self setupTimerOrDisplayLink];
+}
+
+- (void)doTick:(id)sender
+{
     if (!paused)
         windowInstance().update();
     [gosuView drawView];
@@ -130,18 +164,18 @@ Gosu::Window::Window(unsigned width, unsigned height,
 	pimpl->window.reset([[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]]);
     pimpl->controller.reset([[GosuViewController alloc] init]);
     gosuView = (GosuView*)pimpl->controller.obj().view;
-	[pimpl->window.obj() addSubview: gosuView];
+    pimpl->window.obj().rootViewController = pimpl->controller.obj();
     
-    pimpl->graphics.reset(new Graphics(screenWidth(), screenHeight(), false));
+    pimpl->graphics.reset(new Graphics(screenHeight(), screenWidth(), false));
     pimpl->graphics->setResolution(screenHeight(), screenWidth());
-    pimpl->audio.reset(new Audio());
     pimpl->input.reset(new Input(gosuView, updateInterval));
     pimpl->input->onTouchBegan = std::tr1::bind(&Window::touchBegan, this, _1);
     pimpl->input->onTouchMoved = std::tr1::bind(&Window::touchMoved, this, _1);
     pimpl->input->onTouchEnded = std::tr1::bind(&Window::touchEnded, this, _1);
     pimpl->interval = updateInterval;
 
-    [pimpl->window.obj() makeKeyAndVisible];
+    // TODO: Get rid of performSelector:withObject:afterDelay:, without causing a C++ static initialization error
+    [pimpl->window.obj() performSelector:@selector(makeKeyAndVisible) withObject:nil afterDelay:0];
 }
 
 Gosu::Window::~Window()
@@ -174,12 +208,14 @@ Gosu::Graphics& Gosu::Window::graphics()
 
 const Gosu::Audio& Gosu::Window::audio() const
 {
-    return *pimpl->audio;
+    static Gosu::Audio audio;
+    return audio;
 }
 
 Gosu::Audio& Gosu::Window::audio()
 {
-    return *pimpl->audio;
+    static Gosu::Audio audio;
+    return audio;
 }
 
 const Gosu::Input& Gosu::Window::input() const

data/GosuImpl/WindowWin.cpp

@@ -177,8 +177,8 @@ struct Gosu::Window::Impl
 {
     HWND handle;
     HDC hdc;
-    std::auto_ptr<Graphics> graphics;
-    std::auto_ptr<Input> input;
+    GOSU_UNIQUE_PTR<Graphics> graphics;
+    GOSU_UNIQUE_PTR<Input> input;
     double updateInterval;
     bool iconified;
 

data/GosuImpl/WindowX.cpp

@@ -93,8 +93,8 @@ namespace Gosu
 
 struct Gosu::Window::Impl
 {
-    std::auto_ptr<Graphics> graphics;
-    std::auto_ptr<Input> input;
+    GOSU_UNIQUE_PTR<Graphics> graphics;
+    GOSU_UNIQUE_PTR<Input> input;
 
     ::Display* display;
     
@@ -169,7 +169,7 @@ struct Gosu::Window::Impl
                     active = false;
             }
             if (event.type == Expose && event.xexpose.count == 0 &&
-                        window->graphics().begin(Colors::black)) {
+                        window->graphics().begin(Color::BLACK)) {
                 FPS::registerFrame();
                 window->draw();
                 window->graphics().end();
@@ -192,7 +192,7 @@ struct Gosu::Window::Impl
         window->input().update();
         window->update();
 
-        if (window->needsRedraw() && window->graphics().begin(Colors::black))
+        if (window->needsRedraw() && window->graphics().begin(Color::BLACK))
         {
             FPS::registerFrame();
             window->draw();

data/linux/extconf.rb

@@ -69,6 +69,9 @@ OGG_VORBIS_FILES = Dir['../dependencies/libogg/src/*.c'] +
 require 'mkmf'
 require 'fileutils'
 
+# Silence internal deprecation warnings in Gosu
+$CFLAGS << " -DGOSU_DEPRECATED="
+
 $INCFLAGS << " -I../ -I../GosuImpl"
 
 if `uname`.chomp == 'Darwin' then
@@ -81,14 +84,19 @@ if `uname`.chomp == 'Darwin' then
   $INCFLAGS  << " -I../dependencies/libvorbis/include"
   $INCFLAGS  << " -I../dependencies/libvorbis/lib"
   # To make everything work with the Objective C runtime
-  $CFLAGS    << " -x objective-c -fobjc-gc -DNDEBUG"
+  $CFLAGS    << " -x objective-c -DNDEBUG"
   # Compile all C++ files as Objective C++ on OS X since mkmf does not support .mm
   # files.
   # Also undefine two debug flags that cause exceptions to randomly crash
   # otherwise; see:
   # https://trac.macports.org/ticket/27237#comment:21
   # http://newartisans.com/2009/10/a-c-gotcha-on-snow-leopard/#comment-893
-  CONFIG['CXXFLAGS'] =  "#{CONFIG['CXXFLAGS']} -x objective-c++ -U_GLIBCXX_DEBUG -U_GLIBCXX_DEBUG_PEDANTIC"
+  CONFIG['CXXFLAGS'] = "#{CONFIG['CXXFLAGS']} -x objective-c++ -U_GLIBCXX_DEBUG -U_GLIBCXX_DEBUG_PEDANTIC"
+  if `uname -r`.to_i >= 13 then
+    # Use C++11 on Mavericks and above
+    # TODO: This can probably be enabled starting from 10.6?
+    CONFIG['CXXFLAGS'] << " -std=gnu++11"
+  end
   $LDFLAGS   << " -L/usr/X11/lib -liconv"
   %w(AudioToolbox IOKit OpenAL OpenGL AppKit ApplicationServices Foundation Carbon).each do |f|
     $LDFLAGS << " -framework #{f}"

data/reference/gosu.rb

@@ -1,11 +1,20 @@
-# Version string of the form "0.1.2" or "0.1.2.3".
-GOSU_VERSION = :a_string
-# First component of the version.
+##
+# The first component of the version.
 GOSU_MAJOR_VERSION = :a_fixnum
-# Second component of the version.
+
+##
+# The second component of the version.
 GOSU_MINOR_VERSION = :a_fixnum
-# Third component of the version.
+
+##
+# The third component of the version.
 GOSU_POINT_VERSION = :a_fixnum
+
+##
+# A version string of the form "0.1.2" or "0.1.2.3".
+GOSU_VERSION = "#{GOSU_MAJOR_VERSION}.#{GOSU_MINOR_VERSION}.#{GOSU_POINT_VERSION}"
+
+##
 # A long block of legal copy that your game is obliged to display somewhere.
 GOSU_COPYRIGHT_NOTICE = :a_string
 
@@ -50,8 +59,11 @@ module Gosu
   KbDelete = :implementation_defined
   KbDown = :implementation_defined
   KbEnd = :implementation_defined
-  # On Numpad
+  
+  ##
+  # This is the key on the numpad.
   KbEnter = :implementation_defined
+  
   KbEscape = :implementation_defined
   KbF1 = :implementation_defined
   KbF10 = :implementation_defined
@@ -87,8 +99,11 @@ module Gosu
   KbNumpadSubtract = :implementation_defined
   KbPageDown = :implementation_defined
   KbPageUp = :implementation_defined
-  # Above the right shift key
+  
+  ##
+  # This is the key above the right shift key.
   KbReturn = :implementation_defined
+  
   KbRight = :implementation_defined
   KbRightAlt = :implementation_defined
   KbRightControl = :implementation_defined
@@ -222,284 +237,555 @@ module Gosu
   Gp3Left = :implementation_defined
   Gp3Right = :implementation_defined
   Gp3Up = :implementation_defined
-
-  # Represents an ARGB color value with 8 bits for each channel. Can be
-  # replaced by literals of the form 0xaarrggbb in all of Gosu.
+  
+  ##
+  # Represents an ARGB color value with 8 bits for each channel. Colors can be used interchangeably with integer literals of the form 0xAARRGGBB in all Gosu APIs.
   class Color
-    attr_accessor :alpha, :red, :green, :blue, :hue, :saturation, :value
+    ##
+    # @return [Fixnum] the color's alpha channel.
+    attr_accessor :alpha
     
-    # a:: Integer from 0..255
-    # r:: Integer from 0..255
-    # g:: Integer from 0..255
-    # b:: Integer from 0..255
-    def initialize(a, r, g, b); end
-    # Initializes a color from an 0xrrggbbaa integer.
-    def initialize(argb); end
+    ##
+    # @return [Fixnum] the color's red channel.
+    attr_accessor :red
     
-    def dup; end
+    ##
+    # @return [Fixnum] the color's green channel.
+    attr_accessor :green
+    
+    ##
+    # @return [Fixnum] the color's blue channel.
+    attr_accessor :blue
+    
+    ##
+    # @return [Fixnum] the color's hue in the range (0...360).
+    attr_accessor :hue
+    
+    ##
+    # @return [Float] the color's saturation in the range (0..1).
+    attr_accessor :saturation
     
-    # Same as the constructor, but with an explicit order.
-    def self.rgba(r, g, b, a); end    
+    ##
+    # @return [Float] the color's value in the range (0..1).
+    attr_accessor :value
     
-    # Initializes a color from an 0xrrggbbaa integer.
-    def self.rgba(rgba); end    
+    # @!group Creating colors.
     
-    # Same as the constructor, but with an explicit order.
-    def self.argb(a, r, g, b); end    
+    ##
+    # @overload initialize(argb)
+    #   @param argb [Fixnum] an integer of the form 0xAARRGGBB.
+    # 
+    # @overload initialize(a, r, g, b)
+    #   @param a [Fixnum] the color's alpha channel in the range (0..255).
+    #   @param r [Fixnum] the color's red channel in the range (0..255).
+    #   @param g [Fixnum] the color's green channel in the range (0..255).
+    #   @param b [Fixnum] the color's blue channel in the range (0..255).
+    # 
+    # @see from_hsv
+    # @see from_ahsv
+    # @see rgba
+    # @see argb
+    def initialize(*args); end
     
-    # Initializes a color from an 0xrrggbbaa integer.
-    def self.argb(argb); end    
+    ##
+    # @return (see #initialize)
+    # 
+    # @overload rgba(rgba)
+    #   @param argb [Fixnum] an integer of the form 0xRRGGBBAA.
+    # 
+    # @overload rgba(r, g, b, a)
+    #   @param r [Fixnum] the color's red channel in the range (0..255).
+    #   @param g [Fixnum] the color's green channel in the range (0..255).
+    #   @param b [Fixnum] the color's blue channel in the range (0..255).
+    #   @param a [Fixnum] the color's alpha channel in the range (0..255).
+    # 
+    # @see #initialize
+    # @see argb
+    def self.rgba(*args); end
     
-    # Converts a HSV triple into a color. Same as from_ahsv with alpha set to 255.
-    # h:: Integer from 0..360
-    # s:: Float from 0..1
-    # v:: Float from 0..1.
+    # This method is equivalent to calling `Color.new`, but the name makes the parameter order explicit.
+    # 
+    # @return (see #initialize)
+    # @overload argb(argb)
+    # @overload argb(a, r, g, b)
+    # 
+    # @see #initialize
+    # @see rgba
+    def self.argb(*args); end
+    
+    # Converts an HSV triplet to an opaque color.
+    # 
+    # @return [Color] a color corresponding to the HSV triplet.
+    # @param h [Fixnum] the color's hue in the range (0..360).
+    # @param s [Float] the color's saturation in the range (0..1).
+    # @param v [Float] the color's value in the range (0..1).
+    # 
+    # @see from_ahsv
     def self.from_hsv(h, s, v); end
     
-    # Converts a HSV triple into a color, with a given alpha.
-    # a:: Integer from 0..255
-    # h:: Integer from 0..360
-    # s:: Float from 0..1
-    # v:: Float from 0..1.
+    # Converts an HSV triplet to a color with the alpha channel set to a given value.
+    # 
+    # @return (see from_hsv)
+    # @param a [Fixnum] the color's opacity in the range (0..255).
+    # @param (see from_hsv)
+    # 
+    # @see from_hsv
     def self.from_ahsv(a, h, s, v); end
     
-    # 32-bit unsigned value for use with OpenGL ('RGBA' octet in memory).
+    # @!endgroup
+    
+    # Returns a 32-bit representation of the color suitable for use with OpenGL calls. This color is stored in a fixed order in memory and its integer value may vary depending on your system's byte order.
+    # 
+    # @return [Fixnum] a 32-bit OpenGL color.
     def gl; end
     
-    # constant
+    ##
+    # @return [Color] a copy of the color.
+    def dup; end
+    
     NONE    = Gosu::Color.argb(0x00000000)
-    # constant
     BLACK   = Gosu::Color.argb(0xff000000)
-    # constant
     GRAY    = Gosu::Color.argb(0xff808080)
-    # constant
-    WHITE   = Gosu::Color.argb(0xffffffff)            
-    # constant
+    WHITE   = Gosu::Color.argb(0xffffffff)
     AQUA    = Gosu::Color.argb(0xff00ffff)
-    # constant
     RED     = Gosu::Color.argb(0xffff0000)
-    # constant
     GREEN   = Gosu::Color.argb(0xff00ff00)
-    # constant
     BLUE    = Gosu::Color.argb(0xff0000ff)
-    # constant
     YELLOW  = Gosu::Color.argb(0xffffff00)
-    # constant
     FUCHSIA = Gosu::Color.argb(0xffff00ff)
-    # constant
     CYAN    = Gosu::Color.argb(0xff00ffff)
   end
   
+  ##
   # A font can be used to draw text on a Window object very flexibly.
   # Fonts are ideal for small texts that change regularly. For large,
-  # static texts you should use Image#from_text.
+  # static texts you should use {Gosu::Image#from_text}.
   class Font
-    attr_reader :name, :height
+    ##
+    # The font's name. This may be the name of a system font or a filename.
+    # 
+    # @return [String] the font's name.
+    attr_reader :name
     
-    # font_name:: Name of a system font, or a filename to a TTF file (must contain '/').
-    # height:: Height of the font, in pixels.
+    ##
+    # @return [Fixnum] The font's height in pixels.
+    attr_reader :height
+    
+    ##
+    # Load a font from the system fonts or a file.
+    # 
+    # @param window [Gosu::Window]
+    # @param font_name [String] the name of a system font, or a path to a TrueType Font (TTF) file. A path must contain at least one '/' character to distinguish it from a system font.
+    # @param height [Fixnum] the height of the font, in pixels.
     def initialize(window, font_name, height); end
     
-    # Sets the image to be used for a certain character. Must not be called twice for the same character, or after the character has been drawn already.
+    ##
+    # Overrides the image for a character.
+    # 
+    # @note For any given character, this method MUST NOT be called more than once, and MUST NOT be called if a string containing the character has already been drawn.
+    # 
+    # @return [void]
+    # @param character [String] the character to replace.
+    # @param image [Image] the image to use for the character.
     def []=(character, image); end
     
-    # Draws text so the top left corner of the text is at (x; y).
-    #
-    # Characters are created internally as needed.
+    # @!group Drawing text
+    
+    ##
+    # Draws a single line of text with its top left corner at (x, y).
+    # 
+    # @return [void]
+    # @param text [String]
+    # @param x [Number] the X coordinate
+    # @param y [Number] the Y coordinate
+    # @param z [Number] the Z-order.
+    # @param factor_x [Float] the horizontal scaling factor.
+    # @param factor_y [Float] the vertical scaling factor.
+    # @param color [Color, Fixnum]
+    # @param mode [:default, :additive] the blending mode to use.
+    # 
+    # @see #draw_rel
+    # @see Gosu::Image.from_text
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Z-Ordering.md
     def draw(text, x, y, z, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
     
-    # Draws text at a position relative to (x; y).
-    # rel_x:: Determines where the text is drawn horizontally. If relX is 0.0, the text will be to the right of x, if it is 1.0, the text will be to the left of x, if it is 0.5, it will be centered on x. Of course, all real numbers are possible values.
-    # rel_y:: See rel_x.
+    ##
+    # Draws a single line of text relative to (x, y).
+    # 
+    # The text is aligned to the drawing location according to the `rel_x` and `rel_y` parameters: a value of 0.0 corresponds to top and left, while 1.0 corresponds to bottom and right. A value of 0.5 naturally corresponds to the center of the text.
+    # 
+    # All real numbers are valid alignment values and will be interpolated (or extrapolated) accordingly.
+    # 
+    # @return [void]
+    # @param rel_x [Float] the horizontal alignment.
+    # @param rel_y [Float] the vertical alignment.
+    # @param (see #draw)
+    # 
+    # @see #draw
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Z-Ordering.md
     def draw_rel(text, x, y, z, rel_x, rel_y, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
     
-    # Returns the width, in pixels, the given text would occupy if drawn.
-    def text_width(text, factor_x=1); end
-    
-    # Analogous to draw, but rotates the text by a given angle.
-    # @deprecated Use a combination of Window#rotate and Font#draw instead.
+    ##
+    # @deprecated Use {#draw} in conjunction with {Window#rotate} instead.
+    # 
+    # @see #draw
+    # @see Gosu::Window#rotate
     def draw_rot(text, x, y, z, angle, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
+    
+    # @!endgroup
+    
+    ##
+    # Returns the width of a single line of text, in pixels, if it were drawn.
+    # 
+    # @return [Fixnum] the width of the text, in pixels.
+    # @param text [String]
+    def text_width(text, factor_x=1); end
   end
   
+  ##
   # Provides functionality for drawing rectangular images.
   class Image
-    attr_reader :width, :height
+    ##
+    # @return [Fixnum] the image's width, in pixels.
+    attr_reader :width
+    
+    ##
+    # @return [Fixnum] the image's height, in pixels.
+    attr_reader :height
     
-    # Loads an image from a given filename that can be drawn onto the
-    # given window. See the Gosu wiki for a list of supported formats.
+    # @!group Creating and loading images
+    
+    ##
+    # Loads an image from a file or an RMagick image.
+    # 
+    # @note For Windows Bitmap (BMP) images, magenta (FF00FF, often called "magic pink" in this context) is treated as a chroma key and all pixels of that color are automatically rendered fully transparent.
     #
-    # A color key of #ff00ff is automatically applied to BMP type images.
-    def initialize(window, filename_or_rmagick_image, tileable); end
+    # @param window [Window]
+    # @param source [String, Magick::Image] the filename or RMagick image to load from.
+    # @param tileable [true, false]
+    # @param left [Fixnum]
+    # @param top [Fixnum]
+    # @param width [Fixnum]
+    # @param height [Fixnum]
+    # 
+    # @overload initialize(window, source, tileable)
+    # @overload initialize(window, source, tileable, left, top, width, height)
+    #   Loads a rectangular slice of the image.
+    #   
+    #   If you need to load multiple tiles from a texture atlas, {load_tiles} is almost always a better choice.
+    #   
+    # 
+    # @see load_tiles
+    # @see from_text
+    # @see file:reference/Tileability.md
+    def initialize(window, source, tileable, left, top, width, height); end
     
-    # Loads an image from a given filename that can be drawn onto the
-    # given window. See the Gosu wiki for a list of supported formats.
+    ##
+    # Creates a reusable image from one or more lines of text.
     #
-    # A color key of #ff00ff is automatically applied to BMP type images.
+    # The text is always rendered in white. To draw it in a different color, use the `color` parameter of {#draw}, et al.
+    # 
+    # @overload from_text(window, text, font_name, font_height)
+    # @overload from_text(window, text, font_name, font_height, line_spacing, width, align)
+    # 
+    # @return [Gosu::Image]
+    # @param window [Gosu::Window]
+    # @param text [String]
+    # @param font_name [String] the name of a system font, or a path to a TrueType Font (TTF) file. A path must contain at least one '/' character to distinguish it from a system font.
+    # @param font_height [Fixnum] the height of the font, in pixels.
+    # @param line_spacing [Fixnum] the vertical spacing beteen lines.
+    # @param width [Fixnum] the width of the image, in pixels. Long lines will be automatically wrapped around to avoid overflow, but overlong words will be truncated.
+    # @param align [:left, :right, :center, :justify] the text alignment.
+    # 
+    # @see Gosu::Font
+    def self.from_text(window, text, font_name, font_height, line_spacing, width, align); end
+    
+    ##
+    # Loads an image from a file or an RMagick image, then divides the image into an array of equal-sized tiles.
+    # 
+    # @note For Windows Bitmap (BMP) images, magenta (FF00FF, often called "magic pink" in this context) is treated as a chroma key and all pixels of that color are automatically rendered fully transparent.
     #
-    # This constructor only loads a sub-rectangle of the given file. Because
-    # every call of this constructor will open the image again, it is preferable
-    # to use Image#load_tiles when possible.
-    def initialize(window, filename_or_rmagick_image, tileable, src_x, src_y, src_width, src_height); end
+    # @return [Array<Gosu::Image>]
+    # @param window [Window]
+    # @param source [String, Magick::Image]
+    # @param tile_width [Fixnum] If positive, this is the width of the individual tiles; if negative, the image is divided into -tile_width columns.
+    # @param tile_height [Fixnum] If positive, this is the height of the individual tiles; if negative, the image is divided into -tile_height rows.
+    # @param tileable [true, false]
+    # 
+    # @see file:reference/Tileability.md
+    def self.load_tiles(window, source, tile_width, tile_height, tileable); end
+    
+    # @!endgroup
+    
+    # @!group Drawing an image
     
-    # Draws the image so its upper left corner is at (x; y).
+    ##
+    # Draws the image with its top left corner at (x, y).
+    # 
+    # @return [void]
+    # @param x [Float] the X coordinate.
+    # @param y [Float] the X coordinate.
+    # @param z [Float] the Z-order.
+    # @param factor_x [Float] the horizontal scaling factor.
+    # @param factor_y [Float] the vertical scaling factor.
+    # @param color [Gosu::Color, Integer]
+    # @param mode [:default, :additive] the blending mode to use.
+    # 
+    # @see #draw_rot
+    # @see #draw_as_quad
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Z-Ordering.md
     def draw(x, y, z, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
     
-    # center_x:: Relative horizontal position of the rotation center on the image. 0 is the left border, 1 is the right border, 0.5 is the center (and default)
-    # center_y:: See center_x.
+    ##
+    # Draws the image rotated, with its rotational center at (x, y).
+    # 
+    # @return [void]
+    # @param angle [Float]
+    # @param center_x [Float] the relative horizontal rotation origin.
+    # @param center_y [Float] the relative vertical rotation origin.
+    # @param (see #draw)
+    # 
+    # @see #draw
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Z-Ordering.md
     def draw_rot(x, y, z, angle, center_x=0.5, center_y=0.5, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
     
-    # Like Window#draw_quad, but with this texture instead of colors. Can be used to implement advanced, non-rectangular drawing techniques and takes four points and the modulation color at each of them.
-    # The points can be in clockwise order, or in a Z shape, starting at the top left.
+    ##
+    # Draws the image as an arbitrary quad. This method can be used for advanced non-rectangular drawing techniques, e.g., faking perspective or isometric projection.
+    # 
+    # @return [void]
+    # @param (see Gosu::Window#draw_quad)
+    # 
+    # @see #draw
+    # @see Gosu::Window#draw_quad
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Order_of_Corners.md Order of Corners
+    # @see file:reference/Z-Ordering.md
     def draw_as_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z, mode=:default); end
     
-    # Creates an Image containing a line of text.
-    #
-    # The text is always rendered in white. If you want to draw it in a
-    # different color, just modulate it by the target color.
-    # font_name:: Name of a system font, or a filename to a TTF file (must contain '/').
-    # font_height:: Height of the font in pixels.
-    def self.from_text(window, text, font_name, font_height); end
-    
-    # Creates an Image that is filled with the text given to the function.
-    #
-    # The text may contain line breaks.
-    #
-    # The text is always rendered in white. If you want to draw it in a
-    # different color, just modulate it by the target color.
-    # font_name:: Name of a system font, or a filename to a TTF file (must contain '/').
-    # font_height:: Height of the font in pixels.
-    # line_spacing:: Spacing between two lines of text in pixels.
-    # max_width:: Width of the bitmap that will be returned. Text will be split into multiple lines to avoid drawing over the right border. When a single word is too long, it will be truncated.
-    # align:: One of :left, :right, :center or :justify.
-    def self.from_text(window, text, font_name, font_height, line_spacing, max_width, align); end
-    
-    # Convenience function that splits an image file into an array of small rectangles and
-    # creates images from these. Returns the Array containing Image instances.
-    #
-    # A color key of #ff00ff is automatically applied to BMP type images.
-    #
-    # tile_width:: If positive, specifies the width of one tile in pixels. If negative, the bitmap is divided into -tile_width rows.
-    # tile_height:: See tile_width.
-    def self.load_tiles(window, filename_or_rmagick_image, tile_width, tile_height, tileable); end
+    # @!endgroup
     
-    # See examples/OpenGLIntegration.rb.
+    ##
+    # Returns an object that holds information about the underlying OpenGL texture and UV coordinates of the image.
+    # 
+    # @note Some images may be too large to fit on a single texture; this method returns nil in those cases.
+    # 
+    # @return [Gosu::GLTexInfo?] information about the underlying OpenGL texture.
+    # 
+    # @see Gosu::GLTexInfo
+    # @see file:examples/OpenGLIntegration.rb
     def gl_tex_info; end
     
-    # Returns the associated texture contents as binary string of RGBA values.
-    # Useful for use with RMagick (Magick::Image.from_blob).
+    ##
+    # Returns the associated texture contents as binary string of packed RGBA values, useful for use with RMagick (Magick::Image.from_blob).
+    # 
+    # @return [String] a binary string of packed RGBA values.
     def to_blob; end
     
-    # Overwrites all or parts of the Image. x and y can be negative or otherwise out of
-    # bounds, the incoming image data is clipped to the current image size.
+    ##
+    # Overwrites part of the image with the contents of another. If the source image is partially out of bounds, it will be clipped to fit.
+    # 
     # This can be used to e.g. overwrite parts of a landscape.
-    def insert(filename_or_rmagick_image, x, y); end
+    # 
+    # @return [void]
+    # @param source [String, Magick::Image] the filename or RMagick image to load from.
+    # @param x [Fixnum] the X coordinate of the top left corner.
+    # @param y [Fixnum] the Y coordinate of the top left corner.
+    def insert(source, x, y); end
     
-    # Saves the texture contents as an image file. Useful, for example, to
-    # pre-render text on a development machine with proper fonts installed.
-    # The file format is determined from the file extension. See the Gosu
-    # wiki for a list of portably supported formats.
+    ##
+    # Saves the image to a file. The file format is determined from the file extension.
+    # 
+    # Useful for, e.g., pre-rendering text on a development machine where the necessary fonts are known to be available.
+    # 
+    # @return [void]
+    # @param filename [String] the path to save the file under.
     def save(filename); end
   end
   
+  ##
   # A sample is a short sound that is completely loaded in memory, can be
   # played multiple times at once and offers very flexible playback
   # parameters. Use samples for everything that's not music.
+  # 
+  # @see Gosu::Song
   class Sample
+    ##
+    # Loads a sample from a file.
+    # 
+    # @param window [Gosu::Window]
+    # @param filename [String] the path to load the sample from.
     def initialize(window, filename); end
     
+    ##
     # Plays the sample without panning.
+    # 
+    # Playback speed is limited only by the underlying audio library, and both very large and very small values should work just fine.
     #
-    # Returns a SampleInstance.
-    # volume:: Can be anything from 0.0 (silence) to 1.0 (full volume).
-    # speed:: Playback speed is only limited by the underlying audio library, and can accept very high or low values. Use 1.0 for normal playback speed.
-    def play(vol=1, speed=1, looping=false); end
-    
-    # Plays the sample with panning. Even if pan is 0.0, the sample will
-    # not be as loud as if it were played by calling play() due to the
-    # way the panning works.
+    # @return [SampleInstance]
+    # @param volume [Float] the playback volume, in the range (0..1), where 0 is completely silent and 1 is full volume.
+    # @param speed [Float] the playback speed.
+    # @param looping [true, false] whether the sample should play in a loop.
+    # 
+    # @see #play_pan
+    def play(volume=1, speed=1, looping=false); end
+    
+    ##
+    # Plays the sample with panning.
+    # 
+    # @note Samples played with this method will not be as loud as those played with {#play}, even if `pan` is 0. This is due to a limitation in the way panning works.
     #
-    # Returns a SampleInstance.
-    # volume:: Can be anything from 0.0 (silence) to 1.0 (full volume).
-    # speed:: Playback speed is only limited by the underlying audio library, and can accept very high or low values. Use 1.0 for normal playback speed.
-    def play_pan(pan=0, vol=1, speed=1, looping=false); end
+    # @return [SampleInstance]
+    # @param pan [Float] the amount of panning. 0 is centered.
+    # @param (see #play)
+    # 
+    # @see #play
+    def play_pan(pan=0, volume=1, speed=1, looping=false); end
   end
   
-  # An instance of a Sample playing. Can be used to stop sounds dynamically,
-  # or to check if they are finished.
-  # It is recommended that you throw away sample instances if possible,
-  # as they could accidentally refer to other sounds being played after
-  # a very long time has passed.
+  ##
+  # An instance of a {Gosu::Sample} playing. Can be used to stop sounds dynamically, or to check if they are finished.
+  # 
+  # It is recommended to throw away sample instances as soon as possible, as holding onto them for a long time can prevent unneeded samples being properly disposed.
   class SampleInstance
     attr_writer :volume
     attr_writer :speed
     attr_writer :pan
     
-    # Stops this instance of a sound being played. Calling this twice, or too late, does not do any harm. You can nil out the reference to the instance afterwards as it will be useless.
+    ##
+    # Stops playback of this sample instance. After calling this method, the sample instance is useless and can be discarded.
+    # 
+    # Calling `stop` after the sample has finished is harmless and has no effect.
+    # 
+    # @return [void]
     def stop; end
-    # Pauses this instance to be resumed afterwards. It will still keep a channel filled while paused.
+    
+    ##
+    # Pauses the sample, to be resumed afterwards.
+    # 
+    # @note The sample will still occupy a playback channel while paused.
+    # 
+    # @return [void]
     def pause; end
-    def paused?; end
+    
+    ##
+    # Resumes playback of the sample.
+    # 
+    # @return [void]
     def resume; end
+    
+    ##
+    # @return [true, false] whether the sample is paused.
+    def paused?; end
+    
+    ##
+    # @return [true, false] whether the sample is playing.
     def playing?; end
   end
   
-  # Songs are less flexible than samples in that they can only be played
-  # one at a time and without panning or speed parameters.
+  ##
+  # Songs are less flexible than samples in that only one can be played at a time, with no panning or speed control.
+  # 
+  # @see Gosu::Sample
   class Song
-    # Returns the song currently being played or paused, or nil if
-    # no song has been played yet or the last song has finished
-    # playing.
-    def self.current_song; end
-    
+    class <<Song
+      ##
+      # Returns the song currently being played (even if it's paused), or nil if no song is playing.
+      # 
+      # @return [Gosu::Song?] the currently playing song.
+      attr_reader :current_song
+    end
+  
+    ##
+    # @return [Float] the song's playback volume.
     attr_accessor :volume
     
+    ##
+    # Loads a song from a file.
+    # 
+    # @param window [Gosu::Window]
+    # @param filename [String] the path to load the song from.
     def initialize(window, filename); end
     
-    # Starts or resumes playback of the song. This will stop all other
-    # songs and set the current song to this object.
+    ##
+    # Starts or resumes playback of the song.
+    # 
+    # If another song is currently playing, it will be stopped and this song will be set as the current song.
+    # 
+    # If `looping` is false, the current song will be set to `nil` when this song finishes.
+    # 
+    # @return [void]
+    # @param looping [true, false] whether the song should play in a loop.
     def play(looping=false); end
     
-    # Pauses playback of the song. It is not considered being played.
-    # current_song will stay the same.
+    ##
+    # Pauses playback of the song. The current song is unchanged.
+    # 
+    # @return [void]
     def pause; end
     
-    # Returns true if the song is the current song, but in paused
-    # mode.
+    # Returns true if this song is the current song and playback is paused.
+    # 
+    # @return [true, false] whether the song is paused.
     def paused?; end
     
-    # Stops playback of this song if it is currently played or paused.
-    # Afterwards, current_song will return 0.
+    ##
+    # Stops playback if this song is the current song. The current song is set to `nil`.
+    # 
+    # @return [void]
     def stop; end
     
-    # Returns true if the song is currently playing.
+    ##
+    # @return [true, false] whether the song is playing.
     def playing?; end
   end
   
-  # TextInput instances are invisible objects that build a text string from input,
-  # using the current operating system's keyboard layout.
+  ##
+  # A TextInput is an invisible object that handles input using the operating system's input manager.
   #
-  # At its most basic form, you only need to create a new TextInput instance and
-  # pass it to your window via text_input=. Until you call this function again,
-  # passing nil, the TextInput object will build a text that can be accessed via
-  # TextInput#text.
+  # At its most basic, you only need to set {Gosu::Window#text_input} to an instance of this class. The TextInput will then handle all keyboard input until {Gosu::Window#text_input} is set to `nil`. Any text the user has typed is available through {#text}.
   #
-  # A TextInput object is purely abstract, though; drawing the input field is left
-  # to the user. As with most of Gosu, how this is handled is completely left open.
-  #
-  # TextInput only aims to provide enough code for your own GUIs to build upon.
+  # This class is purely back-end and does not come with a GUI; drawing the input field is up to you, the programmer. The best way to do that is left completely open. TextInput only aims to provide a foundation for you to build your own GUI.
+  # 
+  # @see Gosu::Window#text_input
+  # @see file:examples/TextInput.rb
   class TextInput
+    ##
+    # @return [String] the text that the user has typed.
     attr_accessor :text
+    
+    ##
+    # @return [Fixnum] the position of the editing caret.
     attr_accessor :caret_pos
+    
+    ##
+    # @return [Fixnum] the starting position of the currently selected text.
     attr_accessor :selection_start
     
-    # Overridable filter that is applied to all new text that is entered.
-    # Allows for context-sensitive filtering/extending/... of the text.
-    # The text will be inserted at caretPos afterwards.
+    ##
+    # This method is an overridable filter that is applied to all newly entered text. This allows for restricting input characters or format, automatic macro or abbreviation expansion and so on.
+    # 
+    # The return value of this method will be inserted at the current caret position.
+    # 
+    # The default implementation returns its argument unchanged.
+    # 
+    # @return [String] the string to be inserted.
+    # @param text_in [String] the text typed by the user.
+    # 
+    # @example Forcing input to all uppercase, alphanumeric characters.
+    #   input = TextInput.new
+    #   def input.filter(text_in)
+    #     text_in.upcase.gsub(/[^A-Z0-9]/, '')
+    #   end
     def filter text_in
       text_in
     end
   end
   
+  ##
   # Main class that serves as the foundation of a standard
   # Gosu application. Manages initialization of all of Gosu's core components
   # and provides timing functionality.
@@ -508,195 +794,491 @@ module Gosu
   # coordinates relative to the window. This means that the mouse position
   # can be negative or larger than the window size.
   #
-  # Note that you should really only use one instance of this class at the same time. This may or may not change later.
-  #
-  # Right now, having two or more windows and loading samples or songs on both of them will result in an exception.
+  # @note There should really only be one instance of this class at a time. This may or may not change later, but for right now, having two or more windows and loading samples or songs on both of them will result in an exception.
   class Window
+    ##
+    # @return [String] the window's caption, usually dispalyed in the title bar.
     attr_accessor :caption
+    
+    ##
+    # @return [Fixnum] the mouse pointer's window-based X coordinate.
     attr_accessor :mouse_x
+    
+    ##
+    # @return [Fixnum] the mouse pointer's window-based Y coordinate.
     attr_accessor :mouse_y
+    
+    ##
+    # The currently active {TextInput}. If not nil, all keyboard input will be handled by this object.
+    # 
+    # @return [TextInput?] the currently active text input.
     attr_accessor :text_input
-    attr_reader :width, :height
+    
+    ##
+    # The window's width, in pixels. This only counts the drawable area and does not include any borders or decorations added by the window manager.
+    # 
+    # @return [Fixnum] the window's width, in pixels.
+    attr_reader :width
+    
+    ##
+    # The window's height, in pixels. This only counts the drawable area and does not include any borders or decorations added by the window manager.
+    # 
+    # @return [Fixnum] the window's height, in pixels.
+    attr_reader :height
+    
+    ##
+    # @return [true, false] whether this is a full-screen window.
     attr_reader :fullscreen?
+    
+    ##
+    # @return [Float] the interval between calls to {#update}, in milliseconds.
     attr_reader :update_interval
     
-    # update_interval:: Interval in milliseconds between two calls
-    # to the update member function. The default means the game will run
-    # at 60 FPS, which is ideal on standard 60 Hz TFT screens.
+    ##
+    # Creates a new window with the requested size.
+    # 
+    # @note The actual window may be smaller if the requested size is too large for the current display resolution; in that case, Gosu will automatically scale all coordinates to transparently emulate a larger window. No need to thank us.
+    # 
+    # @param width [Fixnum] the desired window width.
+    # @param height [Fixnum] the desired window height.
+    # @param fullscreen [true, false] whether to create a full-screen window.
+    # @param update_interval [Float] the interval between calls to {#update}, in milliseconsd. For the default value of 16.666666, the game will attempt to run at approximately 60 FPS, which is ideal on standard 60 Hz TFT screens.
     def initialize(width, height, fullscreen, update_interval=16.666666); end
     
+    ##
     # Enters a modal loop where the Window is visible on screen and receives calls to draw, update etc.
+    # 
+    # @return [void]
     def show; end
     
-    # Tells the window to end the current show loop as soon as possible.
+    ##
+    # Tells the window to end the current run loop as soon as possible. Calling this method will not prevent execution of lines after it.
+    # 
+    # @return [void]
     def close; end 
     
-    # Called every update_interval milliseconds while the window is being
-    # shown. Your application's main game logic goes here.
+    # @!group Callbacks
+    
+    ##
+    # This method is called once every {#update_interval} milliseconds while the window is being shown. Your application's main logic should go here.
+    # 
+    # @return [void]
     def update; end
     
-    # Called after every update and when the OS wants the window to
-    # repaint itself. Your application's rendering code goes here.
+    ##
+    # This method is called after every update and whenever the OS wants the window to repaint itself. Your application's rendering code should go here.
+    # 
+    # @return [void]
+    # 
+    # @see #needs_redraw?
     def draw; end
     
-    # Can be overriden to give the game a chance to say no to being redrawn.
-    # This is not a definitive answer. The operating system can still cause
-    # redraws for one reason or another.
+    ##
+    # This method can be overriden to give the game a chance to opt out of a call to {#draw}; however, the operating system can still force a redraw for any reason.
     #
-    # By default, the window is redrawn all the time (i.e. Window#needs_redraw?
-    # always returns true.)
+    # @return [true, false] whether the window needs to be redrawn.
+    # 
+    # @see #draw
     def needs_redraw?; end
     
-    # Can be overriden to show the system cursor when necessary, e.g. in level
-    # editors or other situations where introducing a custom cursor is not
-    # desired.
+    ##
+    # This method can be overriden to control the visibility of the system cursor over your window, e.g., for level editors or other situations where introducing a custom cursor or hiding the default one is not desired.
+    # 
+    # @return [true, false] whether the system cursor should be shown.
     def needs_cursor?; end
     
-    # Called before update when the user pressed a button while the
-    # window had the focus.
+    ##
+    # This method is called before {#update} if a button was pressed while the window had focus.
+    # 
+    # @return [void]
+    # @param id [Fixnum] the button's platform-defined id.
+    # 
+    # @see #button_up
+    # @see #button_down?
     def button_down(id); end
-    # Same as buttonDown. Called then the user released a button.
+    
+    ##
+    # This method is called before {#update} if a button was released while the window had focus.
+    # 
+    # @return [void]
+    # @param (see #button_down)
+    # 
+    # @see #button_down
+    # @see #button_down?
     def button_up(id); end
     
-    # Returns true if a button is currently pressed. Updated every tick.
+    # @!endgroup
+    
+    ##
+    # Returns whether the button `id` is currently pressed. Button states are updated once per tick, so repeated calls during the same tick will always yeild the same result.
+    # 
+    # @return [true, false] whether the button is currently pressed.
+    # @param (see #button_down)
+    # 
+    # @see #button_down
+    # @see #button_up
     def button_down?(id); end
     
-    # Draws a line from one point to another (last pixel exclusive).
-    # Note: OpenGL lines are not reliable at all and may have a missing pixel at the start
-    # or end point. Please only use this for debugging purposes. Otherwise, use a quad or
-    # image to simulate lines, or contribute a better draw_line to Gosu.
+    # @!group Drawing primitives
+    
+    ##
+    # Draws a line from one point to another---inconsistently.
+    # 
+    # @note OpenGL lines are not reliable at all and may have a missing pixel at the start or end point. Relying on your machine's behavior can only end in tears. Recommended for debugging purposes only.
+    # 
+    # @return [void]
+    # @param x1 [Float] the X coordinate of the start point.
+    # @param y1 [Float] the Y coordinate of the start point.
+    # @param c1 [Gosu::Color] the color of the start point.
+    # @param x2 [Float] the X coordinate of the end point.
+    # @param y2 [Float] the Y coordinate of the end point.
+    # @param c2 [Gosu::Color] the color of the end point.
+    # @param z [Float] the Z-order.
+    # @param mode [:default, :additive] the blending mode to use.
+    # 
+    # @see #draw_triangle
+    # @see #draw_quad
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Z-Ordering.md
     def draw_line(x1, y1, c1, x2, y2, c2, z=0, mode=:default); end
     
+    ##
+    # Draws a triangle.
+    # 
+    # @return [void]
+    # @param x1 [Float] the X coordinate of the first vertex.
+    # @param y1 [Float] the Y coordinate of the first vertex.
+    # @param c1 [Gosu::Color] the color of the first vertex.
+    # @param x2 [Float] the X coordinate of the second vertex.
+    # @param y2 [Float] the Y coordinate of the second vertex.
+    # @param c2 [Gosu::Color] the color of the second vertex.
+    # @param x3 [Float] the X coordinate of the third vertex.
+    # @param y3 [Float] the Y coordinate of the third vertex.
+    # @param c3 [Gosu::Color] the color of the third vertex.
+    # @param z [Float] the Z-order.
+    # @param mode [:default, :additive] the blending mode to use.
+    #
+    # @see #draw_line
+    # @see #draw_quad
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Z-Ordering.md
     def draw_triangle(x1, y1, c1, x2, y2, c2, x3, y3, c3, z=0, mode=:default); end
     
-    # Draws a rectangle (two triangles) with given corners and corresponding
-    # colors.
-    # The points can be in clockwise order, or in a Z shape.
+    ##
+    # Draws a quad (actually two triangles).
+    # 
+    # @return [void]
+    # @param x1 [Float] the X coordinate of the first vertex.
+    # @param y1 [Float] the Y coordinate of the first vertex.
+    # @param c1 [Gosu::Color] the color of the first vertex.
+    # @param x2 [Float] the X coordinate of the second vertex.
+    # @param y2 [Float] the Y coordinate of the second vertex.
+    # @param c2 [Gosu::Color] the color of the second vertex.
+    # @param x3 [Float] the X coordinate of the third vertex.
+    # @param y3 [Float] the Y coordinate of the third vertex.
+    # @param c3 [Gosu::Color] the color of the third vertex.
+    # @param x4 [Float] the X coordinate of the fourth vertex.
+    # @param y4 [Float] the Y coordinate of the fourth vertex.
+    # @param c4 [Gosu::Color] the color of the fourth vertex.
+    # @param z [Float] the Z-order.
+    # @param mode [:default, :additive] the blending mode to use.
+    #
+    # @see #draw_line
+    # @see #draw_triangle
+    # @see file:reference/Drawing_with_Colors.md Drawing with Colors
+    # @see file:reference/Order_of_Corners.md Order of Corners
+    # @see file:reference/Z-Ordering.md
     def draw_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z=0, mode=:default); end
     
-    # Flushes all drawing operations to OpenGL so that Z-ordering can start anew. This
-    # is useful when drawing several parts of code on top of each other that use conflicting
-    # z positions.
+    # @!endgroup
+    # @!group Manipulating the drawing context
+    
+    ##
+    # Flushes all drawing operations to OpenGL so that Z-ordering can start anew. This is useful for drawing multiple layers that may not have knowledge of each other's Z-ordering, e.g., drawing a HUD on top of the game world or ensuring that a custom cursor is always drawn above everything else.
+    # 
+    # @return [void]
     def flush; end
     
-    # For custom OpenGL calls. Executes the given block in a clean OpenGL environment.
-    # Use the ruby-opengl gem to access OpenGL function (if you manage to get it to work).
-    # IF no z position is given, it will execute the given block immediately, otherwise,
-    # the code will be scheduled to be called between Gosu drawing operations.
+    ##
+    # Runs the block in a clean OpenGL environment.
+    # 
+    # If a Z-order is given, the block will be scheduled to run between Gosu drawing operations as normal; otherwise, all prior drawing operations will be flushed and the block will be executed immediately.
+    # 
+    # @note Gosu does not provide access to the underlying OpenGL APIs. A gem like ruby-opengl is required to use custom OpenGL drawing code.
     #
-    # Note: You cannot call Gosu rendering functions within this block, and you can only
-    # call the gl function in the call tree of Window#draw.
-    #
-    # See examples/OpenGLIntegration.rb for an example.
-    def gl(z=nil, &custom_gl_code); end
+    # @note Gosu rendering functions MUST NOT be used within the block, and {#gl} MUST be used only within the call tree of {#draw}.
+    # 
+    # @return [void]
+    # @param z [Float] the Z-order.
+    # @yield OpenGL code.
+    # 
+    # @see #draw
+    # @see file:reference/Z-Ordering
+    # @see file:examples/OpenGLIntegration.rb
+    def gl(z=nil); end
     
-    # Limits the drawing area to a given rectangle while evaluating the code inside of the block.
-    def clip_to(x, y, w, h, &rendering_code); end
+    ##
+    # Masks the drawing area inside the block.
+    # 
+    # @return [void]
+    # @param x [Float] the X coordinate of the top left corner,.
+    # @param y [Float] the Y coordinate of the top left corner.
+    # @param w [Float] the width of the clipping area.
+    # @param h [Float] the height of the clipping area.
+    # @yield rendering code.
+    # 
+    # @see #draw
+    def clip_to(x, y, w, h); end
     
-    # Returns a Gosu::Image that containes everything rendered within the given block. It can be
-    # used to optimize rendering of many static images, e.g. the map. There are still several
-    # restrictions that you will be informed about via exceptions.
+    ##
+    # Records all drawing operatons inside the block as a reusable "image". This method can be used to speed rendering of multiple static images, e.g., a fixed tile map.
+    # 
+    # @note Because the returned object is not a true image---it's implemented using vertex buffers and is not backed by a texture---there are restrictions on how it can be used.
     #
-    # The returned Gosu::Image will have the width and height you pass as arguments, regardless
-    # of how the area you draw on. It is important to pass accurate values if you plan on using
-    # Gosu::Image#draw_as_quad or Gosu::Image#draw_rot with the result later.
+    # @note The width and height of the returned object will be the same values you passed to {#record}, regardless of the area you draw on. It is important to pass accurate values if you plan on using {Gosu::Image#draw_as_quad} or {Gosu::Image#draw_rot} with the result later.
     #
-    # @return [Gosu::Image]
-    def record(width, height, &rendering_code); end
+    # @return [Gosu::Image] the recorded drawing operations.
+    # @param width [Float] the width of the recorded image.
+    # @param height [Float] the height of the recorded image.
+    # @yield rendering code.
+    # 
+    # @see #draw
+    # @see Gosu::Image
+    def record(width, height); end
     
-    # Rotates everything drawn in the block around (around_x, around_y).
-    def rotate(angle, around_x=0, around_y=0, &rendering_code); end
+    ##
+    # Rotates all drawing operatons inside the block.
+    # 
+    # @return [void]
+    # @param angle [Float] the rotation angle.
+    # @param around_x [Float] the X coorinate of the rotation origin.
+    # @param around_y [Float] the Y coordinate of the rotation origin.
+    # @yield rendering code.
+    # 
+    # @see #draw
+    # @see #scale
+    # @see #translate
+    # @see #transform
+    def rotate(angle, around_x=0, around_y=0); end
     
-    # Scales everything drawn in the block by a factor.
-    def scale(factor_x, factor_y=factor_x, &rendering_code); end
+    ##
+    # Scales all drawing operations inside the block.
+    # 
+    # @overload scale(factor_x, factor_y = factor_x) { ... }
+    # @overload scale(factor_x, factor_y, around_x, around_y) { ... }
+    # 
+    # @return [void]
+    # @param factor_x [Float] the horizontal scaling factor.
+    # @param factor_y [Float] the vertical scaling factor.
+    # @param around_x [Float] the X coordinate of the scaling origin.
+    # @param around_y [Float] the Y coordinate of the scaling origin.
+    # @yield rendering code.
+    # 
+    # @see #draw
+    # @see #rotate
+    # @see #translate
+    # @see #transform
+    def scale(factor_x, factor_y, around_x, around_y); end
     
-    # Scales everything drawn in the block by a factor for each dimension.
-    def scale(factor_x, factor_y, around_x, around_y, &rendering_code); end
+    ##
+    # Offsets all drawing operations inside the block.
+    # 
+    # @return [void]
+    # @param x [Float] the X offset.
+    # @param y [Float] the Y offset.
+    # @yield rendering code.
+    # 
+    # @see #draw
+    # @see #rotate
+    # @see #scale
+    # @see #transform
+    def translate(x, y); end
     
-    # Moves everything drawn in the block by an offset in each dimension.
-    def translate(x, y, &rendering_code); end
+    ##
+    # Applies a free-form matrix transformation to everything drawn in the block.
+    # 
+    # @return [void]
+    # @param m0 [Float]
+    # @param m1 [Float]
+    # @param m2 [Float]
+    # @param m3 [Float]
+    # @param m4 [Float]
+    # @param m5 [Float]
+    # @param m6 [Float]
+    # @param m7 [Float]
+    # @param m8 [Float]
+    # @param m9 [Float]
+    # @param m10 [Float]
+    # @param m11 [Float]
+    # @param m12 [Float]
+    # @param m13 [Float]
+    # @param m14 [Float]
+    # @param m15 [Float]
+    # @yield rendering code.
+    # 
+    # @see #draw
+    # @see #rotate
+    # @see #scale
+    # @see #translate
+    def transform(m0, m1, m2, m3, m4, m5, m6, m7, m8, m9, m10, m11, m12, m13, m14, m15); end
     
-    # Applies a free-form matrix rotation to everything drawn in the block.
-    def transform(m0, m1, m2, m3, m4, m5, m6, m7, m8, m9, m10, m11, m12, m13, m14, m15, &rendering_code); end
+    # @!endgroup
     
-    # Returns the character a button usually produces, or nil. To implement real text-input
-    # facilities, look at the TextInput class instead.
+    ##
+    # Returns the character a button usually produces, if any.
+    # 
+    # @note For real text input, look at {TextInput} instead.
+    # 
+    # @return [String?] the character the button usually produces.
+    # @param id [Fixnum] the button's platform-defined id.
+    # 
+    # @see char_to_button_id
+    # @see #text_input
+    # @see TextInput
     def self.button_id_to_char(id); end
     
-    # Returns the button that has to be pressed to produce the given character, or nil.
+    ##
+    # Returns the button that usually produces a character, if any.
+    # 
+    # @return [Fixnum?] the button that usually produces the character.
+    # @param char [String] the character to query.
+    # 
+    # @see button_id_to_char
+    # @see #text_input
+    # @see TextInput
     def self.char_to_button_id(char); end
     
-    # @deprecated Use Window#mouse_x= and Window#mouse_y= instead.
+    ##
+    # @deprecated Use {#mouse_x=} and {#mouse_y=} instead.
     def set_mouse_position(x, y); end
   end
   
-  # Contains information about the underlying OpenGL texture and the u/v space used for image data.
+  ##
+  # Holds information about the underlying OpenGL texture and UV coordinates of an image.
   #
-  # Can be retrieved from some images to use them in OpenGL operations. nil will be returned instead by images that are too large for a single texture.)
+  # Can be retrieved from some images to use them in OpenGL operations.
   #
-  # See examples/OpenGLIntegration.rb.
+  # @see Gosu::Image#gl_tex_info
+  # @see file:examples/OpenGLIntegration.rb
   class GLTexInfo
-    attr_reader :tex_name, :left, :right, :top, :bottom
+    ##
+    # @return [Fixnum] OpenGL texture id
+    attr_reader :tex_name
+    
+    ##
+    # @return [Float] the U coordinate of the left edge of the image.
+    attr_reader :left
+    
+    ##
+    # @return [Float] the U coordinate of the right edge of the image.
+    attr_reader :right
+    
+    ##
+    # @return [Float] the V coordinate of the top edge of the image.
+    attr_reader :top
+    
+    ##
+    # @return [Float] the V coordinate of the bottom edge of the image.
+    attr_reader :bottom
   end
 
   class << self
-    # Returns a random double between min (inclusive) and max (exclusive).
+    ##
+    # @return [Float] a random number in the range (min...max).
+    # @param min [Float] the minimum value, inclusive.
+    # @param max [Float] the maximum value, exclusive.
     def random(min, max); end
 
-    # Returns the horizontal distance between the origin and the point to which you would get if you moved radius pixels in the direction specified by angle.
-    def offset_x(angle, dist); end
+    ##
+    # @return [Float] the X component of a vector of angle theta and magnitude r, or the vertical distance covered by moving r pixels in the direction given by theta.
+    # @param theta [Float]
+    # @param r [Float]
+    def offset_x(theta, r); end
 
-    # Returns the vertical distance between the origin and the point to which you would get if you moved radius pixels in the direction specified by angle.
-    def offset_y(angle, dist); end
+    ##
+    # @return [Float] the Y component of a vector of angle theta and magnitude r, or the vertical distance covered by moving r pixels in the direction given by theta.
+    # @param theta [Float]
+    # @param r [Float]
+    def offset_y(theta, r); end
 
-    # Returns the angle from point 1 to point 2 in degrees, where 0.0 means upwards. Returns 0 if both points are equal.
+    ##
+    # @return [Float] the angular distance from (x1, y1) to (x1, y2) in degrees, where 0.0 is up. Returns 0 if both points are equal.
+    # @param x1 [Float]
+    # @param y1 [Float]
+    # @param x2 [Float]
+    # @param y2 [Float]
     def angle(x1, y1, x2, y2); end
 
-    # Returns the smallest angle that can be added to angle1 to get to angle2 (can be negative if counter-clockwise movement is shorter).
+    ##
+    # @return [Float] the shortest angular distance from angle1 to angle2. This can be negative if counter-clockwise rotation would yield a shorter distance.
+    # @param angle1 [Float]
+    # @param angle2 [Float]
     def angle_diff(angle1, angle2); end
 
-    # Returns the distance between two points.
+    ##
+    # @return [Float] the distance from (x1, y1) to (x2, y2).
+    # @param x1 [Float]
+    # @param y1 [Float]
+    # @param x2 [Float]
+    # @param y2 [Float]
     def distance(x1, y1, x2, y2); end
 
-    # Incrementing, possibly wrapping millisecond timer.
+    ##
+    # @note For long-running games, this counter will eventually wrap around to 0 again.
+    # 
+    # @return [Fixnum] the number of milliseconds elapsed.
     def milliseconds(); end
 
-    # Return current framerate (frames per second.)
+    ##
+    # @return [Fixnum] the current framerate, in frames per second.
     def fps(); end
 
-    # Returns the name of a neutral font that is available on the current
-    # platform.
+    # @return [String] the name of a neutral font that is available on the current platform.
+    # 
+    # @see Gosu::Font
+    # @see Gosu::Image#from_text
     def default_font_name(); end
 
-    # Returns the width, in pixels, of the user's primary screen.
+    ##
+    # @return [Fixnum] the width, in pixels, of the user's primary screen.
     def screen_width(); end
 
-    # Returns the height, in pixels, of the user's primary screen.
+    # @return [Fixnum] the height, in pixels, of the user's primary screen.
     def screen_height(); end
 
-    # Returns the user's preferred language, at the moment of calling the function. Expect return
-    # values such as 'en_US', 'de_DE.UTF-8', 'ja', 'zh-Hans'. You can rely only on the first two letters
-    # being a common language abbreviation.
+    ##
+    # Returns the language code for the user's preferred language. Expect return values such as 'en_US', 'de_DE.UTF-8', 'ja', 'zh-Hans', etc. You can rely only on the first two letters being a common language abbreviation.
+    # 
+    # @return [String] the user's preferred language.
     def language(); end
   end
 end
 
+##
 # Small additions to Numeric to make it easier to integrate Gosu with
 # libraries that use radians, like Chipmunk.
 class ::Numeric
-  # Returns <tt>self * 180.0 / Math::PI + 90</tt>.
-  # Translates between Gosu's angle system (where 0° is at the top) and
-  # radians (where 0 is at the right).
+  ##
+  # Converts radians to a Gosu-compatible angle using the formula <tt>self * 180.0 / Math::PI + 90</tt>.
+  # 
+  # @return [Float] degrees.
   def radians_to_gosu(); end
 
-  # Returns <tt>(self - 90) * Math::PI / 180.0</tt>
-  # Translates between Gosu's angle system (where 0° is at the top) and
-  # radians (where 0 is at the right).
+  ##
+  # Converts a Gosu-compatible angle to radians using the formula <tt>(self - 90) * Math::PI / 180.0</tt>.
+  # 
+  # @return [Float] radians.
   def gosu_to_radians(); end
   
-  # Scales a degree value to radians.
+  ##
+  # Converts degrees to radians.
+  # 
+  # @return [Float] radians.
   def degrees_to_radians(); end
   
-  # Scales a radian value to degrees.
+  ##
+  # Converts radians to degrees.
+  # 
+  # @return [Float] degrees.
   def radians_to_degrees(); end
 end