gosu 0.7.13 → 0.7.13.2

data/Gosu/Image.hpp

@@ -23,7 +23,7 @@ namespace Gosu
 		//! automatically applied to BMP type images. For more flexibility, use the
 		//! corresponding constructor that uses a Bitmap object.
         Image(Graphics& graphics, const std::wstring& filename,
-              bool hardBorders = false);
+              bool tileable = false);
         //! Loads a portion of the the image at the given filename that can be
         //! drawn onto graphics.
 		//! This constructor can handle PNG and BMP images. A color key of #ff00ff is
@@ -31,17 +31,17 @@ namespace Gosu
 		//! corresponding constructor that uses a Bitmap object.
         Image(Graphics& graphics, const std::wstring& filename, unsigned srcX,
               unsigned srcY, unsigned srcWidth, unsigned srcHeight,
-              bool hardBorders = false);
+              bool tileable = false);
         
         //! Converts the given bitmap into an image that can be drawn onto
         //! graphics.
         Image(Graphics& graphics, const Bitmap& source,
-            bool hardBorders = false);
+            bool tileable = false);
         //! Converts a portion of the given bitmap into an image that can be
         //! drawn onto graphics.
         Image(Graphics& graphics, const Bitmap& source, unsigned srcX,
             unsigned srcY, unsigned srcWidth, unsigned srcHeight,
-            bool hardBorders = false);
+            bool tileable = false);
 
         ~Image();
 
@@ -92,32 +92,32 @@ namespace Gosu
         #endif
     };
 
-	//! Convenience function that splits a BMP or PNG file into an area
+	//! Convenience function that splits a BMP or PNG file into an array
 	//! of small rectangles and creates images from them.
     //! \param tileWidth If positive, specifies the width of one tile in
     //! pixels. If negative, the bitmap is divided into -tileWidth rows.
     //! \param tileHeight See tileWidth.
     //! \param appendTo STL container to which the images will be appended.
     //! Must provide a push_back member function; std::vector<boost::shared_ptr<Image>>
-    //! is usually the most reasonable container.
+    //! or boost::ptr_vector<Image> are good choices.
     template<typename Container>
     void imagesFromTiledBitmap(Graphics& graphics, const std::wstring& filename,
-        int tileWidth, int tileHeight, bool hardBorders, Container& appendTo)
+        int tileWidth, int tileHeight, bool tileable, Container& appendTo)
     {
-		imagesFromTiledBitmap(graphics, quickLoadBitmap(filename), tileWidth, tileHeight, hardBorders, appendTo);
+		imagesFromTiledBitmap(graphics, quickLoadBitmap(filename), tileWidth, tileHeight, tileable, appendTo);
     }
 
-    //! Convenience function that splits a bitmap into an area of small 
+    //! Convenience function that splits a bitmap into an area of array 
     //! rectangles and creates images from them.
     //! \param tileWidth If positive, specifies the width of one tile in
     //! pixels. If negative, the bitmap is divided into -tileWidth rows.
     //! \param tileHeight See tileWidth.
     //! \param appendTo STL container to which the images will be appended.
     //! Must provide a push_back member function; std::vector<boost::shared_ptr<Image>>
-    //! is usually the most reasonable container.
+    //! or boost::ptr_vector<Image> are good choices.
     template<typename Container>
     void imagesFromTiledBitmap(Graphics& graphics, const Bitmap& bmp,
-        int tileWidth, int tileHeight, bool hardBorders, Container& appendTo)
+        int tileWidth, int tileHeight, bool tileable, Container& appendTo)
     {
         int tilesX, tilesY;
 
@@ -141,7 +141,7 @@ namespace Gosu
             for (int x = 0; x < tilesX; ++x)
                 appendTo.push_back(typename Container::value_type(new Image(graphics, bmp,
                     x * tileWidth, y * tileHeight, tileWidth, tileHeight,
-                    hardBorders)));
+                    tileable)));
     }
 }
 

data/Gosu/ImageData.hpp

@@ -11,6 +11,9 @@
 
 namespace Gosu
 {
+    //! Contains information about the underlying OpenGL texture and the
+    //! u/v space used for image data. Can be retrieved from some images
+    //! to use them in OpenGL operations.
     struct GLTexInfo
     {
         int texName;

data/Gosu/Input.hpp

@@ -50,8 +50,17 @@ namespace Gosu
 	};
 	
 	// Available even on non-iPhone platforms to make it easier to compile the
-	// same source for multiple platforms. To be moved to Input.hpp, though.
-    struct Touch { void* id; double x, y; };
+	// same source for multiple platforms.
+    
+    //! Struct that saves information about a touch on the surface of a multi-
+    //! touch device.
+    struct Touch
+    {
+        //! Allows for identification of a touch across calls.
+        void* id;
+        //! Position of a touch on the touch screen.
+        double x, y;
+    };
     typedef std::vector<Touch> Touches;
 
 	//! Tests whether two Buttons identify the same physical button.
@@ -99,6 +108,7 @@ namespace Gosu
         static Button charToId(wchar_t ch);
         
 		//! Returns true if a button is currently pressed.
+        //! Updated every tick.
 		bool down(Button btn) const;
         
         //! Returns the horizontal position of the mouse relative to the top
@@ -123,7 +133,9 @@ namespace Gosu
 		//! If you use the Window class, it will assign forward these to its own methods.
         boost::function<void (Button)> onButtonDown, onButtonUp;
         
+        //! Returns the currently active TextInput instance, or 0.
         TextInput* textInput() const;
+        //! Sets the currently active TextInput, or clears it (input = 0).
         void setTextInput(TextInput* input);
     };
 }

data/Gosu/Math.hpp

@@ -50,11 +50,12 @@ namespace Gosu
     //! specified by angle.
     //! \param angle Angle in degrees where 0.0 means upwards.
     double offsetY(double angle, double radius);
-    //! Returns the angle between two points in degrees, where 0.0 means
+    //! Returns the angle from point 1 to point 2 in degrees, where 0.0 means
     //! upwards. Returns def if both points are equal.
     double angle(double fromX, double fromY, double toX, double toY,
         double def = 0);
-    //! Returns the smallest positive angle between two angles.
+    //! Returns the smallest angle that can be added to angle1 to get to
+    //! angle2 (can be negative if counter-clockwise movement is shorter).
     double angleDiff(double angle1, double angle2);
     //! Normalizes an angle to fit into the range [0; 360[.
     double normalizeAngle(double angle);

data/Gosu/RotFlip.hpp

@@ -1,116 +1,125 @@
-//! \file RotFlip.hpp
-//! Interface of the undocumented RotFlip class.
-
-#ifndef GOSU_ROTFLIP_HPP
-#define GOSU_ROTFLIP_HPP
-
-namespace Gosu
-{
-    enum RotFlipName
-    {
-        rfDefault,
-        rfRotate90,
-        rfRotate180,
-        rfRotate270,
-
-        rfFlipX,
-        rfRotate90FlipX,
-        rfRotate180FlipX,
-        rfRotate270FlipX,
-        
-        rfFlipY          = rfRotate180FlipX,
-        rfRotate90FlipY  = rfRotate270FlipX,
-        rfRotate180FlipY = rfFlipX,
-        rfRotate270FlipY = rfRotate90FlipX,
-
-        rfFlipXRotate90  = rfRotate270FlipX,
-        rfFlipXRotate180 = rfRotate180FlipX,
-        rfFlipXRotate270 = rfRotate90FlipX,
-
-        rfFlipYRotate90  = rfRotate90FlipX,
-        rfFlipYRotate180 = rfFlipX,
-        rfFlipYRotate270 = rfRotate270FlipX
-    };
-
-    class RotFlip
-    {
-        RotFlipName name_;
-
-        typedef RotFlipName TransTable[8];
-        static const TransTable flipXTable, flipYTable, rotate90Table,
-            rotate180Table, rotate270Table;
-
-        typedef unsigned CornerTable[8][4];
-        static const CornerTable mapCornerTable, realCornerTable;
-
-    public:
-        RotFlip(RotFlipName name = rfDefault)
-        : name_(name)
-        {
-        }
-
-        RotFlipName name() const
-        {
-            return name_;
-        }
-
-        void flipX()
-        {
-            name_ = flipXTable[name_];
-        }
-
-        void flipY()
-        {
-            name_ = flipYTable[name_];
-        }
-
-        void rotate90()
-        {
-            name_ = rotate90Table[name_];
-        }
-
-        void rotate180()
-        {
-            name_ = rotate180Table[name_];
-        }
-
-        void rotate270()
-        {
-            name_ = rotate270Table[name_];
-        }
-
-        bool flipped() const
-        {
-            return name_ >= rfFlipX;
-        }
-
-        bool rotated() const
-        {
-            return name_ % 2 == 1;
-        }
-
-        unsigned mapCorner(unsigned n) const
-        {
-            return mapCornerTable[name_][n];
-        }
-
-        unsigned realCorner(unsigned n) const
-        {
-            return realCornerTable[name_][n];
-        }
-    };
-
-    inline bool operator==(RotFlip a, RotFlip b)
-    {
-        return a.name() == b.name();
-    }
-
-    inline bool operator!=(RotFlip a, RotFlip b)
-    {
-        return a.name() != b.name();
-    }
-
-    void applyToPoint(RotFlip rotFlip, int& x, int& y, int max);
-}
-
-#endif
+//! \file RotFlip.hpp
+//! Interface of the RotFlip class.
+
+#ifndef GOSU_ROTFLIP_HPP
+#define GOSU_ROTFLIP_HPP
+
+namespace Gosu
+{
+    //! Human-understandable descriptions of the variants of rotations and flips
+    //! that can be constructed.
+    enum RotFlipName
+    {
+        rfDefault,
+        rfRotate90,
+        rfRotate180,
+        rfRotate270,
+
+        rfFlipX,
+        rfRotate90FlipX,
+        rfRotate180FlipX,
+        rfRotate270FlipX,
+        
+        rfFlipY          = rfRotate180FlipX,
+        rfRotate90FlipY  = rfRotate270FlipX,
+        rfRotate180FlipY = rfFlipX,
+        rfRotate270FlipY = rfRotate90FlipX,
+
+        rfFlipXRotate90  = rfRotate270FlipX,
+        rfFlipXRotate180 = rfRotate180FlipX,
+        rfFlipXRotate270 = rfRotate90FlipX,
+
+        rfFlipYRotate90  = rfRotate90FlipX,
+        rfFlipYRotate180 = rfFlipX,
+        rfFlipYRotate270 = rfRotate270FlipX
+    };
+    
+    //! Light-weight class that encodes a rotation by 0, 90, 180, or 270
+    //! degrees as well as optional horizontal and/or vertical flips.
+    //! In short, this convieniently encodes the eight ways in which a
+    //! aligned rectangle can be linearly transformed to result in an aligned
+    //! rectangle again.
+    //! Especially useful for games with tile-based maps.
+    class RotFlip
+    {
+        RotFlipName name_;
+
+        typedef RotFlipName TransTable[8];
+        static const TransTable flipXTable, flipYTable, rotate90Table,
+            rotate180Table, rotate270Table;
+
+        typedef unsigned CornerTable[8][4];
+        static const CornerTable mapCornerTable, realCornerTable;
+
+    public:
+        RotFlip(RotFlipName name = rfDefault)
+        : name_(name)
+        {
+        }
+
+        RotFlipName name() const
+        {
+            return name_;
+        }
+
+        void flipX()
+        {
+            name_ = flipXTable[name_];
+        }
+
+        void flipY()
+        {
+            name_ = flipYTable[name_];
+        }
+
+        void rotate90()
+        {
+            name_ = rotate90Table[name_];
+        }
+
+        void rotate180()
+        {
+            name_ = rotate180Table[name_];
+        }
+
+        void rotate270()
+        {
+            name_ = rotate270Table[name_];
+        }
+
+        bool flipped() const
+        {
+            return name_ >= rfFlipX;
+        }
+
+        bool rotated() const
+        {
+            return name_ % 2 == 1;
+        }
+
+        unsigned mapCorner(unsigned n) const
+        {
+            return mapCornerTable[name_][n];
+        }
+
+        unsigned realCorner(unsigned n) const
+        {
+            return realCornerTable[name_][n];
+        }
+    };
+
+    inline bool operator==(RotFlip a, RotFlip b)
+    {
+        return a.name() == b.name();
+    }
+
+    inline bool operator!=(RotFlip a, RotFlip b)
+    {
+        return a.name() != b.name();
+    }
+    
+    //! Applies a RotFlip to a point x/y in a square of side length max.
+    void applyToPoint(RotFlip rotFlip, int& x, int& y, int max);
+}
+
+#endif

data/Gosu/Sockets.hpp

@@ -1,129 +1,139 @@
-//! \file Sockets.hpp
-//! Interface of the three socket classes, MessageSocket, CommSocket and ListenerSocket.
-
-#ifndef GOSU_SOCKETS_HPP
-#define GOSU_SOCKETS_HPP
-
-#include <boost/cstdint.hpp>
-#include <boost/function.hpp>
-#include <boost/scoped_ptr.hpp>
-#include <cstddef>
-#include <string>
-
-namespace Gosu
-{
-    // Both addresses and ports are returned from and given to Gosu
-    // functions in host byte order.
-    typedef boost::uint32_t SocketAddress;
-    typedef boost::uint16_t SocketPort;
-    const SocketPort anyPort = 0;
-
-    //! Tries to convert a dotted IP4 string into an address suitable for
-    //! socket functions. If the string supplied is not such a string, it
-    //! tries to look up the host via DNS. If both methods fail, zero is
-    //! returned.
-    SocketAddress stringToAddress(const std::string& s);
-    //! Converts an address into a dotted IP4 string.
-    std::string addressToString(SocketAddress address);
-
-    //! Wraps an UDP socket. Message sockets can send data to and receive
-    //! data from arbitrary addresses. Also, message sockets send messages
-    //! (packets) which are limited in size and can arrive in any order, or
-    //! not at all.
-    class MessageSocket
-    {
-        struct Impl;
-        boost::scoped_ptr<Impl> pimpl;
-
-    public:
-        //! Opens a message socket for listening at the specified port.
-        //! Gosu::anyPort may be passed to have the message socket use
-        //! a random free port.
-        explicit MessageSocket(SocketPort port);
-        ~MessageSocket();
-
-        //! Returns the local address of the socket.
-        SocketAddress address() const;
-        //! Returns the local port of the socket.
-        SocketPort port() const;
-        //! Returns the maximum size, in bytes, of a packet that can be sent
-        //! from this socket.
-        std::size_t maxMessageSize() const;
-
-        //! Collects all the packets that were sent to this socket and
-        //! calls onReceive for each of them.
-        void update();
-
-        //! Sends something to the given port of the computer identified
-        //! by the address.
-        void send(SocketAddress address, SocketPort port,
-            const void* buffer, std::size_t size);
-        /*void broadcast(SocketPort port, const void* buffer,
-            std::size_t size);*/
-
-        //! If assigned, will be called by update for every packet received.
-        boost::function<void (SocketAddress, SocketPort, const void*,
-            std::size_t)> onReceive;
-    };
-
-    enum CommMode
-    {
-        cmRaw,
-        //cmLines,
-        cmManaged
-    };
-
-    class Socket;
-
-    class CommSocket
-    {
-        struct Impl;
-        boost::scoped_ptr<Impl> pimpl;
-
-    public:
-        CommSocket(CommMode mode, SocketAddress targetAddress,
-            SocketPort targetPort);
-        CommSocket(CommMode mode, Socket& socket);
-        ~CommSocket();
-
-        SocketAddress address() const;
-        SocketPort port() const;
-        SocketAddress remoteAddress() const;
-        SocketPort remotePort() const;
-        CommMode mode() const;
-
-        bool connected() const;
-        void disconnect();
-        bool keepAlive() const;
-        void setKeepAlive(bool value);
-
-        void update();
-        void send(const void* buffer, std::size_t size);
-        void sendPendingData();
-        std::size_t pendingBytes() const;
-
-        boost::function<void (const void*, std::size_t)> onReceive;
-        boost::function<void ()> onDisconnection;
-    };
-
-    class ListenerSocket
-    {
-        struct Impl;
-        boost::scoped_ptr<Impl> pimpl;
-
-    public:
-        ListenerSocket(SocketPort port);
-        ~ListenerSocket();
-
-        SocketAddress address() const;
-        SocketPort port() const;
-
-        void update();
-
-        // This signal is fired by update() whenever someone connects
-        // to the port which is currently listened on.
-        boost::function<void (Socket&)> onConnection;
-    };
-}
-
-#endif
+//! \file Sockets.hpp
+//! Interface of the three socket classes, MessageSocket, CommSocket and ListenerSocket.
+
+#ifndef GOSU_SOCKETS_HPP
+#define GOSU_SOCKETS_HPP
+
+#include <boost/cstdint.hpp>
+#include <boost/function.hpp>
+#include <boost/scoped_ptr.hpp>
+#include <cstddef>
+#include <string>
+
+namespace Gosu
+{
+    //! Addresses are returned from and given to Gosu functions in host byte order.
+    typedef boost::uint32_t SocketAddress;
+
+    //! Ports are returned from and given to Gosu functions in host byte order.
+    typedef boost::uint16_t SocketPort;
+    
+    //! Constant that can be used as a placeholder for an arbitrary port, e.g. when
+    //! starting to listen.
+    const SocketPort anyPort = 0;
+    
+    //! Tries to convert a dotted IP4 string into an address suitable for
+    //! socket functions. If the string supplied is not such a string, it
+    //! tries to look up the host via DNS. If both methods fail, zero is
+    //! returned.
+    SocketAddress stringToAddress(const std::string& s);
+    //! Converts an address into a dotted IP4 string.
+    std::string addressToString(SocketAddress address);
+
+    //! Wraps an UDP socket. Message sockets can send data to and receive
+    //! data from arbitrary addresses. Also, message sockets send messages
+    //! (packets) which are limited in size and can arrive in any order, or
+    //! not at all.
+    class MessageSocket
+    {
+        struct Impl;
+        boost::scoped_ptr<Impl> pimpl;
+
+    public:
+        //! Opens a message socket for listening at the specified port.
+        //! Gosu::anyPort may be passed to have the message socket use
+        //! a random free port.
+        explicit MessageSocket(SocketPort port);
+        ~MessageSocket();
+
+        //! Returns the local address of the socket.
+        SocketAddress address() const;
+        //! Returns the local port of the socket.
+        SocketPort port() const;
+        //! Returns the maximum size, in bytes, of a packet that can be sent
+        //! from this socket.
+        std::size_t maxMessageSize() const;
+
+        //! Collects all the packets that were sent to this socket and
+        //! calls onReceive for each of them.
+        void update();
+
+        //! Sends something to the given port of the computer identified
+        //! by the address.
+        void send(SocketAddress address, SocketPort port,
+            const void* buffer, std::size_t size);
+        /*void broadcast(SocketPort port, const void* buffer,
+            std::size_t size);*/
+
+        //! If assigned, will be called by update for every packet received.
+        boost::function<void (SocketAddress, SocketPort, const void*,
+            std::size_t)> onReceive;
+    };
+    
+    //! Defines the way in which data is collected until the onReceive event
+    //! is called for CommSockets.
+    enum CommMode
+    {
+        cmRaw,
+        //cmLines,
+        cmManaged
+    };
+    
+    class Socket;
+    
+    //! Wraps a TCP socket that is used for one part of bi-directional
+    //! communication.
+    class CommSocket
+    {
+        struct Impl;
+        boost::scoped_ptr<Impl> pimpl;
+
+    public:
+        CommSocket(CommMode mode, SocketAddress targetAddress,
+            SocketPort targetPort);
+        CommSocket(CommMode mode, Socket& socket);
+        ~CommSocket();
+
+        SocketAddress address() const;
+        SocketPort port() const;
+        SocketAddress remoteAddress() const;
+        SocketPort remotePort() const;
+        CommMode mode() const;
+
+        bool connected() const;
+        void disconnect();
+        bool keepAlive() const;
+        void setKeepAlive(bool value);
+
+        void update();
+        void send(const void* buffer, std::size_t size);
+        void sendPendingData();
+        std::size_t pendingBytes() const;
+
+        boost::function<void (const void*, std::size_t)> onReceive;
+        boost::function<void ()> onDisconnection;
+    };
+    
+    //! Wraps a TCP socket that waits on a specific port and can create
+    //! CommSocket instances via its onConnection event.
+    class ListenerSocket
+    {
+        struct Impl;
+        boost::scoped_ptr<Impl> pimpl;
+
+    public:
+        ListenerSocket(SocketPort port);
+        ~ListenerSocket();
+
+        SocketAddress address() const;
+        SocketPort port() const;
+
+        void update();
+
+        //! This signal is fired by update() whenever someone connects
+        //! to the port which is currently listened on.
+        boost::function<void (Socket&)> onConnection;
+    };
+}
+
+#endif