gosu 1.4.6 → 2.0.0.pre6

data/include/Gosu/Color.hpp

@@ -1,47 +1,39 @@
 #pragma once
 
-#include <Gosu/Platform.hpp>
+#include <compare>
 #include <cstdint>
+#include <ostream>
 
 namespace Gosu
 {
-    /// Represents an RGBA color value with 8 bit for each channel.
-    /// Can be implicitly constructed from literals of the form 0xaarrggbb.
+    /// Color represents an RGBA 32-bit color value, using 8 bit for each channel.
+    /// Colors can be implicitly constructed from literals of the form 0xaarrggbb.
     struct Color
     {
-        static const unsigned GL_FORMAT = 0x1908; // GL_RGBA
+        using Channel = std::uint8_t;
+        Channel red = 0, green = 0, blue = 0, alpha = 0;
 
-        typedef std::uint8_t Channel;
+        Color() = default;
 
-        Channel red, green, blue, alpha;
-
-        constexpr Color()
-        : red{0},
-          green{0},
-          blue{0},
-          alpha{0}
-        {
-        }
-
-        /// Conversion constructor for literals of the form 0xaarrggbb.
+        /// Implicit 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)}
+        Color(std::uint32_t argb)
+            : red(argb >> 16),
+              green(argb >> 8),
+              blue(argb >> 0),
+              alpha(argb >> 24)
         {
         }
 
-        constexpr Color(Channel red, Channel green, Channel blue)
-        : red{red},
-          green{green},
-          blue{blue},
-          alpha{255}
+        Color(Channel red, Channel green, Channel blue)
+            : red(red),
+              green(green),
+              blue(blue),
+              alpha(255)
         {
         }
 
-        Color with_alpha(Channel new_alpha)
+        Color with_alpha(Channel new_alpha) const
         {
             Color result = *this;
             result.alpha = new_alpha;
@@ -49,13 +41,14 @@ namespace Gosu
         }
 
         /// 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.
+        /// s and v will be clamped into the range 0...1, and h will be normalized to 0...360.
         static Color from_hsv(double h, double s, double v);
 
         /// 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.
+        /// Note: This is a no-op when called on a grey tone (saturation() == 0).
         void set_hue(double h);
 
         /// Returns the saturation of the color, in the range of 0..1.
@@ -73,7 +66,8 @@ namespace Gosu
         /// 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.
+        /// Returns the color in 0xbbggrr representation. Useful for Win32 programming, as this
+        /// corresponds to the COLORREF type that can be created using the RGB() macro.
         std::uint32_t bgr() const { return blue << 16 | green << 8 | red; }
 
         /// Returns the color in 0xaabbggrr representation.
@@ -96,16 +90,13 @@ namespace Gosu
         static const Color FUCHSIA;
         /// Same as Color::AQUA.
         static const Color CYAN;
+
+        std::strong_ordering operator<=>(const Color&) const = default;
     };
 
     // 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.
     Color lerp(Color a, Color b, double t = 0.5);
@@ -113,5 +104,6 @@ namespace Gosu
     /// 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
+
+    std::ostream& operator<<(std::ostream& stream, Color color);
 }

data/include/Gosu/Directories.hpp

@@ -6,38 +6,35 @@ namespace Gosu
 {
     /// Changes the current directory to the result of resource_prefix().
     void use_resource_directory();
-    
-    /// Prefix for a program's own resources.
-    /// <ul>
-    /// <li> Windows: The parent directory of the executable.
-    /// <li> macOS, iOS: The 'Resources' directory inside the .app bundle.
-    /// <li> Linux: The current directory (empty string).
-    /// </ul>
-    const std::string& resource_prefix();
-    
-    /// Prefix for shared resources of a group of programs, e.g. the game and its level editor.
+
+    /// Builds a filename for reading (not writing) game resources.
+    /// An image file can be loaded as e.g. Gosu::Image(Gosu::resource_path("gfx/image.png")).
+    ///
+    /// This function will use the following directory:
     /// <ul>
     /// <li> Windows: The parent directory of the executable.
-    /// <li> macOS: The parent directory of the .app bundle.
+    /// <li> macOS, iOS: The 'Resources' directory inside the .app bundle, or the current directory
+    ///      if this code is not being run from an .app bundle.
     /// <li> Linux: The current directory (empty string).
-    /// </uil>
-    const std::string& shared_resource_prefix();
-    
-    /// Prefix for user settings.
-    /// <ul>
-    /// <li> Windows: The same as %APPDATA%.
-    /// <li> macOS: The user's Library/Preferences folder.
-    /// <li> Linux: The home directory plus a trailing dot for hidden files.
     /// </ul>
-    const std::string& user_settings_prefix();
-    
-    /// Prefix for user documents, e.g. saved games.
+    ///
+    /// Note: This uses SDL_GetBasePath internally. https://wiki.libsdl.org/SDL2/SDL_GetBasePath
+    std::string resource_path(const std::string& relative_filename = "");
+
+    /// Builds a filename for reading or writing game settings. This method will automatically
+    /// create all intermediate directories needed to save files at the returned path.
+    ///
+    /// Preferences might be saved using e.g.:
+    /// Gosu::save_file(buffer, Gosu::user_settings_path("MyStudio", "MyGame", "settings.ini")).
+    ///
+    /// This function will use the following directory:
     /// <ul>
-    /// <li> Windows: The "My Documents" folder.
-    /// <li> macOS: The user's "Documents" folder.
-    /// <li> Linux: The home directory.
+    /// <li> Windows: The "organization/application" folder in %APPDATA%.
+    /// <li> macOS: "~/Library/Application Support/organization/application".
+    /// <li> Linux: "~.local/share/application".
     /// </ul>
-    const std::string& user_documents_prefix();
-
-    // TODO: Instead of re-inventing wheels here, we should wrap SDL_GetBasePath / SDL_GetPrefPath.
+    ///
+    /// Note: This uses SDL_GetPrefPath internally. https://wiki.libsdl.org/SDL2/SDL_GetPrefPath
+    std::string user_settings_path(const std::string& organization, const std::string& application,
+                                   const std::string& relative_filename = "");
 }

data/include/Gosu/Drawable.hpp

@@ -0,0 +1,58 @@
+#pragma once
+
+#include <Gosu/Fwd.hpp>
+#include <Gosu/Color.hpp>
+#include <Gosu/GraphicsBase.hpp>
+#include <Gosu/Utility.hpp>
+#include <cstdint>
+#include <memory>
+
+namespace Gosu
+{
+    /// Returns the maximum size of an texture that will be allocated internally by Gosu.
+    /// Useful when extending Gosu using OpenGL.
+    const unsigned MAX_TEXTURE_SIZE = 1024;
+
+    /// Contains information about the underlying OpenGL texture and the u/v space used for image
+    /// data. Can be retrieved from some drawables to use them in OpenGL operations.
+    struct GLTexInfo
+    {
+        /// This uses std::uint32_t instead of GLuint to avoid publicly including OpenGL headers.
+        /// Both types must be the same because GLuint is guaranteed to be an unsigned 32-bit type.
+        std::uint32_t tex_name;
+        double left, right, top, bottom;
+    };
+
+    /// Abstract base class for a rectangular thing that can be drawn.
+    /// Instances are usually created through Graphics::create_drawable and used to implement
+    /// drawing primitives like Image, which then provide a more convenient drawing interface.
+    class Drawable : private Noncopyable
+    {
+    public:
+        Drawable() = default;
+        virtual ~Drawable() = default;
+
+        virtual int width() const = 0;
+
+        virtual int height() const = 0;
+
+        virtual void draw(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, BlendMode mode) const
+            = 0;
+
+        virtual const GLTexInfo* gl_tex_info() const = 0;
+
+        virtual Bitmap to_bitmap() const = 0;
+
+        virtual std::unique_ptr<Drawable> subimage(const Rect& rect) const = 0;
+
+        virtual void insert(const Bitmap& bitmap, int x, int y) = 0;
+    };
+
+    /// Turns a portion of a bitmap into something that can be drawn, typically a TexChunk instance.
+    std::unique_ptr<Drawable> create_drawable(const Bitmap& source, const Rect& source_rect,
+                                              unsigned image_flags);
+}

data/include/Gosu/Font.hpp

@@ -7,6 +7,7 @@
 #include <Gosu/Text.hpp>
 #include <memory>
 #include <string>
+#include <string_view>
 
 namespace Gosu
 {
@@ -22,11 +23,11 @@ namespace Gosu
         /// @param height Height of the font, in pixels.
         /// @param font_flags  Flags used to render individual characters of the font (FontFlags enum).
         /// @param image_flags  Flags used to render individual characters of the font (ImageFlags enum).
-        explicit Font(int height, const std::string& name = default_font_name(),
+        explicit Font(int height, std::string_view name = default_font_name(),
                       unsigned font_flags = 0, unsigned image_flags = 0);
 
-        /// Returns the name of the font that was used to create it, i.e. the filename, nor the
-        /// internal TTF name. (TODO: Why not?)
+        /// Returns the name of the font that was used to create it. If the font was loaded from a
+        /// filename, the same filename string will be returned here unmodified.
         const std::string& name() const;
 
         /// Returns the height of the font, in pixels.
@@ -69,8 +70,8 @@ namespace Gosu
 
         /// Maps a letter to a specific image, instead of generating one using Gosu's built-in text
         /// rendering.
-        void set_image(std::string codepoint, unsigned font_flags, const Gosu::Image& image);
+        void set_image(std::string_view codepoint, unsigned font_flags, const Gosu::Image& image);
         /// A shortcut for mapping a character to an image regardless of font_flags.
-        void set_image(std::string codepoint, const Gosu::Image& image);
+        void set_image(std::string_view codepoint, const Gosu::Image& image);
     };
 }

data/include/Gosu/Fwd.hpp

@@ -6,17 +6,15 @@ namespace Gosu
     class Buffer;
     class Channel;
     struct Color;
-    class File;
     class Font;
-    class Graphics;
     class Image;
-    class ImageData;
+    class Drawable;
     class Input;
-    class Reader;
-    class Resource;
+    struct Rect;
     class Sample;
     class Song;
     class TextInput;
+    struct Transform;
+    class Viewport;
     class Window;
-    class Writer;
 }

data/include/Gosu/Gosu.hpp

@@ -1,6 +1,6 @@
-/// \mainpage Gosu C++ Documentation
+/// \mainpage Gosu: C++ Interface Reference
 ///
-/// These pages serve as a reference on the C++ interface of Gosu. For a higher-level
+/// These pages serve as a reference for the C++ interface of Gosu. For a higher-level
 /// discussion of concepts and ideas behind the library, see the Wiki entries linked
 /// from the official website, https://www.libgosu.org/.
 
@@ -8,20 +8,20 @@
 
 #include <Gosu/Audio.hpp>
 #include <Gosu/Bitmap.hpp>
+#include <Gosu/Buffer.hpp>
 #include <Gosu/Color.hpp>
 #include <Gosu/Directories.hpp>
+#include <Gosu/Drawable.hpp>
 #include <Gosu/Font.hpp>
 #include <Gosu/Graphics.hpp>
 #include <Gosu/Image.hpp>
-#include <Gosu/ImageData.hpp>
 #include <Gosu/Input.hpp>
-#include <Gosu/Inspection.hpp>
-#include <Gosu/IO.hpp>
 #include <Gosu/Math.hpp>
 #include <Gosu/Platform.hpp>
 #include <Gosu/Text.hpp>
 #include <Gosu/TextInput.hpp>
 #include <Gosu/Timing.hpp>
+#include <Gosu/Transform.hpp>
 #include <Gosu/Utility.hpp>
 #include <Gosu/Version.hpp>
 #include <Gosu/Window.hpp>

data/include/Gosu/Graphics.hpp

@@ -3,96 +3,86 @@
 #include <Gosu/Fwd.hpp>
 #include <Gosu/Color.hpp>
 #include <Gosu/GraphicsBase.hpp>
+#include <Gosu/Utility.hpp>
 #include <functional>
 #include <memory>
 
 namespace Gosu
 {
-    struct DrawOp;
-
-    /// Returns the maximum size of an texture that will be allocated internally by Gosu.
-    /// Useful when extending Gosu using OpenGL.
-    const unsigned MAX_TEXTURE_SIZE = 1024;
-
-    /// Serves as the target of all drawing and provides primitive drawing functionality.
-    /// Usually created internally by Gosu::Window.
-    class Graphics
+    /// Serves as the target of all drawing. Usually created internally by Gosu::Window.
+    class Viewport : private Noncopyable
     {
         struct Impl;
         std::unique_ptr<Impl> m_impl;
 
     public:
-        Graphics(unsigned physical_width, unsigned physical_height);
-        ~Graphics();
+        Viewport(int physical_width, int physical_height);
+        ~Viewport();
 
-        void set_resolution(unsigned logical_width, unsigned logical_height,
+        void set_resolution(int logical_width, int logical_height, //
                             double black_bar_width = 0, double black_bar_height = 0);
 
-        unsigned width() const;
-        unsigned height() const;
+        int width() const;
+        int height() const;
 
         /// Prepares the graphics object for drawing and then runs the rendering code in f.
         /// Nothing must be drawn outside of frame() and record().
         void frame(const std::function<void()>& f);
 
-        /// Flushes the Z queue to the screen and starts a new one.
-        /// This can be useful to separate the Z queues of two parts of the game, e.g. the two
-        /// halves of a game that runs in split-screen mode.
-        static void flush();
+        /// For internal use only.
+        void set_physical_resolution(int physical_width, int physical_height);
 
-        /// Finishes all pending Gosu drawing operations and executes the code in f in a clean
-        /// OpenGL environment.
-        static void gl(const std::function<void()>& f);
+        friend void gl(const std::function<void()>&);
+        friend void gl(ZPos, const std::function<void()>&);
+        friend void clip_to(double, double, double, double, const std::function<void()>&);
+    };
 
-        /// Schedules a custom GL functor to be executed at a certain Z level.
-        /// The functor f is run in a clean GL context.
-        /// Note: You may not call any Gosu rendering functions from within the functor.
-        static void gl(ZPos z, const std::function<void()>& f);
+    /// Flushes the Z queue to the screen and starts a new one.
+    /// This can be useful to separate the Z queues of two parts of the game, e.g. the two
+    /// halves of a game that runs in split-screen mode.
+    void flush();
 
-        /// Renders everything drawn in f clipped to a rectangle on the screen.
-        static void clip_to(double x, double y, double width, double height,
-                            const std::function<void()>& f);
+    /// Finishes all pending Gosu drawing operations and executes the code in f in a clean
+    /// OpenGL environment.
+    void gl(const std::function<void()>& f);
 
-        /// Renders everything drawn in f onto a new Image of size (width, height).
-        /// @param image_flags Pass Gosu::IF_RETRO if you do not want the resulting image to use
-        /// interpolation when it is scaled or rotated.
-        static Gosu::Image render(int width, int height, const std::function<void()>& f,
-                                  unsigned image_flags = 0);
+    /// Schedules a custom GL functor to be executed at a certain Z level.
+    /// The functor f is run in a clean GL context.
+    /// Note: You may not call any Gosu rendering functions from within the functor.
+    void gl(ZPos z, const std::function<void()>& f);
 
-        /// Records a macro and returns it as an Image.
-        static Gosu::Image record(int width, int height, const std::function<void()>& f);
+    /// Renders everything drawn in f clipped to a rectangle on the screen.
+    void clip_to(double x, double y, double width, double height, const std::function<void()>& f);
 
-        /// Pushes one transformation onto the transformation stack.
-        static void transform(const Transform& transform, const std::function<void()>& f);
+    /// Renders everything drawn in f onto a new Image of size (width, height).
+    /// @param image_flags Pass Gosu::IF_RETRO if you do not want the resulting image to use
+    /// interpolation when it is scaled or rotated.
+    Gosu::Image render(int width, int height, const std::function<void()>& f,
+                       unsigned image_flags = 0);
 
-        /// Draws a line from one point to another (last pixel exclusive).
-        /// Note: OpenGL lines are not reliable at all and may have a missing pixel at the start
-        /// or end point. Please only use this for debugging purposes. Otherwise, use a quad or
-        /// image to simulate lines, or contribute a better draw_line to Gosu.
-        static void draw_line(double x1, double y1, Color c1, double x2, double y2, Color c2,
-                              ZPos z, BlendMode mode = BM_DEFAULT);
+    /// Records a macro and returns it as an Image.
+    Gosu::Image record(int width, int height, const std::function<void()>& f);
 
-        static void draw_triangle(double x1, double y1, Color c1, //
-                                  double x2, double y2, Color c2, //
-                                  double x3, double y3, Color c3, //
-                                  ZPos z, BlendMode mode = BM_DEFAULT);
+    /// Pushes one transformation onto the transformation stack.
+    void transform(const Transform& transform, const std::function<void()>& f);
 
-        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, BlendMode mode = BM_DEFAULT);
+    /// Draws a line from one point to another (last pixel exclusive).
+    /// Note: OpenGL lines are not reliable at all and may have a missing pixel at the start
+    /// or end point. Please only use this for debugging purposes. Otherwise, use a quad or
+    /// image to simulate lines, or contribute a better draw_line to Gosu.
+    void draw_line(double x1, double y1, Color c1, double x2, double y2, Color c2, ZPos z,
+                   BlendMode mode = BM_DEFAULT);
 
-        static void draw_rect(double x, double y, double width, double height, Color c, ZPos z,
-                              BlendMode mode = BM_DEFAULT);
+    void draw_triangle(double x1, double y1, Color c1, //
+                       double x2, double y2, Color c2, //
+                       double x3, double y3, Color c3, //
+                       ZPos z, BlendMode mode = BM_DEFAULT);
 
-        /// For internal use only.
-        void set_physical_resolution(unsigned physical_width, unsigned physical_height);
+    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,
+                   BlendMode mode = BM_DEFAULT);
 
-        /// For internal use only.
-        static void schedule_draw_op(const DrawOp& op);
+    void draw_rect(double x, double y, double width, double height, Color c, ZPos z,
+                   BlendMode mode = BM_DEFAULT);
 
-        /// Turns a portion of a bitmap into something that can be drawn on a Graphics object.
-        static std::unique_ptr<ImageData> create_image(const Bitmap& src, unsigned src_x,
-                                                       unsigned src_y, unsigned src_width,
-                                                       unsigned src_height, unsigned image_flags);
-    };
 }

data/include/Gosu/GraphicsBase.hpp

@@ -1,12 +1,9 @@
 #pragma once
 
-#include <Gosu/Platform.hpp>
-#include <array>
-
 namespace Gosu
 {
     /// Represents the Z position of something drawn with Gosu's graphics system.
-    /// Draw calls with higher ZPos values will cover those with a lower ZPos value.
+    /// Images drawn with higher ZPos values will cover those with a lower ZPos value.
     typedef double ZPos;
 
     /// Determines the way pixel colors are combined when images overlap.
@@ -56,11 +53,4 @@ namespace Gosu
         /// Apply nearest-neighbor interpolation when scaling this image up or down.
         IF_RETRO = 1 << 5
     };
-
-    typedef std::array<double, 16> Transform;
-    Transform translate(double x, double y);
-    Transform rotate(double angle, double around_x = 0, double around_y = 0);
-    Transform scale(double factor);
-    Transform scale(double scale_x, double scale_y, double from_x = 0, double from_y = 0);
-    Transform concat(const Transform& lhs, const Transform& rhs);
 }

data/include/Gosu/Image.hpp

@@ -12,7 +12,7 @@ namespace Gosu
     /// Provides functionality for drawing rectangular images.
     class Image
     {
-        std::shared_ptr<ImageData> m_data;
+        std::shared_ptr<Drawable> m_drawable;
 
     public:
         /// Creates an empty image. It will have a width and height of 0, and not contain anything.
@@ -28,18 +28,17 @@ namespace Gosu
         ///
         /// A color key of #ff00ff is automatically applied to BMP image files.
         /// For more flexibility, use the corresponding constructor that uses a Bitmap object.
-        Image(const std::string& filename, int src_x, int src_y, int src_width, int src_height,
+        Image(const std::string& filename, const Rect& source_rect,
               unsigned image_flags = IF_SMOOTH);
 
         /// Converts the given bitmap into an image.
         explicit Image(const Bitmap& source, unsigned image_flags = IF_SMOOTH);
 
         /// Converts a portion of the given bitmap into an image.
-        Image(const Bitmap& source, int src_x, int src_y, int src_width, int src_height,
-              unsigned image_flags = IF_SMOOTH);
+        Image(const Bitmap& source, const Rect& source_rect, unsigned image_flags = IF_SMOOTH);
 
-        /// Creates an Image from a user-supplied instance of the ImageData interface.
-        explicit Image(std::unique_ptr<ImageData>&& data);
+        /// Creates an Image from a user-supplied instance of the Drawable interface.
+        explicit Image(std::unique_ptr<Drawable> data);
 
         unsigned width() const;
         unsigned height() const;
@@ -61,25 +60,23 @@ namespace Gosu
                       double center_y = 0.5, double scale_x = 1, double scale_y = 1,
                       Color c = Color::WHITE, BlendMode mode = BM_DEFAULT) const;
 
-#ifndef SWIG
         /// Provides access to the underlying image data object.
-        ImageData& data() const;
-#endif
+        Drawable& drawable() const;
     };
 
-#ifndef SWIG
     /// Convenience function that slices an image file into a grid and creates images from them.
     /// @param tile_width If positive, specifies the width of one tile in pixels.
     /// If negative, the bitmap is divided into -tile_width rows.
     /// @param tile_height See tile_width.
-    std::vector<Gosu::Image> load_tiles(const Bitmap& bmp, int tile_width, int tile_height,
+    std::vector<Gosu::Image> load_tiles(const Bitmap& bitmap, //
+                                        int tile_width, int tile_height,
                                         unsigned image_flags = IF_SMOOTH);
 
     /// Convenience function that slices a bitmap into a grid and creates images from them.
     /// @param tile_width If positive, specifies the width of one tile in pixels.
     /// If negative, the bitmap is divided into -tile_width rows.
     /// @param tile_height See tile_width.
-    std::vector<Gosu::Image> load_tiles(const std::string& filename, int tile_width,
-                                        int tile_height, unsigned image_flags = IF_SMOOTH);
-#endif
+    std::vector<Gosu::Image> load_tiles(const std::string& filename, //
+                                        int tile_width, int tile_height,
+                                        unsigned image_flags = IF_SMOOTH);
 }