gosu 1.1.0.pre2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70dc24184a235da8dc66f4bac07da231b87ab9f4a7469d06331ba048da6bc5b6
-  data.tar.gz: 0fab031220b2912e66d29e53e1c4dbee51823e042b75927e31415bca59056ac3
+  metadata.gz: 7d58f7d332c57be8c599f33a6c60df54d7143e6ef2980eacd1a84f5d51f7a26a
+  data.tar.gz: e22cf468c5392985d6429aac77b958d71c63c33ac40a4a06b1f01187837bb224
 SHA512:
-  metadata.gz: 59567c7edd20676430b16a27f260fb64f6309d992215cf5f3e22cf8311d39a263945836b040ebd46cb9ee4e0e9a430a0cc1f84d35fc8b3ea8f1ca4b79b170bb6
-  data.tar.gz: 31afdb7a4465c4c59002a2a044202b43803db915c9ae6940fb87606b51e9907707591db591d6baa60c1aadf89104a045a12bfdeb81e7c80bed76dfb9d8284709
+  metadata.gz: 69605aee52675d916c27e58ad596d294ea4268e24520b137a2afa184a38f92b4120646a1e0c3ada0e6293088db9f965adf907a99b164052ee741b81cfd2a779c
+  data.tar.gz: 55615664e9ababb8ee986af01191a296b364d53d42986fcd45a94436b33f4d59aa46643da62a14e0e0a960def6a699d782f03bf74876c70405e4f6ec4d8591df

data/COPYING

@@ -1,4 +1,4 @@
-Copyright (C) 2001-2020 Julian Raschke, Jan Lücker and all contributors.
+Copyright (C) 2001-2021 Julian Raschke, Jan Lücker and all contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),

data/ext/gosu/extconf.rb

@@ -51,7 +51,7 @@ if windows
   else
     $LDFLAGS << "  -L../../dependencies/al_soft/x86 -L../../dependencies/SDL/lib/x86"
   end
-  $LDFLAGS << " -lgdi32 -lwinmm -lOpenGL32 -lOpenAL32 -lSDL2"
+  $LDFLAGS << " -lgdi32 -lwinmm -ldwmapi -lOpenGL32 -lOpenAL32 -lSDL2"
   # Link libstdc++ statically to avoid having another DLL dependency when using Ocra.
   $LDFLAGS << " -static-libstdc++"
 elsif macos
@@ -62,6 +62,10 @@ elsif macos
   # rvm will sometimes try to override this:
   # https://github.com/shawn42/gamebox/issues/96
   $CXXFLAGS << " -stdlib=libc++"
+
+  # Disable an error that is disabled by default and prevents Gosu from building with universal Ruby:
+  # https://trac.macports.org/ticket/58255 / https://github.com/gosu/gosu/issues/424
+  $CXXFLAGS << " -Wno-reserved-user-defined-literal"
   
   # Dependencies.
   $CFLAGS << " #{`sdl2-config --cflags`.chomp}"

data/include/Gosu/Color.hpp

@@ -1,6 +1,3 @@
-//! \file Color.hpp
-//! Interface of the Color class.
-
 #pragma once
 
 #include <Gosu/Platform.hpp>
@@ -8,154 +5,105 @@
 
 namespace Gosu
 {
-    //! Represents an RGBA color value with 8 bits for each channel.
-    //! Can be implicitly constructed from literals of the form 0xaarrggbb.
-    //! Has fast value semantics.
-    //! The four-byte layout in memory is RGBA. On Big-Endian machines the unsigned int will look
-    //! like 0xrrggbbaa, on Little-Endian machines it is 0xaabbggrr.
-    class Color
+    /// Represents an RGBA color value with 8 bit for each channel.
+    /// Can be implicitly constructed from literals of the form 0xaarrggbb.
+    struct Color
     {
-        std::uint32_t rep;
-        #ifdef GOSU_IS_LITTLE_ENDIAN
-        enum { RED_OFFSET = 0, GREEN_OFFSET = 8, BLUE_OFFSET = 16, ALPHA_OFFSET = 24 };
-        #else
-        enum { RED_OFFSET = 24, GREEN_OFFSET = 16, BLUE_OFFSET = 8, ALPHA_OFFSET = 0 };
-        #endif
-        
-    public:
-        typedef std::uint8_t Channel;
         static const unsigned GL_FORMAT = 0x1908; // GL_RGBA
-        
-        //! The default constructor does not initialize the color to any value.
-        Color()
-        {
-        }
-        
-        //! Conversion constructor for literals of the form 0xaarrggbb.
-        Color(unsigned argb)
-        : Color((argb >> 24) & 0xff, (argb >> 16) & 0xff, (argb >> 8) & 0xff, (argb >> 0) & 0xff)
-        {
-        }
-        
-        Color(Channel red, Channel green, Channel blue)
-        : Color(0xff, red, green, blue)
-        {
-        }
-        
-        Color(Channel alpha, Channel red, Channel green, Channel blue)
-        {
-            rep = (alpha << ALPHA_OFFSET) | (red << RED_OFFSET) |
-                  (green << GREEN_OFFSET) | (blue << BLUE_OFFSET);
-        }
-        
-        //! Constructs a color from the given hue/saturation/value triple.
-        //! Ranges of these values are given as 0..360, 0..1, and 0..1, respectively.
-        static Color from_hsv(double h, double s, double v);
-        
-        //! Constructs a color from the given hue/saturation/value triple.
-        //! Ranges of these values are given as 0..360, 0..1, and 0..1, respectively.
-        static Color from_ahsv(Channel alpha, double h, double s, double v);
 
-        Channel red() const
-        {
-            return static_cast<Channel>(rep >> RED_OFFSET);
-        }
-
-        Channel green() const
-        {
-            return static_cast<Channel>(rep >> GREEN_OFFSET);
-        }
+        typedef std::uint8_t Channel;
 
-        Channel blue() const
-        {
-            return static_cast<Channel>(rep >> BLUE_OFFSET);
-        }
+        Channel red, green, blue, alpha;
 
-        Channel alpha() const
+        constexpr Color()
+        : red{0}, green{0}, blue{0}, alpha{0}
         {
-            return static_cast<Channel>(rep >> ALPHA_OFFSET);
         }
 
-        void set_red(Channel value)
+        /// Conversion constructor for literals of the form 0xaarrggbb.
+        // NOLINTNEXTLINE: We want to allow implicit conversions.
+        constexpr Color(std::uint32_t argb)
+        : red{static_cast<Channel>(argb >> 16)}, green{static_cast<Channel>(argb >> 8)},
+          blue{static_cast<Channel>(argb >> 0)}, alpha{static_cast<Channel>(argb >> 24)}
         {
-            rep &= ~(0xff << RED_OFFSET);
-            rep |= value << RED_OFFSET;
         }
 
-        void set_green(Channel value)
+        constexpr Color(Channel red, Channel green, Channel blue)
+        : red{red}, green{green}, blue{blue}, alpha{255}
         {
-            rep &= ~(0xff << GREEN_OFFSET);
-            rep |= value << GREEN_OFFSET;
         }
 
-        void set_blue(Channel value)
+        Color with_alpha(Channel new_alpha)
         {
-            rep &= ~(0xff << BLUE_OFFSET);
-            rep |= value << BLUE_OFFSET;
+            Color result = *this;
+            result.alpha = new_alpha;
+            return result;
         }
 
-        void set_alpha(Channel value)
-        {
-            rep &= ~(0xff << ALPHA_OFFSET);
-            rep |= value << ALPHA_OFFSET;
-        }
+        /// Constructs a color from the given hue/saturation/value triple.
+        /// Ranges of these values are given as 0..360, 0..1, and 0..1, respectively.
+        static Color from_hsv(double h, double s, double v);
 
-        //! Returns the hue of the color, in the usual range of 0..360.
+        /// Returns the hue of the color, in the usual range of 0..360.
         double hue() const;
         
-        //! Changes the current color so hue() will return h.
+        /// Changes the current color so hue() will return h.
         void set_hue(double h);
         
-        //! Returns the saturation of the color, in the range of 0..1.
+        /// Returns the saturation of the color, in the range of 0..1.
         double saturation() const;
         
-        //! Changes the current color so saturation() will return s.
+        /// Changes the current color so saturation() will return s.
         void set_saturation(double s);
         
-        //! Returns the value (brightness) of the color, in the range of 0..1.
+        /// Returns the value (brightness) of the color, in the range of 0..1.
         double value() const;
         
-        //! Changes the current color so value() will return v.
+        /// Changes the current color so value() will return v.
         void set_value(double v);
 
-        //! Returns the color in 0xaarrggbb representation.
-        std::uint32_t argb() const { return alpha() << 24 | red() << 16 | green() << 8 | blue(); }
+        /// Returns the color in 0xaarrggbb representation.
+        std::uint32_t argb() const { return alpha << 24 | red << 16 | green << 8 | blue; }
 
-        //! Returns the color in 0x00bbggrr representation. Useful for Win32 programming.
-        std::uint32_t bgr() const { return blue() << 16 | green() << 8 | red(); }
+        /// Returns the color in 0x00bbggrr representation. Useful for Win32 programming.
+        std::uint32_t bgr() const { return blue << 16 | green << 8 | red; }
+
+        /// Returns the color in 0xaabbggrr representation.
+        std::uint32_t abgr() const { return alpha << 24 | blue << 16 | green << 8 | red; }
+
+        /// Returns the internal representation of the color (RGBA in memory).
+        std::uint32_t gl() const { return *reinterpret_cast<const std::uint32_t*>(this); }
 
-        //! Returns the color in 0xaabbggrr representation.
-        std::uint32_t abgr() const { return alpha() << 24 | blue() << 16 | green() << 8 | red(); }
-        
-        //! Returns the internal representation of the color (RGBA in memory).
-        std::uint32_t gl() const { return rep; }
-        
         static const Color NONE;
         static const Color BLACK;
         static const Color GRAY;
         static const Color WHITE;
-        
+
+        /// Same as Color::CYAN.
         static const Color AQUA;
         static const Color RED;
         static const Color GREEN;
         static const Color BLUE;
         static const Color YELLOW;
         static const Color FUCHSIA;
+        /// Same as Color::AQUA.
         static const Color CYAN;
     };
+
+    // Ensure that we can pass vectors of Gosu::Color straight to OpenGL and back.
+    static_assert(sizeof(Color) == sizeof(std::uint32_t));
     
 #ifndef SWIG
     inline bool operator<(Color a, Color b) { return a.gl() < b.gl(); }
     inline bool operator==(Color a, Color b) { return a.gl() == b.gl(); }
     inline bool operator!=(Color a, Color b) { return a.gl() != b.gl(); }
 
-    //! Interpolates linearly between two colors, with a given weight towards
-    //! the second color.
-    //! Specialization of the general function in Gosu/Math.hpp.
-    Color interpolate(Color a, Color b, double weight = 0.5);
+    /// Interpolates linearly between two colors, with a given weight towards
+    /// the second color.
+    Color lerp(Color a, Color b, double t = 0.5);
     
-    //! Combines two colors as if their channels were mapped to the 0..1 range
-    //! and then multiplied with each other.
+    /// Combines two colors as if their channels were mapped to the 0..1 range
+    /// and then multiplied with each other.
     Color multiply(Color a, Color b);
 #endif
 }

data/include/Gosu/Font.hpp

@@ -22,11 +22,9 @@ namespace Gosu
 
     public:
         //! Constructs a font that can be drawn onto the graphics object.
-        //! \param font_name Name of a system font, or a filename to a TTF
-        //!        file (must contain '/', does not work on Linux).
-        //! \param font_height Height of the font, in pixels.
-        //! \param font_flags Flags used to render individual characters of
-        //!        the font.
+        //! \param name   Name of a system font, or a filename to a TTF file.
+        //! \param height Height of the font, in pixels.
+        //! \param flags  Flags used to render individual characters of the font.
         Font(int height, const std::string& name = default_font_name(), unsigned flags = 0);
         
         //! Returns the name of the font that was used to create it.
@@ -46,11 +44,11 @@ namespace Gosu
         //! Draws text so the top left corner of the text is at (x; y).
         void draw_text(const std::string& text, double x, double y, ZPos z,
                        double scale_x = 1, double scale_y = 1, Color c = Color::WHITE,
-                       AlphaMode mode = AM_DEFAULT) const;
+                       BlendMode mode = BM_DEFAULT) const;
         //! Draws markup so the top left corner of the text is at (x; y).
         void draw_markup(const std::string& markup, double x, double y, ZPos z,
                          double scale_x = 1, double scale_y = 1, Color c = Color::WHITE,
-                         AlphaMode mode = AM_DEFAULT) const;
+                         BlendMode mode = BM_DEFAULT) const;
         
         //! Draws text at a position relative to (x; y).
         //! \param rel_x Determines where the text is drawn horizontally. If
@@ -60,7 +58,7 @@ namespace Gosu
         //! \param rel_y See rel_x.
         void draw_text_rel(const std::string& text, double x, double y, ZPos z,
                            double rel_x, double rel_y, double scale_x = 1, double scale_y = 1,
-                           Color c = Color::WHITE, AlphaMode mode = AM_DEFAULT) const;
+                           Color c = Color::WHITE, BlendMode mode = BM_DEFAULT) const;
         //! Draws text at a position relative to (x; y).
         //! \param rel_x Determines where the text is drawn horizontally. If
         //! rel_x is 0.0, the text will be to the right of x, if it is 1.0,
@@ -69,7 +67,7 @@ namespace Gosu
         //! \param rel_y See rel_x.
         void draw_markup_rel(const std::string& markup, double x, double y, ZPos z,
                              double rel_x, double rel_y, double scale_x = 1, double scale_y = 1,
-                             Color c = Color::WHITE, AlphaMode mode = AM_DEFAULT) const;
+                             Color c = Color::WHITE, BlendMode mode = BM_DEFAULT) const;
         
         //! Maps a letter to a specific image, instead of generating one using
         //! Gosu's built-in text rendering.

data/include/Gosu/Fwd.hpp

@@ -5,7 +5,7 @@ namespace Gosu
     class Bitmap;
     class Buffer;
     class Channel;
-    class Color;
+    struct Color;
     class File;
     class Font;
     class Graphics;

data/include/Gosu/Graphics.hpp

@@ -78,21 +78,23 @@ namespace Gosu
         //! image to simulate lines, or contribute a better draw_line to Gosu.
         static void draw_line(double x1, double y1, Color c1,
                               double x2, double y2, Color c2,
-                              ZPos z, AlphaMode mode = AM_DEFAULT);
+                              ZPos z, BlendMode mode = BM_DEFAULT);
 
         static void draw_triangle(double x1, double y1, Color c1,
                                   double x2, double y2, Color c2,
                                   double x3, double y3, Color c3,
-                                  ZPos z, AlphaMode mode = AM_DEFAULT);
+                                  ZPos z,
+                                  BlendMode mode = BM_DEFAULT);
 
         static void draw_quad(double x1, double y1, Color c1,
                               double x2, double y2, Color c2,
                               double x3, double y3, Color c3,
                               double x4, double y4, Color c4,
-                              ZPos z, AlphaMode mode = AM_DEFAULT);
+                              ZPos z, BlendMode mode = BM_DEFAULT);
         
         static void draw_rect(double x, double y, double width, double height,
-                              Color c, ZPos z, AlphaMode mode = AM_DEFAULT);
+                              Color c, ZPos z,
+                              BlendMode mode = BM_DEFAULT);
 
         //! For internal use only.
         void set_physical_resolution(unsigned physical_width, unsigned physical_height);

data/include/Gosu/GraphicsBase.hpp

@@ -15,18 +15,18 @@ namespace Gosu
     
     //! Determines the way colors are combined when one is drawn onto
     //! another.
-    enum AlphaMode
+    enum BlendMode
     {
-        AM_DEFAULT,
+        BM_DEFAULT,
         //! The color's channels will be interpolated. The alpha channel
         //! specifies the opacity of the new color, 255 is full opacity.
-        AM_INTERPOLATE = AM_DEFAULT,
+        BM_INTERPOLATE = BM_DEFAULT,
         //! The colors' channels will be added. The alpha channel specifies
         //! the percentage of the new color's channels that will be added
         //! to the old color's channels.
-        AM_ADD,
+        BM_ADD,
         //! The color's channels will be multiplied with each other.
-        AM_MULTIPLY
+        BM_MULTIPLY
     };
     
     enum FontFlags
@@ -50,7 +50,7 @@ namespace Gosu
     {
         IF_SMOOTH = 0,
         
-        // Note: No constant for '1', but Gosu treats '1' as if_tileable for
+        // Note: No constant for '1', but Gosu treats '1' as IF_TILEABLE for
         // backward compatibility reasons (this parameter used to be a bool).
         
         IF_TILEABLE_LEFT   = 1 << 1,

data/include/Gosu/Image.hpp

@@ -49,10 +49,10 @@ namespace Gosu
 
         //! Draws the image so its upper left corner is at (x; y).
         void draw(double x, double y, ZPos z = 0, double scale_x = 1, double scale_y = 1,
-            Color c = Color::WHITE, AlphaMode mode = AM_DEFAULT) const;
+            Color c = Color::WHITE, BlendMode mode = BM_DEFAULT) const;
         //! Like draw(), but with modulation colors for all four corners.
         void draw_mod(double x, double y, ZPos z, double scale_x, double scale_y,
-            Color c1, Color c2, Color c3, Color c4, AlphaMode mode = AM_DEFAULT) const;
+            Color c1, Color c2, Color c3, Color c4, BlendMode mode = BM_DEFAULT) const;
 
         //! Draws the image rotated by the given angle so that its rotation
         //! center is at (x; y). Note that this is different from how all the
@@ -65,7 +65,7 @@ namespace Gosu
         //! \param center_y See center_x.
         void draw_rot(double x, double y, ZPos z = 0, double angle = 0,
             double center_x = 0.5, double center_y = 0.5, double scale_x = 1, double scale_y = 1,
-            Color c = Color::WHITE, AlphaMode mode = AM_DEFAULT) const;
+            Color c = Color::WHITE, BlendMode mode = BM_DEFAULT) const;
         
         #ifndef SWIG
         //! Provides access to the underlying image data object.

data/include/Gosu/ImageData.hpp

@@ -44,7 +44,7 @@ namespace Gosu
             double x2, double y2, Color c2,
             double x3, double y3, Color c3,
             double x4, double y4, Color c4,
-            ZPos z, AlphaMode mode) const = 0;
+            ZPos z, BlendMode mode) const = 0;
 
         virtual const GLTexInfo* gl_tex_info() const = 0;
         

data/include/Gosu/Math.hpp

@@ -67,17 +67,7 @@ namespace Gosu
     {
         return value * value;
     }
-    
-    //! Returns min if value is smaller than min, max if value is larger than
-    //! max and value otherwise.
-    template<typename T>
-    T clamp(T value, T min, T max)
-    {
-        if (value < min) return min;
-        if (value > max) return max;
-        return value;
-    }
-    
+
     //! Returns (value-min) % (max-min) + min, where % always has a positive
     //! result for max > min. The results are undefined for max <= min.
     //! Note: This means that max is exclusive.
@@ -100,12 +90,10 @@ namespace Gosu
     //! Returns the distance between two points.
     double distance(double x1, double y1, double x2, double y2);
     
-    //! Interpolates a value between a and b, weight being the bias towards the second value.
-    //! Examples: interpolate(0, 10, 0.5) == 5, interpolate(-10, 10, 0.25) == 5,
-    //! interpolate(0, 10, -0.5) == -5.
+    //! Placeholder for std::lerp, will be removed when Gosu requires C++20.
     template<typename T>
-    T interpolate(T a, T b, double weight = 0.5)
+    T lerp(T a, T b, double t = 0.5)
     {
-        return a * (1.0 - weight) + b * weight;
+        return a * (1.0 - t) + b * t;
     }
 }

data/include/Gosu/Platform.hpp

@@ -1,51 +1,5 @@
-//! \file Platform.hpp
-//! Macros and utility functions to facilitate programming on all of Gosu's supported platforms.
-
 #pragma once
 
-#ifdef __BIG_ENDIAN__
-# define GOSU_IS_BIG_ENDIAN
-# define IDENTITY_FUN big_to_native
-# define IDENTITY_FUN2 native_to_big
-# define CONV_FUN little_to_native
-# define CONV_FUN2 native_to_little
-#else
-# define GOSU_IS_LITTLE_ENDIAN
-# define IDENTITY_FUN little_to_native
-# define IDENTITY_FUN2 native_to_little
-# define CONV_FUN big_to_native
-# define CONV_FUN2 native_to_big
-#endif
-
-#include <algorithm>
-
-namespace Gosu
-{
-    template<typename T> T IDENTITY_FUN(T t) { return t; }
-    template<typename T> T IDENTITY_FUN2(T t) { return t; }
-    
-    template<typename T>
-    T CONV_FUN(T t)
-    {
-        char* begin = reinterpret_cast<char*>(&t);
-        std::reverse(begin, begin + sizeof t);
-        return t;
-    }
-
-    template<typename T> T CONV_FUN2(T t) { return CONV_FUN(t); }
-}
-
-#undef IDENTITY_FUN
-#undef IDENTITY_FUN2
-#undef CONV_FUN
-#undef CONV_FUN2
-
-#if defined(_MSC_VER)
-# define GOSU_NORETURN __declspec(noreturn)
-#elif defined(__GNUC__)
-# define GOSU_NORETURN __attribute__ ((noreturn))
-#endif
-
 #if defined(WIN32) || defined(_WIN64)
 # define GOSU_IS_WIN
 #else
@@ -63,9 +17,5 @@ namespace Gosu
 #endif
 
 #ifndef GOSU_DEPRECATED
-# if defined(GOSU_IS_WIN)
-#  define GOSU_DEPRECATED __declspec(deprecated)
-# else
-#  define GOSU_DEPRECATED __attribute__((__deprecated__))
-# endif
+# define GOSU_DEPRECATED [[deprecated]]
 #endif

data/include/Gosu/Text.hpp

@@ -1,6 +1,3 @@
-//! \file Text.hpp
-//! Functions to output text on bitmaps.
-
 #pragma once
 
 #include <Gosu/Fwd.hpp>
@@ -10,55 +7,55 @@
 
 namespace Gosu
 {
-    //! Returns the name of a neutral font that is available on the current platform.
+    /// Returns the name of a neutral font that is available on the current platform.
     std::string default_font_name();
 
-    //! Returns the width an unformatted line of text would span on a bitmap if it were drawn using
-    //! draw_text with the same arguments.
-    //! \param text A UCS-4 string, normalization: NFC.
-    //! \param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
+    /// Returns the width that an unformatted line of text would span on a bitmap if it were drawn
+    /// using draw_text with the same arguments.
+    /// @param text A UCS-4 string, normalization: NFC.
+    /// @param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
     double text_width(const std::u32string& text, const std::string& font_name, double font_height,
                       unsigned font_flags = 0);
 
-    //! Draws a line of unformatted text on a bitmap. This is a low-level function that does not
-    //! understand any of Gosu's HTML-like markup.
-    //! \param text A UCS-4 string, normalization: NFC.
-    //! \param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
-    //! \param font_height Height, in pixels, of the text.
-    //! \param font_flags Binary combination of members of the FontFlags enum.
+    /// Draws a line of plain text on a bitmap. This is a low-level function that does not
+    /// understand any of Gosu's HTML-like markup.
+    /// @param text A UCS-4 string, normalization: NFC.
+    /// @param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
+    /// @param font_height Height, in pixels, of the text.
+    /// @param font_flags Binary combination of members of the FontFlags enum.
     double draw_text(Bitmap& bitmap, double x, double y, Color c, const std::u32string& text,
                      const std::string& font_name, double font_height, unsigned font_flags = 0);
 
-    //! Creates a bitmap that is filled with the formatted text given to the function.
-    //! The line can contain line breaks and HTML-like markup.
-    //! \param text Formatted text.
-    //! \param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
-    //! \param font_height Height of the font in pixels.
-    //! \param line_spacing Spacing between two lines of text in pixels. Can be negative to make
-    //!        text stick together more closely.
-    //! \param 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.
-    //!        A width smaller than 0 indicates that lines should not be wrapped, and the resulting
-    //!        bitmap will be as wide as the widest line.
-    //! \param font_flags Binary combination of members of the FontFlags enum.
+    /// Creates a bitmap that is filled with the plain text given to the function.
+    /// The line can contain line breaks and HTML-like markup.
+    /// @param text Plain text.
+    /// @param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
+    /// @param font_height Height of the font in pixels.
+    /// @param line_spacing Spacing between two lines of text in pixels. Can be negative to make
+    ///        text stick together more closely.
+    /// @param 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.
+    ///        A width smaller than 0 indicates that lines should not be wrapped, and the resulting
+    ///        bitmap will be as wide as the widest line.
+    /// @param font_flags Binary combination of members of the FontFlags enum.
     Bitmap layout_text(const std::string& text, const std::string& font_name,
                        double font_height, double line_spacing = 0,
                        int width = -1, Alignment align = AL_LEFT, unsigned font_flags = 0);
     
-    //! Creates a bitmap that is filled with the formatted text given to the function.
-    //! The line can contain line breaks and HTML-like markup.
-    //! \param text Formatted text.
-    //! \param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
-    //! \param font_height Height of the font in pixels.
-    //! \param line_spacing Spacing between two lines of text in pixels. Can be negative to make
-    //!        text stick together more closely.
-    //! \param 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.
-    //!        A width smaller than 0 indicates that lines should not be wrapped, and the resulting
-    //!        bitmap will be as wide as the widest line.
-    //! \param font_flags Binary combination of members of the FontFlags enum.
+    /// Creates a bitmap that is filled with the formatted text given to the function.
+    /// The line can contain line breaks and HTML-like markup.
+    /// @param markup Formatted text.
+    /// @param font_name Name of a system font, or filename of a TTF file (must contain '/' or '.').
+    /// @param font_height Height of the font in pixels.
+    /// @param line_spacing Spacing between two lines of text in pixels. Can be negative to make
+    ///        text stick together more closely.
+    /// @param 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.
+    ///        A width smaller than 0 indicates that lines should not be wrapped, and the resulting
+    ///        bitmap will be as wide as the widest line.
+    /// @param font_flags Binary combination of members of the FontFlags enum.
     Bitmap layout_markup(const std::string& markup, const std::string& font_name,
                          double font_height, double line_spacing = 0,
                          int width = -1, Alignment align = AL_LEFT, unsigned font_flags = 0);

data/include/Gosu/Utility.hpp

@@ -1,19 +1,21 @@
 #pragma once
 
 #include <string>
+#include <vector>
 
 namespace Gosu
 {
     std::u32string utf8_to_composed_utc4(const std::string& utf8);
-    
-    //! Returns true if the filename has the given extension.
-    //! The comparison is case-insensitive, but you must pass the extension in lower case.
+
+    /// Returns true if the filename has the given extension.
+    /// The comparison is case-insensitive, but you must pass the extension in lower case.
     bool has_extension(std::string_view filename, std::string_view extension);
-    
-    //! Returns the user's preferred language, at the moment of calling the function. Expect return
-    //! values such as 'en_US', 'de_DE.UTF-8', 'ja', 'zh-Hans'.
-    //! The first two letters will always be a language code.
-    std::string language();
+
+    /// Returns the user's preferred user_languages/locales, e.g. {"en_US", "de_DE", "ja"}.
+    /// The first two letters of each element will always be a language code.
+    /// This value is not cached. Please memorize the specific value that you are interested in,
+    /// typically the first language in the returned array that your game supports.
+    std::vector<std::string> user_languages();
 
     class Noncopyable
     {

data/include/Gosu/Version.hpp

@@ -3,7 +3,7 @@
 #include <string>
 
 #define GOSU_MAJOR_VERSION 1
-#define GOSU_MINOR_VERSION 1
+#define GOSU_MINOR_VERSION 3
 #define GOSU_POINT_VERSION 0
 
 namespace Gosu