gosu 1.1.1.1 → 1.4.1

data/include/Gosu/Inspection.hpp

@@ -1,10 +1,7 @@
-//! \file Inspection.hpp
-//! A special set of functions designed for tuning Gosu games.
-
 #pragma once
 
 namespace Gosu
 {
-    //! Returns the current framerate.
+    /// Returns the current framerate.
     int fps();
 }

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 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.
+    /// 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 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.
+    /// 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 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.
+    /// 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/TextInput.hpp

@@ -1,6 +1,3 @@
-//! \file TextInput.hpp
-//! Interface of the TextInput class.
-
 #pragma once
 
 #include <Gosu/Fwd.hpp>
@@ -10,67 +7,64 @@
 
 namespace Gosu
 {
-    //! TextInput instances are invisible objects that build a text string from input,
-    //! using the current operating system's keyboard layout.
-    //! At its most basic form, you only need to create a new TextInput instance and
-    //! pass it to your window via set_text_input. Until you call this function again,
-    //! passing nullptr, the TextInput object will build a text that can be accessed via
-    //! TextInput::text().
-    //! A TextInput object is purely abstract. It is up to you to actually draw a text field.
-    //! TextInput only provides a portable base for your own GUI to build upon.
+    /// TextInput instances are invisible objects that build a text string from input, using the
+    /// current operating system's keyboard layout or input method editor (IME).
+    /// To start processing keyboard text input, you need to create a new TextInput instance and
+    /// pass it to your window's Input object via set_text_input.
+    /// Until you call this function again with a nullptr value, the TextInput object will then
+    /// build a text that can be accessed via TextInput::text().
+    /// A TextInput object has no built-in UI. It is up to you to actually draw a text field.
+    /// TextInput only provides a portable base for your own GUI to build upon.
     class TextInput
     {
         struct Impl;
         // Non-movable (const) to avoid dangling references to TextInput instances.
-        const std::unique_ptr<Impl> pimpl;
-        
+        const std::unique_ptr<Impl> m_impl;
+
     public:
         TextInput();
         virtual ~TextInput();
 
         std::string text() const;
 
-        //! Replaces the current text by the given string and positions the cursor
-        //! at the end of the text, with an empty selection.
+        /// Replaces the current text by the given string and positions the cursor at the end of the
+        /// text, with an empty selection.
         void set_text(const std::string& text);
 
-        //! Index of the character that comes after the caret. When the text is empty, this is
-        //! always 0. For ease of use in C++, this counts bytes, not codepoints in the UTF-8 encoded
-        //! string.
+        /// Index of the character that comes after the caret. When the text is empty, this is
+        /// always 0. For ease of use in C++, this counts bytes, not codepoints, in the UTF-8
+        /// encoded string.
         unsigned caret_pos() const;
-        //! Sets the caret position as returned by caret_pos.
-        //! You usually also want to use set_selection_start.
+        /// Sets the caret position as returned by caret_pos.
+        /// You usually also want to use set_selection_start.
         void set_caret_pos(unsigned pos);
 
-        //! If there is a selection, the selection_start() member yields its beginning,
-        //! using the same indexing scheme as caret_pos. If there is no selection,
-        //! selection_start() is equal to caret_pos().
+        /// If there is a selection, the selection_start() member yields its beginning, using the
+        /// same indexing scheme as caret_pos. If there is no selection, selection_start() is equal
+        /// to caret_pos().
         unsigned selection_start() const;
-        //! Sets the start of the selection as returned by selection_start.
+        /// Sets the start of the selection as returned by selection_start.
         void set_selection_start(unsigned pos);
-        
+
 #ifndef GOSU_IS_IPHONE
         // Platform-specific communication with Gosu::Input.
         bool feed_sdl_event(void* event);
 #endif
 
-        //! Overridable filter that is applied to all new text that is entered.
-        //! Allows for context-sensitive filtering/extending/... of new characters.
-        //! The return value will be inserted at caret_pos.
-        virtual std::string filter(std::string text) const
-        {
-            return text;
-        }
-        
-        //! Replaces the current selection (if any) and inserts the given string at the current
-        //! caret position.
-        //! The filter method will not be applied before appending the string.
+        /// Overridable filter that is applied to all new text that is entered.
+        /// Allows for context-sensitive filtering/extending/... of new characters.
+        /// The return value will be inserted at caret_pos.
+        virtual std::string filter(std::string text) const { return text; }
+
+        /// Replaces the current selection (if any) and inserts the given string at the current
+        /// caret position.
+        /// The filter method will not be applied before appending the string.
         void insert_text(std::string text);
-        
-        //! Deletes the current selection, if any, or the next character.
+
+        /// Deletes the current selection, if any, or the next character.
         void delete_forward();
-        
-        //! Deletes the current selection, if any, or the previous character.
+
+        /// Deletes the current selection, if any, or the previous character.
         void delete_backward();
     };
 }

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 4
 #define GOSU_POINT_VERSION 1
 
 namespace Gosu

data/include/Gosu/Window.hpp

@@ -12,26 +12,26 @@ namespace Gosu
     {
         WF_WINDOWED,
         WF_FULLSCREEN = 1,
-        WF_RESIZABLE  = 2,
+        WF_RESIZABLE = 2,
         WF_BORDERLESS = 4
     };
 
-    //! Convenient all-in-one 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 you should really only use one instance of this class at the same time.
+    /// Convenient all-in-one 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 you can only use one instance of this class at the same time.
     class Window
     {
         struct Impl;
-        const std::unique_ptr<Impl> pimpl;
+        const std::unique_ptr<Impl> m_impl;
 
     public:
-        //! Constructs a Window.
-        //! \param width Width of the window in points; that is, pixels on a normal display, and
-        //! 'points' on a high-resolution display.
-        //! \param height See width.
-        //! \param window_flags A bitmask of values from Gosu::WindowFlags.
-        //! \param update_interval Interval in milliseconds between two calls to the update member
-        //! function.
+        /// Constructs a Window.
+        /// @param width Width of the window in points; that is, pixels on a normal display, and
+        /// 'points' on a high-resolution display.
+        /// @param height Same as width, just for the other dimension.
+        /// @param window_flags A bitmask of values from Gosu::WindowFlags.
+        /// @param update_interval Interval in milliseconds between two calls to the update member
+        /// function.
         Window(int width, int height, unsigned window_flags = WF_WINDOWED,
                double update_interval = 16.666666);
         virtual ~Window();
@@ -53,75 +53,78 @@ namespace Gosu
         std::string caption() const;
         void set_caption(const std::string& caption);
 
-        //! Enters a modal loop where the Window is visible on screen and
-        //! receives calls to draw, update etc.
+        /// Enters a modal loop where the Window is visible on screen and receives calls to draw,
+        /// update etc.
+        /// The loop exits when the window is closed.
         virtual void show();
 
-        //! EXPERIMENTAL - MAY DISAPPEAR WITHOUT WARNING.
-        //! Performs a single main loop step.
-        //! This method is only useful if you want to integrate Gosu with another library that has
-        //! its own main loop.
-        //! This method implicitly shows the window if it was hidden before, and returns false when
-        //! the window has been closed.
-        //! If you discard the return value and keep calling tick(), the window will be shown again,
-        //! or keep being shown.
+        /// EXPERIMENTAL - MAY DISAPPEAR WITHOUT WARNING.
+        /// Performs a single main loop step.
+        /// This method is only useful if you want to integrate Gosu with another library that has
+        /// its own main loop.
+        /// This method implicitly shows the window if it was hidden before, and returns false when
+        /// the window has been closed.
+        /// If you discard the return value and keep calling tick(), the window will be shown again,
+        /// or keep being shown.
         virtual bool tick();
 
-        //! Closes the window if it is currently shown.
-        //! If you do not want the window to close immediately, you should override this method and
-        //! only call the base implementation (Window::close) when needed.
+        /// Closes the window if it is currently shown.
+        /// If you do not want the window to close immediately, you should override this method and
+        /// only call the base implementation (Window::close) when needed.
         virtual void close();
 
-        //! Called every update_interval milliseconds while the window is being shown.
-        //! Your application's main game logic goes here.
+        /// Called every update_interval milliseconds while the window is being shown.
+        /// Your application's main game logic goes here.
         virtual void update() {}
 
-        //! Called after every update and when the OS wants the window to repaint itself.
-        //! Your application's rendering code goes here.
+        /// Called after every update and when the OS wants the window to repaint itself.
+        /// Your application's rendering code goes here.
         virtual void draw() {}
 
-        //! Gives the game a chance to say no to being redrawn.
-        //! This is not a definitive answer. The operating system can still force the window to
-        //! redraw itself.
-        //! By default, the window is redrawn all the time.
+        /// Gives the game a chance to say no to being redrawn.
+        /// This is not a definitive answer. The operating system can still force the window to
+        /// redraw itself.
+        /// By default, the window is redrawn all the time.
         virtual bool needs_redraw() const { return true; }
 
-        //! If this function returns true, the system cursor will be visible while over the window.
+        /// If this function returns true, the system cursor will be visible while over the window.
         virtual bool needs_cursor() const { return true; }
 
-        //! This function is called when the window loses focus on some platforms.
-        //! Most importantly, it is called on the iPhone or iPad when the user locks the screen.
+        virtual void gain_focus() {}
+
+        /// This function is called when the window loses focus on some platforms.
+        /// Most importantly, it is called on the iPhone or iPad when the user locks the screen.
         virtual void lose_focus() {}
 
-        //! This function is called when the operating system's memory is low.
-        //! So far, it is only called in iOS applications.
+        /// This function is called when the operating system's memory is low.
+        /// So far, it is only called in iOS applications.
         virtual void release_memory() {}
 
-        //! Called before update when the user presses a button while the window has the focus.
-        //! By default, this will toggle fullscreen mode if the user presses Alt+Enter (Windows,
-        //! Linux), cmd+F (macOS), or F11 (on all operating systems).
-        //! To support these shortcuts in your application, make sure to call Window::button_down
-        //! in your implementation.
+        /// Called before update when the user presses a button while the window has the focus.
+        /// By default, this will toggle fullscreen mode if the user presses Alt+Enter (Windows,
+        /// Linux), cmd+F (macOS), or F11 (on all operating systems).
+        /// To support these shortcuts in your application, make sure to call Window::button_down
+        /// in your implementation.
         virtual void button_down(Gosu::Button);
 
-        //! Same as button_down. Called when the user releases a button.
+        /// Same as button_down. Called when the user releases a button.
         virtual void button_up(Gosu::Button) {}
 
-        //! Called when a gamepad is connected.
-        //! \param index the index of the gamepad slot that the gamepad is in.
+        /// Called when a gamepad is connected.
+        /// @param index the index of the gamepad slot that the gamepad is in.
         virtual void gamepad_connected(int index) {}
 
-        //! Called when a gamepad is disconnected.
-        //! \param index the index of the gamepad slot that the gamepad is in. The slot will be freed immediately after this callback.
+        /// Called when a gamepad is disconnected.
+        /// @param index the index of the gamepad slot that the gamepad is in. The slot will be freed immediately after this callback.
         virtual void gamepad_disconnected(int index) {}
 
-        //! Called when a file is dropped onto the window.
-        //! \param filename The filename of the dropped file. When multiple files are dropped, this
-        //! method will be called several times.
+        /// Called when a file is dropped onto the window.
+        /// @param filename The filename of the dropped file. When multiple files are dropped, this
+        /// method will be called several times.
         virtual void drop(const std::string& filename) {}
 
-        // Ignore when SWIG is wrapping this class for Ruby/Gosu.
-        #ifndef SWIG
+// Ignore when SWIG is wrapping this class for Ruby/Gosu.
+#ifndef SWIG
         // Callbacks for touch events. So far these are only used on iOS.
         virtual void touch_began(Touch touch) {}
         virtual void touch_moved(Touch touch) {}
@@ -133,32 +136,32 @@ namespace Gosu
 
         const Input& input() const;
         Input& input();
-        #endif
+#endif
 
-        #ifdef GOSU_IS_IPHONE
+#ifdef GOSU_IS_IPHONE
         void* uikit_window() const;
-        #endif
+#endif
     };
 
-    //! Returns the width (in pixels) of a screen.
-    //! \param window The result describes the screen on which the window is shown, or the
-    //!               primary screen if no window is given.
+    /// Returns the width (in pixels) of a screen.
+    /// @param window The result describes the screen on which the window is shown, or the
+    ///               primary screen if no window is given.
     int screen_width(Window* window = nullptr);
 
-    //! Returns the height (in pixels) of the user's primary screen.
-    //! \param window The result describes the screen on which the window is shown, or the
-    //!               primary screen if no window is given.
+    /// Returns the height (in pixels) of the user's primary screen.
+    /// @param window The result describes the screen on which the window is shown, or the
+    ///               primary screen if no window is given.
     int screen_height(Window* window = nullptr);
 
-    //! Returns the maximum width (in 'points') that is available for a non-fullscreen Window.
-    //! All windows larger than this size will automatically be shrunk to fit.
-    //! \param window The result describes the screen on which the window is shown, or the
-    //!               primary screen if no window is given.
+    /// Returns the maximum width (in 'points') that is available for a non-fullscreen Window.
+    /// All windows larger than this size will automatically be shrunk to fit.
+    /// @param window The result describes the screen on which the window is shown, or the
+    ///               primary screen if no window is given.
     int available_width(Window* window = nullptr);
 
-    //! Returns the maximum height (in 'points') that is available for a non-fullscreen Window.
-    //! All windows larger than this size will automatically be shrunk to fit.
-    //! \param window The result describes the screen on which the window is shown, or the
-    //!               primary screen if no window is given.
+    /// Returns the maximum height (in 'points') that is available for a non-fullscreen Window.
+    /// All windows larger than this size will automatically be shrunk to fit.
+    /// @param window The result describes the screen on which the window is shown, or the
+    ///               primary screen if no window is given.
     int available_height(Window* window = nullptr);
 }