-
Notifications
You must be signed in to change notification settings - Fork 174
/
gosu.rb
1248 lines (1106 loc) · 45.5 KB
/
gosu.rb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# Encoding: UTF-8
module Gosu
##
# The first component of the version.
MAJOR_VERSION = :an_integer
##
# The second component of the version.
MINOR_VERSION = :an_integer
##
# The third component of the version.
POINT_VERSION = :an_integer
##
# A version string of the form "0.1.2", "0.1.2.3" or "0.1.2pre4".
VERSION = :a_string
##
# @deprecated Use LICENSES instead as it's a more appropriate name
GOSU_COPYRIGHT_NOTICE = :a_string
##
# A block of legal copy that your game is obliged to display somewhere.
LICENSES = :a_string
KB_0…KB_9 = :an_integer
KB_A…KB_Z = :an_integer
KB_APOSTROPHE = :an_integer
KB_BACKSLASH = :an_integer
KB_BACKSPACE = :an_integer
KB_BACKTICK = :an_integer
KB_COMMA = :an_integer
KB_DELETE = :an_integer
KB_DOWN = :an_integer
KB_END = :an_integer
##
# This is the key on the numpad.
KB_ENTER = :an_integer
KB_EQUALS = :an_integer
KB_ESCAPE = :an_integer
KB_F1…KB_F12 = :an_integer
KB_HOME = :an_integer
KB_INSERT = :an_integer
KB_ISO = :an_integer
KB_LEFT = :an_integer
KB_LEFT_ALT = :an_integer
KB_LEFT_BRACKET = :an_integer
KB_LEFT_CONTROL = :an_integer
KB_LEFT_META = :an_integer
KB_LEFT_SHIFT = :an_integer
KB_MINUS = :an_integer
KB_NUMPAD_0…KB_NUMPAD_9 = :an_integer
KB_NUMPAD_DIVIDE = :an_integer
KB_NUMPAD_MINUS = :an_integer
KB_NUMPAD_MULTIPLY = :an_integer
KB_NUMPAD_PLUS = :an_integer
KB_PAGE_DOWN = :an_integer
KB_PAGE_UP = :an_integer
KB_PERIOD = :an_integer
##
# This is the key above the right shift key.
KB_RETURN = :an_integer
KB_RIGHT = :an_integer
KB_RIGHT_ALT = :an_integer
KB_RIGHT_BRACKET = :an_integer
KB_RIGHT_CONTROL = :an_integer
KB_RIGHT_META = :an_integer
KB_RIGHT_SHIFT = :an_integer
KB_SEMICOLON = :an_integer
KB_SLASH = :an_integer
KB_SPACE = :an_integer
KB_TAB = :an_integer
KB_UP = :an_integer
MS_LEFT = :an_integer
MS_MIDDLE = :an_integer
MS_RIGHT = :an_integer
MS_WHEEL_DOWN = :an_integer
MS_WHEEL_UP = :an_integer
MS_OTHER_0…MS_OTHER_7 = :an_integer
GP_BUTTON_0…GP_BUTTON_15 = :an_integer
GP_DOWN = :an_integer
GP_LEFT = :an_integer
GP_RIGHT = :an_integer
GP_UP = :an_integer
GP_0_BUTTON_0…GP_3_BUTTON_15 = :an_integer
GP_0_DOWN…GP_3_DOWN = :an_integer
GP_0_LEFT…GP_3_LEFT = :an_integer
GP_0_RIGHT…GP_3_RIGHT = :an_integer
GP_0_UP…GP_3_UP = :an_integer
##
# 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
##
# @return [Fixnum] the color's alpha channel.
attr_accessor :alpha
##
# @return [Fixnum] the color's red channel.
attr_accessor :red
##
# @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
##
# @return [Float] the color's value in the range (0..1).
attr_accessor :value
# @!group Creating colors.
##
# @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
##
# @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
# 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 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
# @!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
##
# @return [Color] a copy of the color.
def dup; end
NONE = Gosu::Color.argb(0x00_000000)
BLACK = Gosu::Color.argb(0xff_000000)
GRAY = Gosu::Color.argb(0xff_808080)
WHITE = Gosu::Color.argb(0xff_ffffff)
AQUA = Gosu::Color.argb(0xff_00ffff)
RED = Gosu::Color.argb(0xff_ff0000)
GREEN = Gosu::Color.argb(0xff_00ff00)
BLUE = Gosu::Color.argb(0xff_0000ff)
YELLOW = Gosu::Color.argb(0xff_ffff00)
FUCHSIA = Gosu::Color.argb(0xff_ff00ff)
CYAN = Gosu::Color.argb(0xff_00ffff)
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 {Gosu::Image#from_text}.
class Font
##
# 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
##
# @return [Fixnum] the font's height in pixels.
attr_reader :height
##
# Load a font from the system fonts or a file.
#
# (Passing a Window reference is not necessary anymore, please use the first overload from now on.)
#
# @param height [Fixnum] the height of the font, in pixels.
# @param [Hash] options
# @option options [String] :name 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.
#
# @overload initialize(height, options = {})
# @overload initialize(window, font_name, height)
def initialize(height, options = {}); end
##
# 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
# @!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 scale_x [Float] the horizontal scaling factor.
# @param scale_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 https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw(text, x, y, z, scale_x=1, scale_y=1, color=0xff_ffffff, mode=:default); end
##
# 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 https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw_rel(text, x, y, z, rel_x, rel_y, scale_x=1, scale_y=1, color=0xff_ffffff, mode=:default); end
##
# @deprecated Use {#draw} in conjunction with {Gosu.rotate} instead.
#
# @see #draw
# @see Gosu::Window#rotate
def draw_rot(text, x, y, z, angle, scale_x=1, scale_y=1, color=0xff_ffffff, 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, scale_x=1); end
end
##
# Provides functionality for drawing rectangular images.
class Image
##
# @return [Fixnum] the image's width, in pixels.
attr_reader :width
##
# @return [Fixnum] the image's height, in pixels.
attr_reader :height
# @!group Creating and loading images
##
# Loads an image from a file or an RMagick image.
#
# (Passing a Window reference is not necessary anymore, please use the first overload from now on.)
#
# @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.
#
# @param [String, Magick::Image] source the filename or RMagick image to load from.
# @param [Hash] options
# @option options [true, false] :tileable (false) if true, the Image will not have soft edges when scaled
# @option options [true, false] :retro (false) if true, the image will not be interpolated when it is scaled up or down. When :retro it set, :tileable has no effect.
# @option options [Array] :rect ([0, 0, image_width, image_height]) the source rectangle in the image
#
# @overload initialize(source, options = {})
# @overload initialize(window, source, tileable = false)
# @overload initialize(window, source, tileable, left, top, width, height)
#
# @see load_tiles
# @see from_text
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#tileability Tileability explained in the Gosu Wiki
def initialize(source, options = {}); end
##
# Creates a reusable image from one or more lines of text.
#
# (Passing a Window reference is not necessary anymore, please use the first overload from now on.)
#
# @note 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(text, line_height, options = {})
# @overload from_text(window, text, font_name, line_height)
# @overload from_text(window, text, font_name, line_height, line_spacing, width, align)
#
# @return [Gosu::Image]
# @param [String] text
# @param [Fixnum] line_height the line height, in pixels.
# @param [Hash] options
# @option options [String] :font (Gosu::default_font_name) 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.
# @option options [Fixnum] :width the width of the image, in pixels. Long lines will be automatically wrapped around to avoid overflow, but overlong words will be truncated. If this option is omitted, lines will not be wrapped, and :align and :spacing will be ignored as well.
# @option options [Fixnum] :spacing (0) the spacing between lines, in pixels.
# @option options [:left, :right, :center, :justify] :align (:left) the text alignment.
# @option options [true, false] :retro (false) if true, the image will not be interpolated when it is scaled up or down.
#
# @see Gosu::Font
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
def self.from_text(text, line_height, options = {}); 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.
#
# @return [Array<Gosu::Image>]
# @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 [Hash] options
# @option options [true, false] :tileable (false) if true, the Image will not have soft edges when scaled
# @option options [true, false] :retro (false) if true, the image will not be interpolated when it is scaled up or down. When :retro it set, :tileable has no effect.
#
# @overload load_tiles(source, tile_width, tile_height, options = {})
# @overload load_tiles(window, source, tile_width, tile_height, tileable)
#
# (Passing a Window reference is not necessary anymore, please use the first overload from now on.)
#
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#tileability Tileability explained in the Gosu Wiki
def self.load_tiles(source, tile_width, tile_height, options = {}); end
##
# EXPERIMENTAL - MAY DISAPPEAR WITHOUT WARNING.
#
# Returns an image that is a smaller, rectangular view of this {Image}.
#
# This is a very fast operation, and no new textures are allocated.
# If you update this {Image} or the {#subimage} using {#insert}, the other {Image} will be affected as well.
#
# This method can be used to load texture atlases created with third-party tools.
# The texture atlas must be a power of two (512x512 or 1024x1024) and loaded with :tileable => true.
# The individual {Image}s can then be loaded efficiently with {#subimage}.
# {#gl_tex_info} will work on a {#subimage}.
#
# Caveats:
# * {#subimage} only works if the image lives on a single texture.
# If the image was too large and had to be split up into several OpenGL textures, subimage will return nil (same as {#gl_tex_info}).
# * If you stretch or rotate a {#subimage}, the pixels adjacent to it might bleed into it, as Gosu does not manage the 'tileability' of subimages.
#
# If you find a good way to use {#subimage}, please let us know on the forum and we can make this a part of Gosu's stable interface.
# Thank you!
#
# @return [Image?] an image that represents a portion of the containing image
def subimage(left, top, width, height); end
# @!endgroup
# @!group Drawing an image
##
# Draws the image with its top left corner at (x, y).
#
# @return [void]
# @param x [Float] the X coordinate.
# @param y [Float] the Y coordinate.
# @param z [Float] the Z-order.
# @param scale_x [Float] the horizontal scaling factor.
# @param scale_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 https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw(x, y, z, scale_x=1, scale_y=1, color=0xff_ffffff, mode=:default); end
##
# 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 https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw_rot(x, y, z, angle, center_x=0.5, center_y=0.5, scale_x=1, scale_y=1, color=0xff_ffffff, mode=:default); end
##
# 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.draw_quad)
#
# @see #draw
# @see Gosu.draw_quad
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#order-of-corners The order of corners explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw_as_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z, mode=:default); end
# @!endgroup
##
# 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 packed RGBA values, useful for use with RMagick (Magick::Image.from_blob).
#
# magick_image = Magick::Image.from_blob(image.to_blob) {
# self.format = "RGBA"
# self.size = "#{image.width}x#{image.height}"
# self.depth = 8
# }.first
#
# @return [String] a binary string of packed RGBA values.
def to_blob; end
##
# 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.
#
# @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 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.
#
# (Passing a Window reference is not necessary anymore, please use the first overload from now on.)
#
# @overload initialize(filename)
# @overload initialize(window, filename)
#
# @param filename [String] the path to load the sample from.
def initialize(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.
#
# @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.
#
# @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 {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 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 the sample, to be resumed afterwards.
#
# @note The sample will still occupy a playback channel while paused.
#
# @return [void]
def pause; 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 only one can be played at a time, with no panning or speed control.
#
# @see Gosu::Sample
class Song
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.
#
# (Passing a Window reference is not necessary anymore, please use the first overload instead.)
#
# @overload initialize(filename)
# @overload initialize(window, filename)
#
# @param filename [String] the path to load the song from.
def initialize(filename); end
##
# 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. The current song is unchanged.
#
# @return [void]
def pause; end
# 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 if this song is the current song. The current song is set to `nil`.
#
# @return [void]
def stop; end
##
# @return [true, false] whether the song is playing.
def playing?; end
end
##
# A TextInput is an invisible object that handles input using the operating system's input manager.
#
# 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}.
#
# 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
##
# 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.
#
# Note that all coordinates, even the mouse position, are in client coordinates, relative to the window’s top left corner.
# This means that the mouse position can be negative or larger than the window size.
#
# @note There should really only be one instance of this class at a time. This may or may not change later.
class Window
##
# @return [String] the window's caption, usually displayed in the title bar.
attr_accessor :caption
##
# @return [Float] the mouse pointer's window-based X coordinate.
attr_accessor :mouse_x
##
# @return [Float] 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, if any.
attr_accessor :text_input
##
# 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_accessor :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_accessor :height
##
# @return [true, false] whether this is a fullscreen window.
def fullscreen?; end
##
# Toggles between windowed mode and fullscreen.
attr_writer :fullscreen
##
# @return [Float] the interval between calls to {#update}, in milliseconds.
attr_accessor :update_interval
##
# 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.
#
# @overload initialize(width, height, options = {})
# @overload initialize(width, height, fullscreen, update_interval = 16.666666)
#
# @param width [Fixnum] the desired window width.
# @param height [Fixnum] the desired window height.
# @param [Hash] options
# @option options [true, false] :fullscreen (false) whether to present the window in fullscreen mode.
# @option options [Float] :update_interval (16.666666) the interval between frames, in milliseconds.
def initialize(width, height, options); end
##
# Enters a modal loop where the Window is visible on screen and receives calls to draw, update etc.
#
# @return [void]
def show; end
##
# EXPERIMENTAL - MAY DISAPPEAR WITHOUT WARNING.
#
# Performs a single step in the main loop.
# This can be useful for integrating Gosu with other libraries that have their own main loop, e.g. Ruby/Tk.
#
# See: https://www.libgosu.org/cgi-bin/mwf/topic_show.pl?tid=1218
#
# If you find a good way to use {#tick}, please let us know on the forum and we can make this a part of Gosu's stable interface.
# Thank you!
#
# @return [true, false] whether the {Window} should still be shown after this tick
def tick; end
##
# 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
# @!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
##
# 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
##
# 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.
#
# @return [true, false] whether the window needs to be redrawn.
#
# @see #draw
def needs_redraw?; end
##
# 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
##
# 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 Gosu.button_down?
def button_down(id); end
##
# 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 Gosu.button_down?
def button_up(id); end
# @!endgroup
##
# @deprecated Use {#mouse_x=} and {#mouse_y=} instead.
def set_mouse_position(x, y); end
end
##
# 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.
#
# @see Gosu::Image#gl_tex_info
# @see file:examples/OpenGLIntegration.rb
class GLTexInfo
##
# @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 whether the button `id` is currently pressed. Button states are updated once per tick, so repeated calls during the same tick will always yield the same result.
#
# @return [true, false] whether the button is currently pressed.
# @param (see #button_down)
#
# @see Window#button_down
# @see Window#button_up
def button_down?(id); end
# @!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 https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
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_rect
# @see draw_quad
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw_triangle(x1, y1, c1, x2, y2, c2, x3, y3, c3, z=0, mode=:default); end
##
# Draws a rectangle (actually a quad, or two triangles).
#
# @return [void]
# @param x [Float] the X coordinate of the rectangle’s top left corner.
# @param y [Float] the Y coordinate of the rectangle’s top left corner.
# @param width [Float] the width of the rectangle.
# @param height [Float] the height of the rectangle.
# @param c [Gosu::Color] the color of the rectangle.
# @param z [Float] the Z-order.
# @param mode [:default, :additive] the blending mode to use.
#
# @see draw_line
# @see draw_triangle
# @see draw_quad
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#order-of-corners The order of corners explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw_rect(x, y, width, height, c, z=0, mode=:default); end
##
# 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 draw_rect
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#drawing-with-colours Drawing with colors, explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#order-of-corners The order of corners explained in the Gosu Wiki
# @see https://github.com/gosu/gosu/wiki/Basic-Concepts#z-ordering Z-ordering explained in the Gosu Wiki
def draw_quad(x1, y1, c1, x2, y2, c2, x3, y3, c3, x4, y4, c4, z=0, mode=:default); end
# @!endgroup
# @!group Manipulating the current 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
##
# 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 Gosu rendering functions MUST NOT be used within the block, and {gl} MUST be used only within the call tree of {Window#draw}.
#
# @return [void]
# @param z [Float] the Z-order.