gosu 0.7.48 → 0.7.49

Sign up to get free protection for your applications and to get access to all the features.
Files changed (51) hide show
  1. checksums.yaml +7 -7
  2. data/.yardopts +1 -1
  3. data/Gosu/Audio.hpp +11 -3
  4. data/Gosu/Buttons.hpp +1 -1
  5. data/Gosu/Color.hpp +11 -11
  6. data/Gosu/Graphics.hpp +11 -3
  7. data/Gosu/GraphicsBase.hpp +21 -0
  8. data/Gosu/IO.hpp +12 -2
  9. data/Gosu/Image.hpp +1 -1
  10. data/Gosu/ImageData.hpp +2 -1
  11. data/Gosu/Input.hpp +8 -1
  12. data/Gosu/Platform.hpp +21 -5
  13. data/Gosu/Sockets.hpp +22 -3
  14. data/Gosu/TR1.hpp +4 -0
  15. data/Gosu/TextInput.hpp +7 -1
  16. data/Gosu/Version.hpp +2 -2
  17. data/Gosu/Window.hpp +7 -1
  18. data/GosuImpl/Audio/ALChannelManagement.hpp +11 -1
  19. data/GosuImpl/Audio/AudioOpenAL.cpp +1 -1
  20. data/GosuImpl/Graphics/BitmapApple.mm +16 -2
  21. data/GosuImpl/Graphics/BlockAllocator.hpp +2 -1
  22. data/GosuImpl/Graphics/Color.cpp +11 -11
  23. data/GosuImpl/Graphics/DrawOpQueue.hpp +0 -2
  24. data/GosuImpl/Graphics/Font.cpp +2 -2
  25. data/GosuImpl/Graphics/GosuView.hpp +1 -17
  26. data/GosuImpl/Graphics/GosuView.mm +68 -32
  27. data/GosuImpl/Graphics/Graphics.cpp +14 -63
  28. data/GosuImpl/Graphics/Image.cpp +1 -1
  29. data/GosuImpl/Graphics/LargeImageData.hpp +3 -2
  30. data/GosuImpl/Graphics/Macro.hpp +7 -6
  31. data/GosuImpl/Graphics/TexChunk.cpp +2 -2
  32. data/GosuImpl/Graphics/TexChunk.hpp +1 -1
  33. data/GosuImpl/Graphics/Texture.cpp +3 -3
  34. data/GosuImpl/Graphics/Texture.hpp +1 -1
  35. data/GosuImpl/Iconv.hpp +0 -5
  36. data/GosuImpl/InputTouch.mm +2 -12
  37. data/GosuImpl/WindowTouch.mm +70 -34
  38. data/GosuImpl/WindowWin.cpp +2 -2
  39. data/GosuImpl/WindowX.cpp +4 -4
  40. data/linux/extconf.rb +10 -2
  41. data/reference/gosu.rb +848 -266
  42. metadata +26 -46
  43. data/Gosu/Async.hpp +0 -50
  44. data/GosuImpl/Async.cpp +0 -38
  45. data/GosuImpl/Orientation.hpp +0 -15
  46. data/GosuImpl/Orientation.mm +0 -34
  47. data/GosuImpl/RubyGosuStub.mm +0 -52
  48. data/reference/Drawing_with_Colors.rdoc +0 -5
  49. data/reference/Order_of_Corners.rdoc +0 -5
  50. data/reference/Tileability.rdoc +0 -11
  51. data/reference/Z_Ordering.rdoc +0 -5
@@ -38,7 +38,7 @@ Gosu::Image::Image(Graphics& graphics, const Bitmap& source,
38
38
  {
39
39
  }
40
40
 
41
- Gosu::Image::Image(std::auto_ptr<ImageData> data)
41
+ Gosu::Image::Image(GOSU_UNIQUE_PTR<ImageData> data)
42
42
  : data(data.release())
43
43
  {
44
44
  if (this->data.get() == 0)
@@ -4,6 +4,7 @@
4
4
  #include <Gosu/Fwd.hpp>
5
5
  #include <Gosu/ImageData.hpp>
6
6
  #include <Gosu/TR1.hpp>
7
+ #include <Gosu/Platform.hpp>
7
8
  #include <stdexcept>
8
9
  #include <vector>
9
10
 
@@ -32,9 +33,9 @@ namespace Gosu
32
33
  return 0;
33
34
  }
34
35
 
35
- std::auto_ptr<ImageData> subimage(int x, int y, int w, int h) const
36
+ GOSU_UNIQUE_PTR<ImageData> subimage(int x, int y, int w, int h) const
36
37
  {
37
- return std::auto_ptr<ImageData>();
38
+ return GOSU_UNIQUE_PTR<ImageData>();
38
39
  }
39
40
 
40
41
  Bitmap toBitmap() const;
@@ -4,6 +4,7 @@
4
4
  #include <Gosu/Fwd.hpp>
5
5
  #include <Gosu/ImageData.hpp>
6
6
  #include <Gosu/TR1.hpp>
7
+ #include <Gosu/Platform.hpp>
7
8
  #include "Common.hpp"
8
9
  #include "DrawOpQueue.hpp"
9
10
  #include <cmath>
@@ -48,7 +49,7 @@ class Gosu::Macro : public Gosu::ImageData
48
49
 
49
50
  // Since this matrix is relatively sparse, we unroll all three solving paths.
50
51
 
51
- static const Transform nullTransform = { 0 };
52
+ static const Transform nullTransform = {{ 0 }};
52
53
 
53
54
  // Row 7 is completely useless
54
55
  if (x2 == x4 && x3 == x4)
@@ -154,12 +155,12 @@ class Gosu::Macro : public Gosu::ImageData
154
155
 
155
156
  // Let's hope I never have to debug/understand this again! :D
156
157
 
157
- Transform result = {
158
+ Transform result = {{
158
159
  c[0], c[3], 0, c[6],
159
160
  c[1], c[4], 0, c[7],
160
161
  0, 0, 1, 0,
161
162
  c[2], c[5], 0, 1
162
- };
163
+ }};
163
164
  return result;
164
165
  }
165
166
 
@@ -211,7 +212,7 @@ public:
211
212
  double x4, double y4, Color c4,
212
213
  ZPos z, AlphaMode mode) const
213
214
  {
214
- if (c1 != 0xffffffff || c2 != 0xffffffff || c3 != 0xffffffff || c4 != 0xffffffff)
215
+ if (c1 != Color::WHITE || c2 != Color::WHITE || c3 != Color::WHITE || c4 != Color::WHITE)
215
216
  throw std::invalid_argument("Macros cannot be tinted with colors yet");
216
217
  std::tr1::function<void()> f = std::tr1::bind(&Macro::drawVertexArrays, this, x1, y1, x2, y2, x3, y3, x4, y4);
217
218
  graphics.scheduleGL(f, z);
@@ -227,9 +228,9 @@ public:
227
228
  throw std::logic_error("Gosu::Macro cannot be rendered as Gosu::Bitmap yet");
228
229
  }
229
230
 
230
- std::auto_ptr<ImageData> subimage(int x, int y, int width, int height) const
231
+ GOSU_UNIQUE_PTR<ImageData> subimage(int x, int y, int width, int height) const
231
232
  {
232
- return std::auto_ptr<ImageData>();
233
+ return GOSU_UNIQUE_PTR<ImageData>();
233
234
  }
234
235
 
235
236
  void insert(const Bitmap& bitmap, int x, int y)
@@ -76,9 +76,9 @@ Gosu::Bitmap Gosu::TexChunk::toBitmap() const
76
76
  return texture->toBitmap(x, y, w, h);
77
77
  }
78
78
 
79
- std::auto_ptr<Gosu::ImageData> Gosu::TexChunk::subimage(int x, int y, int width, int height) const
79
+ GOSU_UNIQUE_PTR<Gosu::ImageData> Gosu::TexChunk::subimage(int x, int y, int width, int height) const
80
80
  {
81
- return std::auto_ptr<Gosu::ImageData>(new TexChunk(*this, x, y, width, height));
81
+ return GOSU_UNIQUE_PTR<Gosu::ImageData>(new TexChunk(*this, x, y, width, height));
82
82
  }
83
83
 
84
84
  void Gosu::TexChunk::insert(const Bitmap& original, int x, int y)
@@ -50,7 +50,7 @@ public:
50
50
 
51
51
  const GLTexInfo* glTexInfo() const;
52
52
  Gosu::Bitmap toBitmap() const;
53
- std::auto_ptr<ImageData> subimage(int x, int y, int width, int height) const;
53
+ GOSU_UNIQUE_PTR<ImageData> subimage(int x, int y, int width, int height) const;
54
54
  void insert(const Bitmap& bitmap, int x, int y);
55
55
  };
56
56
 
@@ -63,11 +63,11 @@ GLuint Gosu::Texture::texName() const
63
63
  return name;
64
64
  }
65
65
 
66
- std::auto_ptr<Gosu::TexChunk>
66
+ GOSU_UNIQUE_PTR<Gosu::TexChunk>
67
67
  Gosu::Texture::tryAlloc(Graphics& graphics, DrawOpQueueStack& queues,
68
68
  std::tr1::shared_ptr<Texture> ptr, const Bitmap& bmp, unsigned padding)
69
69
  {
70
- std::auto_ptr<Gosu::TexChunk> result;
70
+ GOSU_UNIQUE_PTR<Gosu::TexChunk> result;
71
71
 
72
72
  BlockAllocator::Block block;
73
73
  if (!allocator.alloc(bmp.width(), bmp.height(), block))
@@ -80,7 +80,7 @@ std::auto_ptr<Gosu::TexChunk>
80
80
  glTexSubImage2D(GL_TEXTURE_2D, 0, block.left, block.top, block.width, block.height,
81
81
  Color::GL_FORMAT, GL_UNSIGNED_BYTE, bmp.data());
82
82
 
83
- return result;
83
+ return GOSU_MOVE_UNIQUE_PTR(result);
84
84
  }
85
85
 
86
86
  void Gosu::Texture::block(unsigned x, unsigned y, unsigned width, unsigned height)
@@ -21,7 +21,7 @@ namespace Gosu
21
21
  ~Texture();
22
22
  unsigned size() const;
23
23
  GLuint texName() const;
24
- std::auto_ptr<TexChunk>
24
+ GOSU_UNIQUE_PTR<TexChunk>
25
25
  tryAlloc(Graphics& graphics, DrawOpQueueStack& queues,
26
26
  std::tr1::shared_ptr<Texture> ptr, const Bitmap& bmp, unsigned padding);
27
27
  void block(unsigned x, unsigned y, unsigned width, unsigned height);
@@ -3,12 +3,7 @@
3
3
 
4
4
  #include <Gosu/Platform.hpp>
5
5
 
6
- #ifdef __APPLE__
7
- #include </usr/include/iconv.h> // We want Apple's iconv
8
- #else
9
6
  #include <iconv.h>
10
- #endif
11
- //#endif
12
7
  #include <errno.h>
13
8
 
14
9
  namespace Gosu
@@ -2,7 +2,6 @@
2
2
  #include <Gosu/TextInput.hpp>
3
3
 
4
4
  #include "MacUtility.hpp"
5
- #include "Orientation.hpp"
6
5
  #include "Input/AccelerometerReader.hpp"
7
6
  #import <UIKit/UIKit.h>
8
7
 
@@ -27,16 +26,7 @@ struct Gosu::Input::Impl
27
26
  Touch translateTouch(UITouch* uiTouch)
28
27
  {
29
28
  CGPoint point = [uiTouch locationInView: view];
30
- Touch touch = { uiTouch, point.y, point.x };
31
- switch (currentOrientation())
32
- {
33
- case orLandscapeLeft:
34
- touch.y = [view bounds].size.width - touch.y;
35
- break;
36
- default:
37
- touch.x = [view bounds].size.height - touch.x;
38
- break;
39
- }
29
+ Touch touch = { uiTouch, point.x, point.y };
40
30
  touch.x *= factorX, touch.y *= factorY;
41
31
  return touch;
42
32
  }
@@ -77,7 +67,7 @@ void Gosu::Input::feedTouchEvent(int type, void* touches)
77
67
  [pimpl->currentTouchesSet.get() minusSet: uiTouches], f = &onTouchEnded;
78
68
  for (UITouch* uiTouch in uiTouches)
79
69
  if (*f)
80
- (*f)(pimpl->translateTouch(uiTouch));
70
+ (*f)(pimpl->translateTouch(uiTouch));
81
71
  }
82
72
 
83
73
  wchar_t Gosu::Input::idToChar(Button btn)
@@ -8,6 +8,10 @@
8
8
  #import <CoreGraphics/CoreGraphics.h>
9
9
  #import <UIKit/UIKit.h>
10
10
  #import <OpenGLES/EAGL.h>
11
+ #import <QuartzCore/QuartzCore.h>
12
+
13
+ #include <OpenAL/alc.h>
14
+ #include <AudioToolbox/AudioSession.h>
11
15
 
12
16
  using namespace std::tr1::placeholders;
13
17
 
@@ -28,6 +32,17 @@ namespace Gosu
28
32
  {
29
33
  return screenRect().size.height;
30
34
  }
35
+
36
+ ALCcontext *sharedContext();
37
+ }
38
+
39
+ static void handleAudioInterruption(void *unused, UInt32 inInterruptionState)
40
+ {
41
+ if (inInterruptionState == kAudioSessionBeginInterruption) {
42
+ alcMakeContextCurrent(NULL);
43
+ } else if (inInterruptionState == kAudioSessionEndInterruption) {
44
+ alcMakeContextCurrent(Gosu::sharedContext());
45
+ }
31
46
  }
32
47
 
33
48
  int main(int argc, char *argv[])
@@ -51,7 +66,6 @@ struct Gosu::Window::Impl
51
66
  ObjRef<UIWindow> window;
52
67
  ObjRef<GosuViewController> controller;
53
68
  std::auto_ptr<Graphics> graphics;
54
- std::auto_ptr<Audio> audio;
55
69
  std::auto_ptr<Input> input;
56
70
  double interval;
57
71
  };
@@ -67,36 +81,43 @@ namespace
67
81
  GosuView* gosuView = nil;
68
82
  bool pausedSong = false;
69
83
  bool paused = false;
70
- }
71
-
72
- @implementation GosuAppDelegate
73
- // Required according to docs...
74
- - (void)applicationProtectedDataWillBecomeUnavailable:(UIApplication *)application {
75
- }
76
84
 
77
- // Required according to docs...
78
- - (void)applicationProtectedDataDidBecomeAvailable:(UIApplication *)application {
85
+ id timerOrDisplayLink = nil;
79
86
  }
80
87
 
81
- // Required according to docs...
82
- - (void)application:(UIApplication *)application didReceiveLocalNotification:(UILocalNotification *)notification {
88
+ @implementation GosuAppDelegate
89
+ - (void)setupTimerOrDisplayLink
90
+ {
91
+ if (timerOrDisplayLink)
92
+ return;
93
+
94
+ NSInteger targetFPS = round(1000.0 / windowInstance().updateInterval());
95
+
96
+ if (60 % targetFPS != 0) {
97
+ NSTimer *timer = [NSTimer scheduledTimerWithTimeInterval:windowInstance().updateInterval() / 1000.0 target:self selector:@selector(doTick:) userInfo:nil repeats:YES];
98
+
99
+ timerOrDisplayLink = [timer retain];
100
+ }
101
+ else {
102
+ CADisplayLink *displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(doTick:)];
103
+ displayLink.frameInterval = 60 / targetFPS;
104
+ [displayLink addToRunLoop:[NSRunLoop mainRunLoop] forMode:NSRunLoopCommonModes];
105
+
106
+ timerOrDisplayLink = [displayLink retain];
107
+ }
83
108
  }
84
109
 
85
- - (void)applicationDidFinishLaunching:(UIApplication *)application {
86
- [UIDevice.currentDevice beginGeneratingDeviceOrientationNotifications];
87
- //UIApplication.sharedApplication.idleTimerDisabled = YES;
88
- UIApplication.sharedApplication.statusBarOrientation = UIInterfaceOrientationLandscapeRight;
89
-
90
- [[NSTimer scheduledTimerWithTimeInterval: windowInstance().updateInterval() / 1000.0
91
- target: self
92
- selector: @selector(doTick:)
93
- userInfo: nil
94
- repeats: YES] retain];
110
+ - (void)applicationDidFinishLaunching:(UIApplication *)application
111
+ {
112
+ [UIApplication sharedApplication].statusBarHidden = YES;
113
+ [self setupTimerOrDisplayLink];
114
+
115
+ AudioSessionInitialize(NULL, NULL, handleAudioInterruption, NULL);
95
116
  }
96
117
 
97
- - (void)applicationWillResignActive:(UIApplication *)application {
98
- if (Gosu::Song::currentSong())
99
- {
118
+ - (void)applicationWillResignActive:(UIApplication *)application
119
+ {
120
+ if (Gosu::Song::currentSong()) {
100
121
  Gosu::Song::currentSong()->pause();
101
122
  pausedSong = true;
102
123
  }
@@ -104,9 +125,9 @@ namespace
104
125
  windowInstance().loseFocus();
105
126
  }
106
127
 
107
- - (void)applicationDidBecomeActive:(UIApplication *)application {
108
- if (pausedSong)
109
- {
128
+ - (void)applicationDidBecomeActive:(UIApplication *)application
129
+ {
130
+ if (pausedSong) {
110
131
  if (Gosu::Song::currentSong())
111
132
  Gosu::Song::currentSong()->play();
112
133
  pausedSong = false;
@@ -114,7 +135,20 @@ namespace
114
135
  paused = false;
115
136
  }
116
137
 
117
- - (void)doTick:(NSTimer*)timer {
138
+ - (void)applicationDidEnterBackground:(UIApplication *)application
139
+ {
140
+ [timerOrDisplayLink invalidate];
141
+ [timerOrDisplayLink release];
142
+ timerOrDisplayLink = nil;
143
+ }
144
+
145
+ - (void)applicationWillEnterForeground:(UIApplication *)application
146
+ {
147
+ [self setupTimerOrDisplayLink];
148
+ }
149
+
150
+ - (void)doTick:(id)sender
151
+ {
118
152
  if (!paused)
119
153
  windowInstance().update();
120
154
  [gosuView drawView];
@@ -130,18 +164,18 @@ Gosu::Window::Window(unsigned width, unsigned height,
130
164
  pimpl->window.reset([[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]]);
131
165
  pimpl->controller.reset([[GosuViewController alloc] init]);
132
166
  gosuView = (GosuView*)pimpl->controller.obj().view;
133
- [pimpl->window.obj() addSubview: gosuView];
167
+ pimpl->window.obj().rootViewController = pimpl->controller.obj();
134
168
 
135
- pimpl->graphics.reset(new Graphics(screenWidth(), screenHeight(), false));
169
+ pimpl->graphics.reset(new Graphics(screenHeight(), screenWidth(), false));
136
170
  pimpl->graphics->setResolution(screenHeight(), screenWidth());
137
- pimpl->audio.reset(new Audio());
138
171
  pimpl->input.reset(new Input(gosuView, updateInterval));
139
172
  pimpl->input->onTouchBegan = std::tr1::bind(&Window::touchBegan, this, _1);
140
173
  pimpl->input->onTouchMoved = std::tr1::bind(&Window::touchMoved, this, _1);
141
174
  pimpl->input->onTouchEnded = std::tr1::bind(&Window::touchEnded, this, _1);
142
175
  pimpl->interval = updateInterval;
143
176
 
144
- [pimpl->window.obj() makeKeyAndVisible];
177
+ // TODO: Get rid of performSelector:withObject:afterDelay:, without causing a C++ static initialization error
178
+ [pimpl->window.obj() performSelector:@selector(makeKeyAndVisible) withObject:nil afterDelay:0];
145
179
  }
146
180
 
147
181
  Gosu::Window::~Window()
@@ -174,12 +208,14 @@ Gosu::Graphics& Gosu::Window::graphics()
174
208
 
175
209
  const Gosu::Audio& Gosu::Window::audio() const
176
210
  {
177
- return *pimpl->audio;
211
+ static Gosu::Audio audio;
212
+ return audio;
178
213
  }
179
214
 
180
215
  Gosu::Audio& Gosu::Window::audio()
181
216
  {
182
- return *pimpl->audio;
217
+ static Gosu::Audio audio;
218
+ return audio;
183
219
  }
184
220
 
185
221
  const Gosu::Input& Gosu::Window::input() const
@@ -177,8 +177,8 @@ struct Gosu::Window::Impl
177
177
  {
178
178
  HWND handle;
179
179
  HDC hdc;
180
- std::auto_ptr<Graphics> graphics;
181
- std::auto_ptr<Input> input;
180
+ GOSU_UNIQUE_PTR<Graphics> graphics;
181
+ GOSU_UNIQUE_PTR<Input> input;
182
182
  double updateInterval;
183
183
  bool iconified;
184
184
 
@@ -93,8 +93,8 @@ namespace Gosu
93
93
 
94
94
  struct Gosu::Window::Impl
95
95
  {
96
- std::auto_ptr<Graphics> graphics;
97
- std::auto_ptr<Input> input;
96
+ GOSU_UNIQUE_PTR<Graphics> graphics;
97
+ GOSU_UNIQUE_PTR<Input> input;
98
98
 
99
99
  ::Display* display;
100
100
 
@@ -169,7 +169,7 @@ struct Gosu::Window::Impl
169
169
  active = false;
170
170
  }
171
171
  if (event.type == Expose && event.xexpose.count == 0 &&
172
- window->graphics().begin(Colors::black)) {
172
+ window->graphics().begin(Color::BLACK)) {
173
173
  FPS::registerFrame();
174
174
  window->draw();
175
175
  window->graphics().end();
@@ -192,7 +192,7 @@ struct Gosu::Window::Impl
192
192
  window->input().update();
193
193
  window->update();
194
194
 
195
- if (window->needsRedraw() && window->graphics().begin(Colors::black))
195
+ if (window->needsRedraw() && window->graphics().begin(Color::BLACK))
196
196
  {
197
197
  FPS::registerFrame();
198
198
  window->draw();
@@ -69,6 +69,9 @@ OGG_VORBIS_FILES = Dir['../dependencies/libogg/src/*.c'] +
69
69
  require 'mkmf'
70
70
  require 'fileutils'
71
71
 
72
+ # Silence internal deprecation warnings in Gosu
73
+ $CFLAGS << " -DGOSU_DEPRECATED="
74
+
72
75
  $INCFLAGS << " -I../ -I../GosuImpl"
73
76
 
74
77
  if `uname`.chomp == 'Darwin' then
@@ -81,14 +84,19 @@ if `uname`.chomp == 'Darwin' then
81
84
  $INCFLAGS << " -I../dependencies/libvorbis/include"
82
85
  $INCFLAGS << " -I../dependencies/libvorbis/lib"
83
86
  # To make everything work with the Objective C runtime
84
- $CFLAGS << " -x objective-c -fobjc-gc -DNDEBUG"
87
+ $CFLAGS << " -x objective-c -DNDEBUG"
85
88
  # Compile all C++ files as Objective C++ on OS X since mkmf does not support .mm
86
89
  # files.
87
90
  # Also undefine two debug flags that cause exceptions to randomly crash
88
91
  # otherwise; see:
89
92
  # https://trac.macports.org/ticket/27237#comment:21
90
93
  # http://newartisans.com/2009/10/a-c-gotcha-on-snow-leopard/#comment-893
91
- CONFIG['CXXFLAGS'] = "#{CONFIG['CXXFLAGS']} -x objective-c++ -U_GLIBCXX_DEBUG -U_GLIBCXX_DEBUG_PEDANTIC"
94
+ CONFIG['CXXFLAGS'] = "#{CONFIG['CXXFLAGS']} -x objective-c++ -U_GLIBCXX_DEBUG -U_GLIBCXX_DEBUG_PEDANTIC"
95
+ if `uname -r`.to_i >= 13 then
96
+ # Use C++11 on Mavericks and above
97
+ # TODO: This can probably be enabled starting from 10.6?
98
+ CONFIG['CXXFLAGS'] << " -std=gnu++11"
99
+ end
92
100
  $LDFLAGS << " -L/usr/X11/lib -liconv"
93
101
  %w(AudioToolbox IOKit OpenAL OpenGL AppKit ApplicationServices Foundation Carbon).each do |f|
94
102
  $LDFLAGS << " -framework #{f}"
@@ -1,11 +1,20 @@
1
- # Version string of the form "0.1.2" or "0.1.2.3".
2
- GOSU_VERSION = :a_string
3
- # First component of the version.
1
+ ##
2
+ # The first component of the version.
4
3
  GOSU_MAJOR_VERSION = :a_fixnum
5
- # Second component of the version.
4
+
5
+ ##
6
+ # The second component of the version.
6
7
  GOSU_MINOR_VERSION = :a_fixnum
7
- # Third component of the version.
8
+
9
+ ##
10
+ # The third component of the version.
8
11
  GOSU_POINT_VERSION = :a_fixnum
12
+
13
+ ##
14
+ # A version string of the form "0.1.2" or "0.1.2.3".
15
+ GOSU_VERSION = "#{GOSU_MAJOR_VERSION}.#{GOSU_MINOR_VERSION}.#{GOSU_POINT_VERSION}"
16
+
17
+ ##
9
18
  # A long block of legal copy that your game is obliged to display somewhere.
10
19
  GOSU_COPYRIGHT_NOTICE = :a_string
11
20
 
@@ -50,8 +59,11 @@ module Gosu
50
59
  KbDelete = :implementation_defined
51
60
  KbDown = :implementation_defined
52
61
  KbEnd = :implementation_defined
53
- # On Numpad
62
+
63
+ ##
64
+ # This is the key on the numpad.
54
65
  KbEnter = :implementation_defined
66
+
55
67
  KbEscape = :implementation_defined
56
68
  KbF1 = :implementation_defined
57
69
  KbF10 = :implementation_defined
@@ -87,8 +99,11 @@ module Gosu
87
99
  KbNumpadSubtract = :implementation_defined
88
100
  KbPageDown = :implementation_defined
89
101
  KbPageUp = :implementation_defined
90
- # Above the right shift key
102
+
103
+ ##
104
+ # This is the key above the right shift key.
91
105
  KbReturn = :implementation_defined
106
+
92
107
  KbRight = :implementation_defined
93
108
  KbRightAlt = :implementation_defined
94
109
  KbRightControl = :implementation_defined
@@ -222,284 +237,555 @@ module Gosu
222
237
  Gp3Left = :implementation_defined
223
238
  Gp3Right = :implementation_defined
224
239
  Gp3Up = :implementation_defined
225
-
226
- # Represents an ARGB color value with 8 bits for each channel. Can be
227
- # replaced by literals of the form 0xaarrggbb in all of Gosu.
240
+
241
+ ##
242
+ # 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.
228
243
  class Color
229
- attr_accessor :alpha, :red, :green, :blue, :hue, :saturation, :value
244
+ ##
245
+ # @return [Fixnum] the color's alpha channel.
246
+ attr_accessor :alpha
230
247
 
231
- # a:: Integer from 0..255
232
- # r:: Integer from 0..255
233
- # g:: Integer from 0..255
234
- # b:: Integer from 0..255
235
- def initialize(a, r, g, b); end
236
- # Initializes a color from an 0xrrggbbaa integer.
237
- def initialize(argb); end
248
+ ##
249
+ # @return [Fixnum] the color's red channel.
250
+ attr_accessor :red
238
251
 
239
- def dup; end
252
+ ##
253
+ # @return [Fixnum] the color's green channel.
254
+ attr_accessor :green
255
+
256
+ ##
257
+ # @return [Fixnum] the color's blue channel.
258
+ attr_accessor :blue
259
+
260
+ ##
261
+ # @return [Fixnum] the color's hue in the range (0...360).
262
+ attr_accessor :hue
263
+
264
+ ##
265
+ # @return [Float] the color's saturation in the range (0..1).
266
+ attr_accessor :saturation
240
267
 
241
- # Same as the constructor, but with an explicit order.
242
- def self.rgba(r, g, b, a); end
268
+ ##
269
+ # @return [Float] the color's value in the range (0..1).
270
+ attr_accessor :value
243
271
 
244
- # Initializes a color from an 0xrrggbbaa integer.
245
- def self.rgba(rgba); end
272
+ # @!group Creating colors.
246
273
 
247
- # Same as the constructor, but with an explicit order.
248
- def self.argb(a, r, g, b); end
274
+ ##
275
+ # @overload initialize(argb)
276
+ # @param argb [Fixnum] an integer of the form 0xAARRGGBB.
277
+ #
278
+ # @overload initialize(a, r, g, b)
279
+ # @param a [Fixnum] the color's alpha channel in the range (0..255).
280
+ # @param r [Fixnum] the color's red channel in the range (0..255).
281
+ # @param g [Fixnum] the color's green channel in the range (0..255).
282
+ # @param b [Fixnum] the color's blue channel in the range (0..255).
283
+ #
284
+ # @see from_hsv
285
+ # @see from_ahsv
286
+ # @see rgba
287
+ # @see argb
288
+ def initialize(*args); end
249
289
 
250
- # Initializes a color from an 0xrrggbbaa integer.
251
- def self.argb(argb); end
290
+ ##
291
+ # @return (see #initialize)
292
+ #
293
+ # @overload rgba(rgba)
294
+ # @param argb [Fixnum] an integer of the form 0xRRGGBBAA.
295
+ #
296
+ # @overload rgba(r, g, b, a)
297
+ # @param r [Fixnum] the color's red channel in the range (0..255).
298
+ # @param g [Fixnum] the color's green channel in the range (0..255).
299
+ # @param b [Fixnum] the color's blue channel in the range (0..255).
300
+ # @param a [Fixnum] the color's alpha channel in the range (0..255).
301
+ #
302
+ # @see #initialize
303
+ # @see argb
304
+ def self.rgba(*args); end
252
305
 
253
- # Converts a HSV triple into a color. Same as from_ahsv with alpha set to 255.
254
- # h:: Integer from 0..360
255
- # s:: Float from 0..1
256
- # v:: Float from 0..1.
306
+ # This method is equivalent to calling `Color.new`, but the name makes the parameter order explicit.
307
+ #
308
+ # @return (see #initialize)
309
+ # @overload argb(argb)
310
+ # @overload argb(a, r, g, b)
311
+ #
312
+ # @see #initialize
313
+ # @see rgba
314
+ def self.argb(*args); end
315
+
316
+ # Converts an HSV triplet to an opaque color.
317
+ #
318
+ # @return [Color] a color corresponding to the HSV triplet.
319
+ # @param h [Fixnum] the color's hue in the range (0..360).
320
+ # @param s [Float] the color's saturation in the range (0..1).
321
+ # @param v [Float] the color's value in the range (0..1).
322
+ #
323
+ # @see from_ahsv
257
324
  def self.from_hsv(h, s, v); end
258
325
 
259
- # Converts a HSV triple into a color, with a given alpha.
260
- # a:: Integer from 0..255
261
- # h:: Integer from 0..360
262
- # s:: Float from 0..1
263
- # v:: Float from 0..1.
326
+ # Converts an HSV triplet to a color with the alpha channel set to a given value.
327
+ #
328
+ # @return (see from_hsv)
329
+ # @param a [Fixnum] the color's opacity in the range (0..255).
330
+ # @param (see from_hsv)
331
+ #
332
+ # @see from_hsv
264
333
  def self.from_ahsv(a, h, s, v); end
265
334
 
266
- # 32-bit unsigned value for use with OpenGL ('RGBA' octet in memory).
335
+ # @!endgroup
336
+
337
+ # 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.
338
+ #
339
+ # @return [Fixnum] a 32-bit OpenGL color.
267
340
  def gl; end
268
341
 
269
- # constant
342
+ ##
343
+ # @return [Color] a copy of the color.
344
+ def dup; end
345
+
270
346
  NONE = Gosu::Color.argb(0x00000000)
271
- # constant
272
347
  BLACK = Gosu::Color.argb(0xff000000)
273
- # constant
274
348
  GRAY = Gosu::Color.argb(0xff808080)
275
- # constant
276
- WHITE = Gosu::Color.argb(0xffffffff)
277
- # constant
349
+ WHITE = Gosu::Color.argb(0xffffffff)
278
350
  AQUA = Gosu::Color.argb(0xff00ffff)
279
- # constant
280
351
  RED = Gosu::Color.argb(0xffff0000)
281
- # constant
282
352
  GREEN = Gosu::Color.argb(0xff00ff00)
283
- # constant
284
353
  BLUE = Gosu::Color.argb(0xff0000ff)
285
- # constant
286
354
  YELLOW = Gosu::Color.argb(0xffffff00)
287
- # constant
288
355
  FUCHSIA = Gosu::Color.argb(0xffff00ff)
289
- # constant
290
356
  CYAN = Gosu::Color.argb(0xff00ffff)
291
357
  end
292
358
 
359
+ ##
293
360
  # A font can be used to draw text on a Window object very flexibly.
294
361
  # Fonts are ideal for small texts that change regularly. For large,
295
- # static texts you should use Image#from_text.
362
+ # static texts you should use {Gosu::Image#from_text}.
296
363
  class Font
297
- attr_reader :name, :height
364
+ ##
365
+ # The font's name. This may be the name of a system font or a filename.
366
+ #
367
+ # @return [String] the font's name.
368
+ attr_reader :name
298
369
 
299
- # font_name:: Name of a system font, or a filename to a TTF file (must contain '/').
300
- # height:: Height of the font, in pixels.
370
+ ##
371
+ # @return [Fixnum] The font's height in pixels.
372
+ attr_reader :height
373
+
374
+ ##
375
+ # Load a font from the system fonts or a file.
376
+ #
377
+ # @param window [Gosu::Window]
378
+ # @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.
379
+ # @param height [Fixnum] the height of the font, in pixels.
301
380
  def initialize(window, font_name, height); end
302
381
 
303
- # 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.
382
+ ##
383
+ # Overrides the image for a character.
384
+ #
385
+ # @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.
386
+ #
387
+ # @return [void]
388
+ # @param character [String] the character to replace.
389
+ # @param image [Image] the image to use for the character.
304
390
  def []=(character, image); end
305
391
 
306
- # Draws text so the top left corner of the text is at (x; y).
307
- #
308
- # Characters are created internally as needed.
392
+ # @!group Drawing text
393
+
394
+ ##
395
+ # Draws a single line of text with its top left corner at (x, y).
396
+ #
397
+ # @return [void]
398
+ # @param text [String]
399
+ # @param x [Number] the X coordinate
400
+ # @param y [Number] the Y coordinate
401
+ # @param z [Number] the Z-order.
402
+ # @param factor_x [Float] the horizontal scaling factor.
403
+ # @param factor_y [Float] the vertical scaling factor.
404
+ # @param color [Color, Fixnum]
405
+ # @param mode [:default, :additive] the blending mode to use.
406
+ #
407
+ # @see #draw_rel
408
+ # @see Gosu::Image.from_text
409
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
410
+ # @see file:reference/Z-Ordering.md
309
411
  def draw(text, x, y, z, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
310
412
 
311
- # Draws text at a position relative to (x; y).
312
- # 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.
313
- # rel_y:: See rel_x.
413
+ ##
414
+ # Draws a single line of text relative to (x, y).
415
+ #
416
+ # 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.
417
+ #
418
+ # All real numbers are valid alignment values and will be interpolated (or extrapolated) accordingly.
419
+ #
420
+ # @return [void]
421
+ # @param rel_x [Float] the horizontal alignment.
422
+ # @param rel_y [Float] the vertical alignment.
423
+ # @param (see #draw)
424
+ #
425
+ # @see #draw
426
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
427
+ # @see file:reference/Z-Ordering.md
314
428
  def draw_rel(text, x, y, z, rel_x, rel_y, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
315
429
 
316
- # Returns the width, in pixels, the given text would occupy if drawn.
317
- def text_width(text, factor_x=1); end
318
-
319
- # Analogous to draw, but rotates the text by a given angle.
320
- # @deprecated Use a combination of Window#rotate and Font#draw instead.
430
+ ##
431
+ # @deprecated Use {#draw} in conjunction with {Window#rotate} instead.
432
+ #
433
+ # @see #draw
434
+ # @see Gosu::Window#rotate
321
435
  def draw_rot(text, x, y, z, angle, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
436
+
437
+ # @!endgroup
438
+
439
+ ##
440
+ # Returns the width of a single line of text, in pixels, if it were drawn.
441
+ #
442
+ # @return [Fixnum] the width of the text, in pixels.
443
+ # @param text [String]
444
+ def text_width(text, factor_x=1); end
322
445
  end
323
446
 
447
+ ##
324
448
  # Provides functionality for drawing rectangular images.
325
449
  class Image
326
- attr_reader :width, :height
450
+ ##
451
+ # @return [Fixnum] the image's width, in pixels.
452
+ attr_reader :width
453
+
454
+ ##
455
+ # @return [Fixnum] the image's height, in pixels.
456
+ attr_reader :height
327
457
 
328
- # Loads an image from a given filename that can be drawn onto the
329
- # given window. See the Gosu wiki for a list of supported formats.
458
+ # @!group Creating and loading images
459
+
460
+ ##
461
+ # Loads an image from a file or an RMagick image.
462
+ #
463
+ # @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.
330
464
  #
331
- # A color key of #ff00ff is automatically applied to BMP type images.
332
- def initialize(window, filename_or_rmagick_image, tileable); end
465
+ # @param window [Window]
466
+ # @param source [String, Magick::Image] the filename or RMagick image to load from.
467
+ # @param tileable [true, false]
468
+ # @param left [Fixnum]
469
+ # @param top [Fixnum]
470
+ # @param width [Fixnum]
471
+ # @param height [Fixnum]
472
+ #
473
+ # @overload initialize(window, source, tileable)
474
+ # @overload initialize(window, source, tileable, left, top, width, height)
475
+ # Loads a rectangular slice of the image.
476
+ #
477
+ # If you need to load multiple tiles from a texture atlas, {load_tiles} is almost always a better choice.
478
+ #
479
+ #
480
+ # @see load_tiles
481
+ # @see from_text
482
+ # @see file:reference/Tileability.md
483
+ def initialize(window, source, tileable, left, top, width, height); end
333
484
 
334
- # Loads an image from a given filename that can be drawn onto the
335
- # given window. See the Gosu wiki for a list of supported formats.
485
+ ##
486
+ # Creates a reusable image from one or more lines of text.
336
487
  #
337
- # A color key of #ff00ff is automatically applied to BMP type images.
488
+ # The text is always rendered in white. To draw it in a different color, use the `color` parameter of {#draw}, et al.
489
+ #
490
+ # @overload from_text(window, text, font_name, font_height)
491
+ # @overload from_text(window, text, font_name, font_height, line_spacing, width, align)
492
+ #
493
+ # @return [Gosu::Image]
494
+ # @param window [Gosu::Window]
495
+ # @param text [String]
496
+ # @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.
497
+ # @param font_height [Fixnum] the height of the font, in pixels.
498
+ # @param line_spacing [Fixnum] the vertical spacing beteen lines.
499
+ # @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.
500
+ # @param align [:left, :right, :center, :justify] the text alignment.
501
+ #
502
+ # @see Gosu::Font
503
+ def self.from_text(window, text, font_name, font_height, line_spacing, width, align); end
504
+
505
+ ##
506
+ # Loads an image from a file or an RMagick image, then divides the image into an array of equal-sized tiles.
507
+ #
508
+ # @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.
338
509
  #
339
- # This constructor only loads a sub-rectangle of the given file. Because
340
- # every call of this constructor will open the image again, it is preferable
341
- # to use Image#load_tiles when possible.
342
- def initialize(window, filename_or_rmagick_image, tileable, src_x, src_y, src_width, src_height); end
510
+ # @return [Array<Gosu::Image>]
511
+ # @param window [Window]
512
+ # @param source [String, Magick::Image]
513
+ # @param tile_width [Fixnum] If positive, this is the width of the individual tiles; if negative, the image is divided into -tile_width columns.
514
+ # @param tile_height [Fixnum] If positive, this is the height of the individual tiles; if negative, the image is divided into -tile_height rows.
515
+ # @param tileable [true, false]
516
+ #
517
+ # @see file:reference/Tileability.md
518
+ def self.load_tiles(window, source, tile_width, tile_height, tileable); end
519
+
520
+ # @!endgroup
521
+
522
+ # @!group Drawing an image
343
523
 
344
- # Draws the image so its upper left corner is at (x; y).
524
+ ##
525
+ # Draws the image with its top left corner at (x, y).
526
+ #
527
+ # @return [void]
528
+ # @param x [Float] the X coordinate.
529
+ # @param y [Float] the X coordinate.
530
+ # @param z [Float] the Z-order.
531
+ # @param factor_x [Float] the horizontal scaling factor.
532
+ # @param factor_y [Float] the vertical scaling factor.
533
+ # @param color [Gosu::Color, Integer]
534
+ # @param mode [:default, :additive] the blending mode to use.
535
+ #
536
+ # @see #draw_rot
537
+ # @see #draw_as_quad
538
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
539
+ # @see file:reference/Z-Ordering.md
345
540
  def draw(x, y, z, factor_x=1, factor_y=1, color=0xffffffff, mode=:default); end
346
541
 
347
- # 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)
348
- # center_y:: See center_x.
542
+ ##
543
+ # Draws the image rotated, with its rotational center at (x, y).
544
+ #
545
+ # @return [void]
546
+ # @param angle [Float]
547
+ # @param center_x [Float] the relative horizontal rotation origin.
548
+ # @param center_y [Float] the relative vertical rotation origin.
549
+ # @param (see #draw)
550
+ #
551
+ # @see #draw
552
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
553
+ # @see file:reference/Z-Ordering.md
349
554
  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
350
555
 
351
- # 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.
352
- # The points can be in clockwise order, or in a Z shape, starting at the top left.
556
+ ##
557
+ # 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.
558
+ #
559
+ # @return [void]
560
+ # @param (see Gosu::Window#draw_quad)
561
+ #
562
+ # @see #draw
563
+ # @see Gosu::Window#draw_quad
564
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
565
+ # @see file:reference/Order_of_Corners.md Order of Corners
566
+ # @see file:reference/Z-Ordering.md
353
567
  def draw_as_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z, mode=:default); end
354
568
 
355
- # Creates an Image containing a line of text.
356
- #
357
- # The text is always rendered in white. If you want to draw it in a
358
- # different color, just modulate it by the target color.
359
- # font_name:: Name of a system font, or a filename to a TTF file (must contain '/').
360
- # font_height:: Height of the font in pixels.
361
- def self.from_text(window, text, font_name, font_height); end
362
-
363
- # Creates an Image that is filled with the text given to the function.
364
- #
365
- # The text may contain line breaks.
366
- #
367
- # The text is always rendered in white. If you want to draw it in a
368
- # different color, just modulate it by the target color.
369
- # font_name:: Name of a system font, or a filename to a TTF file (must contain '/').
370
- # font_height:: Height of the font in pixels.
371
- # line_spacing:: Spacing between two lines of text in pixels.
372
- # 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.
373
- # align:: One of :left, :right, :center or :justify.
374
- def self.from_text(window, text, font_name, font_height, line_spacing, max_width, align); end
375
-
376
- # Convenience function that splits an image file into an array of small rectangles and
377
- # creates images from these. Returns the Array containing Image instances.
378
- #
379
- # A color key of #ff00ff is automatically applied to BMP type images.
380
- #
381
- # tile_width:: If positive, specifies the width of one tile in pixels. If negative, the bitmap is divided into -tile_width rows.
382
- # tile_height:: See tile_width.
383
- def self.load_tiles(window, filename_or_rmagick_image, tile_width, tile_height, tileable); end
569
+ # @!endgroup
384
570
 
385
- # See examples/OpenGLIntegration.rb.
571
+ ##
572
+ # Returns an object that holds information about the underlying OpenGL texture and UV coordinates of the image.
573
+ #
574
+ # @note Some images may be too large to fit on a single texture; this method returns nil in those cases.
575
+ #
576
+ # @return [Gosu::GLTexInfo?] information about the underlying OpenGL texture.
577
+ #
578
+ # @see Gosu::GLTexInfo
579
+ # @see file:examples/OpenGLIntegration.rb
386
580
  def gl_tex_info; end
387
581
 
388
- # Returns the associated texture contents as binary string of RGBA values.
389
- # Useful for use with RMagick (Magick::Image.from_blob).
582
+ ##
583
+ # Returns the associated texture contents as binary string of packed RGBA values, useful for use with RMagick (Magick::Image.from_blob).
584
+ #
585
+ # @return [String] a binary string of packed RGBA values.
390
586
  def to_blob; end
391
587
 
392
- # Overwrites all or parts of the Image. x and y can be negative or otherwise out of
393
- # bounds, the incoming image data is clipped to the current image size.
588
+ ##
589
+ # 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.
590
+ #
394
591
  # This can be used to e.g. overwrite parts of a landscape.
395
- def insert(filename_or_rmagick_image, x, y); end
592
+ #
593
+ # @return [void]
594
+ # @param source [String, Magick::Image] the filename or RMagick image to load from.
595
+ # @param x [Fixnum] the X coordinate of the top left corner.
596
+ # @param y [Fixnum] the Y coordinate of the top left corner.
597
+ def insert(source, x, y); end
396
598
 
397
- # Saves the texture contents as an image file. Useful, for example, to
398
- # pre-render text on a development machine with proper fonts installed.
399
- # The file format is determined from the file extension. See the Gosu
400
- # wiki for a list of portably supported formats.
599
+ ##
600
+ # Saves the image to a file. The file format is determined from the file extension.
601
+ #
602
+ # Useful for, e.g., pre-rendering text on a development machine where the necessary fonts are known to be available.
603
+ #
604
+ # @return [void]
605
+ # @param filename [String] the path to save the file under.
401
606
  def save(filename); end
402
607
  end
403
608
 
609
+ ##
404
610
  # A sample is a short sound that is completely loaded in memory, can be
405
611
  # played multiple times at once and offers very flexible playback
406
612
  # parameters. Use samples for everything that's not music.
613
+ #
614
+ # @see Gosu::Song
407
615
  class Sample
616
+ ##
617
+ # Loads a sample from a file.
618
+ #
619
+ # @param window [Gosu::Window]
620
+ # @param filename [String] the path to load the sample from.
408
621
  def initialize(window, filename); end
409
622
 
623
+ ##
410
624
  # Plays the sample without panning.
625
+ #
626
+ # Playback speed is limited only by the underlying audio library, and both very large and very small values should work just fine.
411
627
  #
412
- # Returns a SampleInstance.
413
- # volume:: Can be anything from 0.0 (silence) to 1.0 (full volume).
414
- # 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.
415
- def play(vol=1, speed=1, looping=false); end
416
-
417
- # Plays the sample with panning. Even if pan is 0.0, the sample will
418
- # not be as loud as if it were played by calling play() due to the
419
- # way the panning works.
628
+ # @return [SampleInstance]
629
+ # @param volume [Float] the playback volume, in the range (0..1), where 0 is completely silent and 1 is full volume.
630
+ # @param speed [Float] the playback speed.
631
+ # @param looping [true, false] whether the sample should play in a loop.
632
+ #
633
+ # @see #play_pan
634
+ def play(volume=1, speed=1, looping=false); end
635
+
636
+ ##
637
+ # Plays the sample with panning.
638
+ #
639
+ # @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.
420
640
  #
421
- # Returns a SampleInstance.
422
- # volume:: Can be anything from 0.0 (silence) to 1.0 (full volume).
423
- # 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.
424
- def play_pan(pan=0, vol=1, speed=1, looping=false); end
641
+ # @return [SampleInstance]
642
+ # @param pan [Float] the amount of panning. 0 is centered.
643
+ # @param (see #play)
644
+ #
645
+ # @see #play
646
+ def play_pan(pan=0, volume=1, speed=1, looping=false); end
425
647
  end
426
648
 
427
- # An instance of a Sample playing. Can be used to stop sounds dynamically,
428
- # or to check if they are finished.
429
- # It is recommended that you throw away sample instances if possible,
430
- # as they could accidentally refer to other sounds being played after
431
- # a very long time has passed.
649
+ ##
650
+ # An instance of a {Gosu::Sample} playing. Can be used to stop sounds dynamically, or to check if they are finished.
651
+ #
652
+ # 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.
432
653
  class SampleInstance
433
654
  attr_writer :volume
434
655
  attr_writer :speed
435
656
  attr_writer :pan
436
657
 
437
- # 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.
658
+ ##
659
+ # Stops playback of this sample instance. After calling this method, the sample instance is useless and can be discarded.
660
+ #
661
+ # Calling `stop` after the sample has finished is harmless and has no effect.
662
+ #
663
+ # @return [void]
438
664
  def stop; end
439
- # Pauses this instance to be resumed afterwards. It will still keep a channel filled while paused.
665
+
666
+ ##
667
+ # Pauses the sample, to be resumed afterwards.
668
+ #
669
+ # @note The sample will still occupy a playback channel while paused.
670
+ #
671
+ # @return [void]
440
672
  def pause; end
441
- def paused?; end
673
+
674
+ ##
675
+ # Resumes playback of the sample.
676
+ #
677
+ # @return [void]
442
678
  def resume; end
679
+
680
+ ##
681
+ # @return [true, false] whether the sample is paused.
682
+ def paused?; end
683
+
684
+ ##
685
+ # @return [true, false] whether the sample is playing.
443
686
  def playing?; end
444
687
  end
445
688
 
446
- # Songs are less flexible than samples in that they can only be played
447
- # one at a time and without panning or speed parameters.
689
+ ##
690
+ # Songs are less flexible than samples in that only one can be played at a time, with no panning or speed control.
691
+ #
692
+ # @see Gosu::Sample
448
693
  class Song
449
- # Returns the song currently being played or paused, or nil if
450
- # no song has been played yet or the last song has finished
451
- # playing.
452
- def self.current_song; end
453
-
694
+ class <<Song
695
+ ##
696
+ # Returns the song currently being played (even if it's paused), or nil if no song is playing.
697
+ #
698
+ # @return [Gosu::Song?] the currently playing song.
699
+ attr_reader :current_song
700
+ end
701
+
702
+ ##
703
+ # @return [Float] the song's playback volume.
454
704
  attr_accessor :volume
455
705
 
706
+ ##
707
+ # Loads a song from a file.
708
+ #
709
+ # @param window [Gosu::Window]
710
+ # @param filename [String] the path to load the song from.
456
711
  def initialize(window, filename); end
457
712
 
458
- # Starts or resumes playback of the song. This will stop all other
459
- # songs and set the current song to this object.
713
+ ##
714
+ # Starts or resumes playback of the song.
715
+ #
716
+ # If another song is currently playing, it will be stopped and this song will be set as the current song.
717
+ #
718
+ # If `looping` is false, the current song will be set to `nil` when this song finishes.
719
+ #
720
+ # @return [void]
721
+ # @param looping [true, false] whether the song should play in a loop.
460
722
  def play(looping=false); end
461
723
 
462
- # Pauses playback of the song. It is not considered being played.
463
- # current_song will stay the same.
724
+ ##
725
+ # Pauses playback of the song. The current song is unchanged.
726
+ #
727
+ # @return [void]
464
728
  def pause; end
465
729
 
466
- # Returns true if the song is the current song, but in paused
467
- # mode.
730
+ # Returns true if this song is the current song and playback is paused.
731
+ #
732
+ # @return [true, false] whether the song is paused.
468
733
  def paused?; end
469
734
 
470
- # Stops playback of this song if it is currently played or paused.
471
- # Afterwards, current_song will return 0.
735
+ ##
736
+ # Stops playback if this song is the current song. The current song is set to `nil`.
737
+ #
738
+ # @return [void]
472
739
  def stop; end
473
740
 
474
- # Returns true if the song is currently playing.
741
+ ##
742
+ # @return [true, false] whether the song is playing.
475
743
  def playing?; end
476
744
  end
477
745
 
478
- # TextInput instances are invisible objects that build a text string from input,
479
- # using the current operating system's keyboard layout.
746
+ ##
747
+ # A TextInput is an invisible object that handles input using the operating system's input manager.
480
748
  #
481
- # At its most basic form, you only need to create a new TextInput instance and
482
- # pass it to your window via text_input=. Until you call this function again,
483
- # passing nil, the TextInput object will build a text that can be accessed via
484
- # TextInput#text.
749
+ # 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}.
485
750
  #
486
- # A TextInput object is purely abstract, though; drawing the input field is left
487
- # to the user. As with most of Gosu, how this is handled is completely left open.
488
- #
489
- # TextInput only aims to provide enough code for your own GUIs to build upon.
751
+ # 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.
752
+ #
753
+ # @see Gosu::Window#text_input
754
+ # @see file:examples/TextInput.rb
490
755
  class TextInput
756
+ ##
757
+ # @return [String] the text that the user has typed.
491
758
  attr_accessor :text
759
+
760
+ ##
761
+ # @return [Fixnum] the position of the editing caret.
492
762
  attr_accessor :caret_pos
763
+
764
+ ##
765
+ # @return [Fixnum] the starting position of the currently selected text.
493
766
  attr_accessor :selection_start
494
767
 
495
- # Overridable filter that is applied to all new text that is entered.
496
- # Allows for context-sensitive filtering/extending/... of the text.
497
- # The text will be inserted at caretPos afterwards.
768
+ ##
769
+ # 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.
770
+ #
771
+ # The return value of this method will be inserted at the current caret position.
772
+ #
773
+ # The default implementation returns its argument unchanged.
774
+ #
775
+ # @return [String] the string to be inserted.
776
+ # @param text_in [String] the text typed by the user.
777
+ #
778
+ # @example Forcing input to all uppercase, alphanumeric characters.
779
+ # input = TextInput.new
780
+ # def input.filter(text_in)
781
+ # text_in.upcase.gsub(/[^A-Z0-9]/, '')
782
+ # end
498
783
  def filter text_in
499
784
  text_in
500
785
  end
501
786
  end
502
787
 
788
+ ##
503
789
  # Main class that serves as the foundation of a standard
504
790
  # Gosu application. Manages initialization of all of Gosu's core components
505
791
  # and provides timing functionality.
@@ -508,195 +794,491 @@ module Gosu
508
794
  # coordinates relative to the window. This means that the mouse position
509
795
  # can be negative or larger than the window size.
510
796
  #
511
- # Note that you should really only use one instance of this class at the same time. This may or may not change later.
512
- #
513
- # Right now, having two or more windows and loading samples or songs on both of them will result in an exception.
797
+ # @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.
514
798
  class Window
799
+ ##
800
+ # @return [String] the window's caption, usually dispalyed in the title bar.
515
801
  attr_accessor :caption
802
+
803
+ ##
804
+ # @return [Fixnum] the mouse pointer's window-based X coordinate.
516
805
  attr_accessor :mouse_x
806
+
807
+ ##
808
+ # @return [Fixnum] the mouse pointer's window-based Y coordinate.
517
809
  attr_accessor :mouse_y
810
+
811
+ ##
812
+ # The currently active {TextInput}. If not nil, all keyboard input will be handled by this object.
813
+ #
814
+ # @return [TextInput?] the currently active text input.
518
815
  attr_accessor :text_input
519
- attr_reader :width, :height
816
+
817
+ ##
818
+ # 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.
819
+ #
820
+ # @return [Fixnum] the window's width, in pixels.
821
+ attr_reader :width
822
+
823
+ ##
824
+ # 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.
825
+ #
826
+ # @return [Fixnum] the window's height, in pixels.
827
+ attr_reader :height
828
+
829
+ ##
830
+ # @return [true, false] whether this is a full-screen window.
520
831
  attr_reader :fullscreen?
832
+
833
+ ##
834
+ # @return [Float] the interval between calls to {#update}, in milliseconds.
521
835
  attr_reader :update_interval
522
836
 
523
- # update_interval:: Interval in milliseconds between two calls
524
- # to the update member function. The default means the game will run
525
- # at 60 FPS, which is ideal on standard 60 Hz TFT screens.
837
+ ##
838
+ # Creates a new window with the requested size.
839
+ #
840
+ # @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.
841
+ #
842
+ # @param width [Fixnum] the desired window width.
843
+ # @param height [Fixnum] the desired window height.
844
+ # @param fullscreen [true, false] whether to create a full-screen window.
845
+ # @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.
526
846
  def initialize(width, height, fullscreen, update_interval=16.666666); end
527
847
 
848
+ ##
528
849
  # Enters a modal loop where the Window is visible on screen and receives calls to draw, update etc.
850
+ #
851
+ # @return [void]
529
852
  def show; end
530
853
 
531
- # Tells the window to end the current show loop as soon as possible.
854
+ ##
855
+ # Tells the window to end the current run loop as soon as possible. Calling this method will not prevent execution of lines after it.
856
+ #
857
+ # @return [void]
532
858
  def close; end
533
859
 
534
- # Called every update_interval milliseconds while the window is being
535
- # shown. Your application's main game logic goes here.
860
+ # @!group Callbacks
861
+
862
+ ##
863
+ # This method is called once every {#update_interval} milliseconds while the window is being shown. Your application's main logic should go here.
864
+ #
865
+ # @return [void]
536
866
  def update; end
537
867
 
538
- # Called after every update and when the OS wants the window to
539
- # repaint itself. Your application's rendering code goes here.
868
+ ##
869
+ # 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.
870
+ #
871
+ # @return [void]
872
+ #
873
+ # @see #needs_redraw?
540
874
  def draw; end
541
875
 
542
- # Can be overriden to give the game a chance to say no to being redrawn.
543
- # This is not a definitive answer. The operating system can still cause
544
- # redraws for one reason or another.
876
+ ##
877
+ # 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.
545
878
  #
546
- # By default, the window is redrawn all the time (i.e. Window#needs_redraw?
547
- # always returns true.)
879
+ # @return [true, false] whether the window needs to be redrawn.
880
+ #
881
+ # @see #draw
548
882
  def needs_redraw?; end
549
883
 
550
- # Can be overriden to show the system cursor when necessary, e.g. in level
551
- # editors or other situations where introducing a custom cursor is not
552
- # desired.
884
+ ##
885
+ # 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.
886
+ #
887
+ # @return [true, false] whether the system cursor should be shown.
553
888
  def needs_cursor?; end
554
889
 
555
- # Called before update when the user pressed a button while the
556
- # window had the focus.
890
+ ##
891
+ # This method is called before {#update} if a button was pressed while the window had focus.
892
+ #
893
+ # @return [void]
894
+ # @param id [Fixnum] the button's platform-defined id.
895
+ #
896
+ # @see #button_up
897
+ # @see #button_down?
557
898
  def button_down(id); end
558
- # Same as buttonDown. Called then the user released a button.
899
+
900
+ ##
901
+ # This method is called before {#update} if a button was released while the window had focus.
902
+ #
903
+ # @return [void]
904
+ # @param (see #button_down)
905
+ #
906
+ # @see #button_down
907
+ # @see #button_down?
559
908
  def button_up(id); end
560
909
 
561
- # Returns true if a button is currently pressed. Updated every tick.
910
+ # @!endgroup
911
+
912
+ ##
913
+ # 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.
914
+ #
915
+ # @return [true, false] whether the button is currently pressed.
916
+ # @param (see #button_down)
917
+ #
918
+ # @see #button_down
919
+ # @see #button_up
562
920
  def button_down?(id); end
563
921
 
564
- # Draws a line from one point to another (last pixel exclusive).
565
- # Note: OpenGL lines are not reliable at all and may have a missing pixel at the start
566
- # or end point. Please only use this for debugging purposes. Otherwise, use a quad or
567
- # image to simulate lines, or contribute a better draw_line to Gosu.
922
+ # @!group Drawing primitives
923
+
924
+ ##
925
+ # Draws a line from one point to another---inconsistently.
926
+ #
927
+ # @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.
928
+ #
929
+ # @return [void]
930
+ # @param x1 [Float] the X coordinate of the start point.
931
+ # @param y1 [Float] the Y coordinate of the start point.
932
+ # @param c1 [Gosu::Color] the color of the start point.
933
+ # @param x2 [Float] the X coordinate of the end point.
934
+ # @param y2 [Float] the Y coordinate of the end point.
935
+ # @param c2 [Gosu::Color] the color of the end point.
936
+ # @param z [Float] the Z-order.
937
+ # @param mode [:default, :additive] the blending mode to use.
938
+ #
939
+ # @see #draw_triangle
940
+ # @see #draw_quad
941
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
942
+ # @see file:reference/Z-Ordering.md
568
943
  def draw_line(x1, y1, c1, x2, y2, c2, z=0, mode=:default); end
569
944
 
945
+ ##
946
+ # Draws a triangle.
947
+ #
948
+ # @return [void]
949
+ # @param x1 [Float] the X coordinate of the first vertex.
950
+ # @param y1 [Float] the Y coordinate of the first vertex.
951
+ # @param c1 [Gosu::Color] the color of the first vertex.
952
+ # @param x2 [Float] the X coordinate of the second vertex.
953
+ # @param y2 [Float] the Y coordinate of the second vertex.
954
+ # @param c2 [Gosu::Color] the color of the second vertex.
955
+ # @param x3 [Float] the X coordinate of the third vertex.
956
+ # @param y3 [Float] the Y coordinate of the third vertex.
957
+ # @param c3 [Gosu::Color] the color of the third vertex.
958
+ # @param z [Float] the Z-order.
959
+ # @param mode [:default, :additive] the blending mode to use.
960
+ #
961
+ # @see #draw_line
962
+ # @see #draw_quad
963
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
964
+ # @see file:reference/Z-Ordering.md
570
965
  def draw_triangle(x1, y1, c1, x2, y2, c2, x3, y3, c3, z=0, mode=:default); end
571
966
 
572
- # Draws a rectangle (two triangles) with given corners and corresponding
573
- # colors.
574
- # The points can be in clockwise order, or in a Z shape.
967
+ ##
968
+ # Draws a quad (actually two triangles).
969
+ #
970
+ # @return [void]
971
+ # @param x1 [Float] the X coordinate of the first vertex.
972
+ # @param y1 [Float] the Y coordinate of the first vertex.
973
+ # @param c1 [Gosu::Color] the color of the first vertex.
974
+ # @param x2 [Float] the X coordinate of the second vertex.
975
+ # @param y2 [Float] the Y coordinate of the second vertex.
976
+ # @param c2 [Gosu::Color] the color of the second vertex.
977
+ # @param x3 [Float] the X coordinate of the third vertex.
978
+ # @param y3 [Float] the Y coordinate of the third vertex.
979
+ # @param c3 [Gosu::Color] the color of the third vertex.
980
+ # @param x4 [Float] the X coordinate of the fourth vertex.
981
+ # @param y4 [Float] the Y coordinate of the fourth vertex.
982
+ # @param c4 [Gosu::Color] the color of the fourth vertex.
983
+ # @param z [Float] the Z-order.
984
+ # @param mode [:default, :additive] the blending mode to use.
985
+ #
986
+ # @see #draw_line
987
+ # @see #draw_triangle
988
+ # @see file:reference/Drawing_with_Colors.md Drawing with Colors
989
+ # @see file:reference/Order_of_Corners.md Order of Corners
990
+ # @see file:reference/Z-Ordering.md
575
991
  def draw_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z=0, mode=:default); end
576
992
 
577
- # Flushes all drawing operations to OpenGL so that Z-ordering can start anew. This
578
- # is useful when drawing several parts of code on top of each other that use conflicting
579
- # z positions.
993
+ # @!endgroup
994
+ # @!group Manipulating the drawing context
995
+
996
+ ##
997
+ # 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.
998
+ #
999
+ # @return [void]
580
1000
  def flush; end
581
1001
 
582
- # For custom OpenGL calls. Executes the given block in a clean OpenGL environment.
583
- # Use the ruby-opengl gem to access OpenGL function (if you manage to get it to work).
584
- # IF no z position is given, it will execute the given block immediately, otherwise,
585
- # the code will be scheduled to be called between Gosu drawing operations.
1002
+ ##
1003
+ # Runs the block in a clean OpenGL environment.
1004
+ #
1005
+ # 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.
1006
+ #
1007
+ # @note Gosu does not provide access to the underlying OpenGL APIs. A gem like ruby-opengl is required to use custom OpenGL drawing code.
586
1008
  #
587
- # Note: You cannot call Gosu rendering functions within this block, and you can only
588
- # call the gl function in the call tree of Window#draw.
589
- #
590
- # See examples/OpenGLIntegration.rb for an example.
591
- def gl(z=nil, &custom_gl_code); end
1009
+ # @note Gosu rendering functions MUST NOT be used within the block, and {#gl} MUST be used only within the call tree of {#draw}.
1010
+ #
1011
+ # @return [void]
1012
+ # @param z [Float] the Z-order.
1013
+ # @yield OpenGL code.
1014
+ #
1015
+ # @see #draw
1016
+ # @see file:reference/Z-Ordering
1017
+ # @see file:examples/OpenGLIntegration.rb
1018
+ def gl(z=nil); end
592
1019
 
593
- # Limits the drawing area to a given rectangle while evaluating the code inside of the block.
594
- def clip_to(x, y, w, h, &rendering_code); end
1020
+ ##
1021
+ # Masks the drawing area inside the block.
1022
+ #
1023
+ # @return [void]
1024
+ # @param x [Float] the X coordinate of the top left corner,.
1025
+ # @param y [Float] the Y coordinate of the top left corner.
1026
+ # @param w [Float] the width of the clipping area.
1027
+ # @param h [Float] the height of the clipping area.
1028
+ # @yield rendering code.
1029
+ #
1030
+ # @see #draw
1031
+ def clip_to(x, y, w, h); end
595
1032
 
596
- # Returns a Gosu::Image that containes everything rendered within the given block. It can be
597
- # used to optimize rendering of many static images, e.g. the map. There are still several
598
- # restrictions that you will be informed about via exceptions.
1033
+ ##
1034
+ # 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.
1035
+ #
1036
+ # @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.
599
1037
  #
600
- # The returned Gosu::Image will have the width and height you pass as arguments, regardless
601
- # of how the area you draw on. It is important to pass accurate values if you plan on using
602
- # Gosu::Image#draw_as_quad or Gosu::Image#draw_rot with the result later.
1038
+ # @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.
603
1039
  #
604
- # @return [Gosu::Image]
605
- def record(width, height, &rendering_code); end
1040
+ # @return [Gosu::Image] the recorded drawing operations.
1041
+ # @param width [Float] the width of the recorded image.
1042
+ # @param height [Float] the height of the recorded image.
1043
+ # @yield rendering code.
1044
+ #
1045
+ # @see #draw
1046
+ # @see Gosu::Image
1047
+ def record(width, height); end
606
1048
 
607
- # Rotates everything drawn in the block around (around_x, around_y).
608
- def rotate(angle, around_x=0, around_y=0, &rendering_code); end
1049
+ ##
1050
+ # Rotates all drawing operatons inside the block.
1051
+ #
1052
+ # @return [void]
1053
+ # @param angle [Float] the rotation angle.
1054
+ # @param around_x [Float] the X coorinate of the rotation origin.
1055
+ # @param around_y [Float] the Y coordinate of the rotation origin.
1056
+ # @yield rendering code.
1057
+ #
1058
+ # @see #draw
1059
+ # @see #scale
1060
+ # @see #translate
1061
+ # @see #transform
1062
+ def rotate(angle, around_x=0, around_y=0); end
609
1063
 
610
- # Scales everything drawn in the block by a factor.
611
- def scale(factor_x, factor_y=factor_x, &rendering_code); end
1064
+ ##
1065
+ # Scales all drawing operations inside the block.
1066
+ #
1067
+ # @overload scale(factor_x, factor_y = factor_x) { ... }
1068
+ # @overload scale(factor_x, factor_y, around_x, around_y) { ... }
1069
+ #
1070
+ # @return [void]
1071
+ # @param factor_x [Float] the horizontal scaling factor.
1072
+ # @param factor_y [Float] the vertical scaling factor.
1073
+ # @param around_x [Float] the X coordinate of the scaling origin.
1074
+ # @param around_y [Float] the Y coordinate of the scaling origin.
1075
+ # @yield rendering code.
1076
+ #
1077
+ # @see #draw
1078
+ # @see #rotate
1079
+ # @see #translate
1080
+ # @see #transform
1081
+ def scale(factor_x, factor_y, around_x, around_y); end
612
1082
 
613
- # Scales everything drawn in the block by a factor for each dimension.
614
- def scale(factor_x, factor_y, around_x, around_y, &rendering_code); end
1083
+ ##
1084
+ # Offsets all drawing operations inside the block.
1085
+ #
1086
+ # @return [void]
1087
+ # @param x [Float] the X offset.
1088
+ # @param y [Float] the Y offset.
1089
+ # @yield rendering code.
1090
+ #
1091
+ # @see #draw
1092
+ # @see #rotate
1093
+ # @see #scale
1094
+ # @see #transform
1095
+ def translate(x, y); end
615
1096
 
616
- # Moves everything drawn in the block by an offset in each dimension.
617
- def translate(x, y, &rendering_code); end
1097
+ ##
1098
+ # Applies a free-form matrix transformation to everything drawn in the block.
1099
+ #
1100
+ # @return [void]
1101
+ # @param m0 [Float]
1102
+ # @param m1 [Float]
1103
+ # @param m2 [Float]
1104
+ # @param m3 [Float]
1105
+ # @param m4 [Float]
1106
+ # @param m5 [Float]
1107
+ # @param m6 [Float]
1108
+ # @param m7 [Float]
1109
+ # @param m8 [Float]
1110
+ # @param m9 [Float]
1111
+ # @param m10 [Float]
1112
+ # @param m11 [Float]
1113
+ # @param m12 [Float]
1114
+ # @param m13 [Float]
1115
+ # @param m14 [Float]
1116
+ # @param m15 [Float]
1117
+ # @yield rendering code.
1118
+ #
1119
+ # @see #draw
1120
+ # @see #rotate
1121
+ # @see #scale
1122
+ # @see #translate
1123
+ def transform(m0, m1, m2, m3, m4, m5, m6, m7, m8, m9, m10, m11, m12, m13, m14, m15); end
618
1124
 
619
- # Applies a free-form matrix rotation to everything drawn in the block.
620
- def transform(m0, m1, m2, m3, m4, m5, m6, m7, m8, m9, m10, m11, m12, m13, m14, m15, &rendering_code); end
1125
+ # @!endgroup
621
1126
 
622
- # Returns the character a button usually produces, or nil. To implement real text-input
623
- # facilities, look at the TextInput class instead.
1127
+ ##
1128
+ # Returns the character a button usually produces, if any.
1129
+ #
1130
+ # @note For real text input, look at {TextInput} instead.
1131
+ #
1132
+ # @return [String?] the character the button usually produces.
1133
+ # @param id [Fixnum] the button's platform-defined id.
1134
+ #
1135
+ # @see char_to_button_id
1136
+ # @see #text_input
1137
+ # @see TextInput
624
1138
  def self.button_id_to_char(id); end
625
1139
 
626
- # Returns the button that has to be pressed to produce the given character, or nil.
1140
+ ##
1141
+ # Returns the button that usually produces a character, if any.
1142
+ #
1143
+ # @return [Fixnum?] the button that usually produces the character.
1144
+ # @param char [String] the character to query.
1145
+ #
1146
+ # @see button_id_to_char
1147
+ # @see #text_input
1148
+ # @see TextInput
627
1149
  def self.char_to_button_id(char); end
628
1150
 
629
- # @deprecated Use Window#mouse_x= and Window#mouse_y= instead.
1151
+ ##
1152
+ # @deprecated Use {#mouse_x=} and {#mouse_y=} instead.
630
1153
  def set_mouse_position(x, y); end
631
1154
  end
632
1155
 
633
- # Contains information about the underlying OpenGL texture and the u/v space used for image data.
1156
+ ##
1157
+ # Holds information about the underlying OpenGL texture and UV coordinates of an image.
634
1158
  #
635
- # 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.)
1159
+ # Can be retrieved from some images to use them in OpenGL operations.
636
1160
  #
637
- # See examples/OpenGLIntegration.rb.
1161
+ # @see Gosu::Image#gl_tex_info
1162
+ # @see file:examples/OpenGLIntegration.rb
638
1163
  class GLTexInfo
639
- attr_reader :tex_name, :left, :right, :top, :bottom
1164
+ ##
1165
+ # @return [Fixnum] OpenGL texture id
1166
+ attr_reader :tex_name
1167
+
1168
+ ##
1169
+ # @return [Float] the U coordinate of the left edge of the image.
1170
+ attr_reader :left
1171
+
1172
+ ##
1173
+ # @return [Float] the U coordinate of the right edge of the image.
1174
+ attr_reader :right
1175
+
1176
+ ##
1177
+ # @return [Float] the V coordinate of the top edge of the image.
1178
+ attr_reader :top
1179
+
1180
+ ##
1181
+ # @return [Float] the V coordinate of the bottom edge of the image.
1182
+ attr_reader :bottom
640
1183
  end
641
1184
 
642
1185
  class << self
643
- # Returns a random double between min (inclusive) and max (exclusive).
1186
+ ##
1187
+ # @return [Float] a random number in the range (min...max).
1188
+ # @param min [Float] the minimum value, inclusive.
1189
+ # @param max [Float] the maximum value, exclusive.
644
1190
  def random(min, max); end
645
1191
 
646
- # 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.
647
- def offset_x(angle, dist); end
1192
+ ##
1193
+ # @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.
1194
+ # @param theta [Float]
1195
+ # @param r [Float]
1196
+ def offset_x(theta, r); end
648
1197
 
649
- # 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.
650
- def offset_y(angle, dist); end
1198
+ ##
1199
+ # @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.
1200
+ # @param theta [Float]
1201
+ # @param r [Float]
1202
+ def offset_y(theta, r); end
651
1203
 
652
- # Returns the angle from point 1 to point 2 in degrees, where 0.0 means upwards. Returns 0 if both points are equal.
1204
+ ##
1205
+ # @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.
1206
+ # @param x1 [Float]
1207
+ # @param y1 [Float]
1208
+ # @param x2 [Float]
1209
+ # @param y2 [Float]
653
1210
  def angle(x1, y1, x2, y2); end
654
1211
 
655
- # Returns the smallest angle that can be added to angle1 to get to angle2 (can be negative if counter-clockwise movement is shorter).
1212
+ ##
1213
+ # @return [Float] the shortest angular distance from angle1 to angle2. This can be negative if counter-clockwise rotation would yield a shorter distance.
1214
+ # @param angle1 [Float]
1215
+ # @param angle2 [Float]
656
1216
  def angle_diff(angle1, angle2); end
657
1217
 
658
- # Returns the distance between two points.
1218
+ ##
1219
+ # @return [Float] the distance from (x1, y1) to (x2, y2).
1220
+ # @param x1 [Float]
1221
+ # @param y1 [Float]
1222
+ # @param x2 [Float]
1223
+ # @param y2 [Float]
659
1224
  def distance(x1, y1, x2, y2); end
660
1225
 
661
- # Incrementing, possibly wrapping millisecond timer.
1226
+ ##
1227
+ # @note For long-running games, this counter will eventually wrap around to 0 again.
1228
+ #
1229
+ # @return [Fixnum] the number of milliseconds elapsed.
662
1230
  def milliseconds(); end
663
1231
 
664
- # Return current framerate (frames per second.)
1232
+ ##
1233
+ # @return [Fixnum] the current framerate, in frames per second.
665
1234
  def fps(); end
666
1235
 
667
- # Returns the name of a neutral font that is available on the current
668
- # platform.
1236
+ # @return [String] the name of a neutral font that is available on the current platform.
1237
+ #
1238
+ # @see Gosu::Font
1239
+ # @see Gosu::Image#from_text
669
1240
  def default_font_name(); end
670
1241
 
671
- # Returns the width, in pixels, of the user's primary screen.
1242
+ ##
1243
+ # @return [Fixnum] the width, in pixels, of the user's primary screen.
672
1244
  def screen_width(); end
673
1245
 
674
- # Returns the height, in pixels, of the user's primary screen.
1246
+ # @return [Fixnum] the height, in pixels, of the user's primary screen.
675
1247
  def screen_height(); end
676
1248
 
677
- # Returns the user's preferred language, at the moment of calling the function. Expect return
678
- # values such as 'en_US', 'de_DE.UTF-8', 'ja', 'zh-Hans'. You can rely only on the first two letters
679
- # being a common language abbreviation.
1249
+ ##
1250
+ # 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.
1251
+ #
1252
+ # @return [String] the user's preferred language.
680
1253
  def language(); end
681
1254
  end
682
1255
  end
683
1256
 
1257
+ ##
684
1258
  # Small additions to Numeric to make it easier to integrate Gosu with
685
1259
  # libraries that use radians, like Chipmunk.
686
1260
  class ::Numeric
687
- # Returns <tt>self * 180.0 / Math::PI + 90</tt>.
688
- # Translates between Gosu's angle system (where 0° is at the top) and
689
- # radians (where 0 is at the right).
1261
+ ##
1262
+ # Converts radians to a Gosu-compatible angle using the formula <tt>self * 180.0 / Math::PI + 90</tt>.
1263
+ #
1264
+ # @return [Float] degrees.
690
1265
  def radians_to_gosu(); end
691
1266
 
692
- # Returns <tt>(self - 90) * Math::PI / 180.0</tt>
693
- # Translates between Gosu's angle system (where is at the top) and
694
- # radians (where 0 is at the right).
1267
+ ##
1268
+ # Converts a Gosu-compatible angle to radians using the formula <tt>(self - 90) * Math::PI / 180.0</tt>.
1269
+ #
1270
+ # @return [Float] radians.
695
1271
  def gosu_to_radians(); end
696
1272
 
697
- # Scales a degree value to radians.
1273
+ ##
1274
+ # Converts degrees to radians.
1275
+ #
1276
+ # @return [Float] radians.
698
1277
  def degrees_to_radians(); end
699
1278
 
700
- # Scales a radian value to degrees.
1279
+ ##
1280
+ # Converts radians to degrees.
1281
+ #
1282
+ # @return [Float] degrees.
701
1283
  def radians_to_degrees(); end
702
1284
  end