gosu 0.7.13 → 0.7.13.2

data/COPYING.txt

@@ -19,11 +19,13 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 
 Julian Raschke julian@raschke.de
+
 Jan Lücker jan.luecker@gmx.de
-http://code.google.com/p/gosu/
+
+http://www.libgosu.org/
 
 ***
 
-Does NOT apply to fmod.dll shipped with the Windows version of Gosu,
+This does NOT apply to fmod.dll shipped with the Windows version of Gosu,
 or the bytecode of FMOD contained in Gosu.framework and gosu.bundle on OS X.
 FMOD is a property of Firelight Technologies Pty, Ltd., see www.fmod.org.

data/Gosu/Audio.hpp

@@ -49,8 +49,11 @@ namespace Gosu
 
 		bool playing() const;
 		bool paused() const;
+        //! Pauses this instance to be resumed afterwards. It will still keep a channel filled while paused.
         void pause();
         void resume();
+        //! Stops this instance of a sound being played.
+        //! Calling this twice, or too late, does not do any harm.
 		void stop();
 
         //! \param volume Can be anything from 0.0 (silence) to 1.0 (full
@@ -86,8 +89,8 @@ namespace Gosu
         //! Plays the sample without panning.
         //! \param volume Can be anything from 0.0 (silence) to 1.0 (full
         //! volume).
-        //! \param speed Playback speed is only limited by FMOD's
-        //! capabilities and can accept very high or low values. Use 1.0 for
+        //! \param speed Playback speed is only limited by the underlying audio library,
+        //! and can accept very high or low values. Use 1.0 for
         //! normal playback speed.
         SampleInstance play(double volume = 1, double speed = 1,
             bool looping = false) const;
@@ -98,8 +101,8 @@ namespace Gosu
         //! \param pan Can be anything from -1.0 (left) to 1.0 (right).
         //! \param volume Can be anything from 0.0 (silence) to 1.0 (full
         //! volume).
-        //! \param speed Playback speed is only limited by FMOD's (or
-        //! SDL_mixer's, respectively) capabilities and can accept very high
+        //! \param speed Playback speed is only limited by by the underlying audio library,
+        //! and can accept very high
         //! or low values. Use 1.0 for normal playback speed.
         SampleInstance playPan(double pan, double volume = 1, double speed = 1,
             bool looping = false) const;
@@ -151,7 +154,7 @@ namespace Gosu
         //! Stops playback of this song if it is currently played or paused.
         //! Afterwards, currentSong will return 0.
         void stop();
-        //! Returns if the song is currently playing.
+        //! Returns true if the song is currently playing.
         bool playing() const;
         //! Returns the current volume of the song.
         double volume() const;

data/Gosu/Font.hpp

@@ -23,7 +23,8 @@ namespace Gosu
 
     public:
         //! Constructs a font that can be drawn onto the graphics object.
-        //! \param fontName Name of a system font, or a filename to a TTF file (must contain '/').
+        //! \param fontName Name of a system font, or a filename to a TTF
+        //!        file (must contain '/', does not work on Linux).
         //! \param height Height of the font, in pixels.
         Font(Graphics& graphics, const std::wstring& fontName,
             unsigned height);
@@ -32,7 +33,7 @@ namespace Gosu
         //! Returns the height of the font, in pixels.
         unsigned height() const;
 
-        //! Returns the width the given text would occupy if drawn.
+        //! Returns the width, in pixels, the given text would occupy if drawn.
         double textWidth(const std::wstring& text, double factorX = 1) const;
 
         //! Draws text so the top left corner of the text is at (x; y).
@@ -49,7 +50,8 @@ namespace Gosu
         void drawRel(const std::wstring& text, double x, double y, ZPos z,
             double relX, double relY, double factorX = 1, double factorY = 1,
             Color c = Colors::white, AlphaMode mode = amDefault) const;
-            
+        
+        //! Analogous to draw, but rotates the text by a given angle.
         void drawRot(const std::wstring& text, double x, double y, ZPos z, double angle,
             double factorX = 1, double factorY = 1,
             Color c = Colors::white, AlphaMode mode = amDefault) const;

data/Gosu/Gosu.hpp

@@ -1,6 +1,12 @@
 //! \file Gosu.hpp
 //! Umbrella header for lazy people with fast compilers, or pre-compiled headers.
 
+//! \mainpage Gosu C++ Documentation
+//!
+//! These pages serve as a reference on 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, http://www.libgosu.org/.
+
 #ifndef GOSU_GOSU_HPP
 #define GOSU_GOSU_HPP
 

data/Gosu/Graphics.hpp

@@ -12,19 +12,11 @@
 
 namespace Gosu
 {
+    //! Returns the width, in pixels, of the user's primary screen.
     unsigned screenWidth();
+    
+    //! Returns the height, in pixels, of the user's primary screen.
     unsigned screenHeight();
-
-    //! Flags that affect the softness of a border.
-    enum BorderFlags
-    {
-        bfSoft = 0,
-        bfHardLeft = 1,
-        bfHardTop = 2,
-        bfHardRight = 4,
-        bfHardBottom = 8,
-        bfHard = bfHardLeft | bfHardTop | bfHardRight | bfHardBottom
-    };        
     
     //! Serves as the target of all drawing and provides basic drawing
     //! functionality.
@@ -58,11 +50,12 @@ namespace Gosu
         void beginGL();
         //! Resets Gosu into its default rendering state.
         void endGL();
-        // Enables clipping to a specified rectangle.
+        //! Enables clipping to a specified rectangle.
         void beginClipping(int x, int y, unsigned width, unsigned height);
-        // Disables clipping.
+        //! Disables clipping.
         void endClipping();
 
+        //! Draws a line from one point to another (last pixel exclusive).
         void drawLine(double x1, double y1, Color c1,
             double x2, double y2, Color c2,
             ZPos z, AlphaMode mode = amDefault);

data/Gosu/GraphicsBase.hpp

@@ -17,7 +17,7 @@ namespace Gosu
     //! your drawing operation does not need Z ordering and can be performed
     //! immediately.
     const double zImmediate = -std::numeric_limits<double>::infinity();
-
+    
     //! Determines the way colors are combined when one is drawn onto
     //! another.
     enum AlphaMode
@@ -30,14 +30,14 @@ namespace Gosu
         //! to the old color's channels.
         amAdditive
     };
-
+    
     enum FontFlags
     {
         ffBold      = 1,
         ffItalic    = 2,
         ffUnderline = 4
     };
-
+    
     enum TextAlign
     {
         taLeft,
@@ -45,6 +45,17 @@ namespace Gosu
         taCenter,
         taJustify
     };
+    
+    //! Flags that affect the tileability of an image.
+    enum BorderFlags
+    {
+        bfSoft = 0,
+        bfTileableLeft = 1,
+        bfTileableTop = 2,
+        bfTileableRight = 4,
+        bfTileableBottom = 8,
+        bfTileable = bfTileableLeft | bfTileableTop | bfTileableRight | bfTileableBottom
+    };        
 }
 
 #endif

data/Gosu/IO.hpp

@@ -1,255 +1,259 @@
-//! \file IO.hpp
-//! Contains everything related to input and output.
-
-#ifndef GOSU_IO_HPP
-#define GOSU_IO_HPP
-
-#include <boost/utility.hpp>
-#include <boost/scoped_ptr.hpp>
-#include <cstddef>
-#include <algorithm>
-#include <string>
-#include <vector>
-
-namespace Gosu
-{
-    class Resource;
-    
-    enum ByteOrder { boLittle, boBig, boDontCare };
-#ifdef __BIG_ENDIAN__
-    const ByteOrder nativeByteOrder = boBig, otherByteOrder = boLittle;
-#else
-    const ByteOrder nativeByteOrder = boLittle, otherByteOrder = boBig;
-#endif
-
-    class Reader
-    {
-        const Resource* res;
-        std::size_t pos;
-
-    public:
-        Reader(const Resource& resource, std::size_t position)
-        : res(&resource), pos(position)
-        {
-        }
-
-        const Resource& resource() const
-        {
-            return *res;
-        }
-
-        std::size_t position() const
-        {
-            return pos;
-        }
-
-        void setPosition(std::size_t value)
-        {
-            // TODO: Check?
-            pos = value;
-        }
-
-        void seek(std::ptrdiff_t offset)
-        {
-            // TODO: Check?
-            pos += offset;
-        }
-
-        void read(void* destBuffer, std::size_t length);
-        
-        //! Convenience function; equivalent to read(&t, sizeof t).
-        template<typename T>
-        void readPod(T& t, ByteOrder bo = boDontCare)
-        {
-            read(&t, sizeof t);
-            if (bo == otherByteOrder)
-            {
-                char* begin = reinterpret_cast<char*>(&t);
-                std::reverse(begin, begin + sizeof t);
-            }
-        }
-
-        //! Similar to readPod(T&), but returns the read value instead.
-        template<typename T>
-        T getPod(ByteOrder bo = boDontCare)
-        {
-            T t;
-            readPod<T>(t, bo);
-            return t;
-        }
-    };
-
-    class Writer
-    {
-        Resource* res;
-        std::size_t pos;
-
-    public:
-        Writer(Resource& resource, std::size_t position)
-        : res(&resource), pos(position)
-        {
-        }
-
-        Resource& resource() const
-        {
-            return *res;
-        }
-
-        std::size_t position() const
-        {
-            return pos;
-        }
-
-        void setPosition(std::size_t value)
-        {
-            // TODO: Check?
-            pos = value;
-        }
-
-        void seek(std::ptrdiff_t offset)
-        {
-            // TODO: Check?
-            pos += offset;
-        }
-
-        void write(const void* sourceBuffer, std::size_t length);
-
-        //! Convenience function; equivalent to write(&t, sizeof t).
-        template<typename T>
-        void writePod(const T& t, ByteOrder bo = boDontCare)
-        {
-            if (bo == otherByteOrder)
-            {
-                char buf[sizeof t];
-                const char* begin = reinterpret_cast<const char*>(&t);
-                std::reverse_copy(begin, begin + sizeof t, buf);
-                write(buf, sizeof buf);
-            }
-            else
-                write(&t, sizeof t);
-        }
-    };
-
-    //! Base class for resources. A resource in Gosu is nothing more but a
-    //! piece of binary data that can be read or written, for example files
-    //! or simply areas of allocated memory.
-    //! A resource always knows its size and can resize itself, thereby either
-    //! truncating its content or allocating room for more data.
-    class Resource : boost::noncopyable
-    {
-    public:
-        virtual ~Resource()
-        {
-        }
-
-        //! Convenience: Creates a new Reader that reads from the start of
-        //! the resource.
-        Reader frontReader() const
-        {
-            return Reader(*this, 0);
-        }
-
-        //! Convenience: Creates a new Writer that appends data at the
-        //! end of the resource.
-        Writer backWriter()
-        {
-            return Writer(*this, size());
-        }
-
-        virtual std::size_t size() const = 0;
-
-        virtual void resize(std::size_t newSize) = 0;
-
-        virtual void read(std::size_t offset, std::size_t length,
-            void* destBuffer) const = 0;
-
-        virtual void write(std::size_t offset, std::size_t length,
-            const void* sourceBuffer) = 0;
-    };
-
-    //! Piece of memory with the Resource interface.
-    class Buffer : public Resource
-    {
-        std::vector<char> buf;
-
-    public:
-        Buffer()
-        {
-        }
-
-        Buffer(const Buffer& other)
-        : buf(other.buf)
-        {
-        }
-
-        Buffer& operator=(const Buffer& other)
-        {
-            buf = other.buf;
-            return *this;
-        }
-
-        std::size_t size() const
-        {
-            return buf.size();
-        }
-
-        void resize(std::size_t newSize)
-        {
-            buf.resize(newSize);
-        }
-
-        void read(std::size_t offset, std::size_t length,
-            void* destBuffer) const;
-
-        void write(std::size_t offset, std::size_t length,
-            const void* sourceBuffer);
-
-        const void* data() const
-        {
-            return &buf[0];
-        }
-
-        void* data()
-        {
-            return &buf[0];
-        }
-    };
-
-    enum FileMode
-    {
-        //! Opens an existing file for reading; throws an exception if the file
-        //! cannot be found.
-        fmRead,
-        //! Writes data to a file. If the file already exists, is emptied on
-        //! opening. If the file does not exist, it is created.
-        fmReplace,
-        //! Opens or creates a file with writing access, but does not clear
-        //! existing contents.
-        fmAlter
-    };
-
-    //! File with the Resource interface.
-    class File : public Resource
-    {
-        struct Impl;
-        boost::scoped_ptr<Impl> pimpl;
-
-    public:
-        explicit File(const std::wstring& filename, FileMode mode = fmRead);
-        ~File();
-
-        std::size_t size() const;
-        void resize(std::size_t newSize);
-        void read(std::size_t offset, std::size_t length,
-            void* destBuffer) const;
-        void write(std::size_t offset, std::size_t length,
-            const void* sourceBuffer);
-    };
-
-    //! Loads a whole file into a buffer.
-    void loadFile(Buffer& buffer, const std::wstring& filename);
-    //! Creates or overwrites a file with the contents of a buffer.
-    void saveFile(const Buffer& buffer, const std::wstring& filename);
-}
-
-#endif
+//! \file IO.hpp
+//! Contains everything related to input and output.
+
+#ifndef GOSU_IO_HPP
+#define GOSU_IO_HPP
+
+#include <boost/utility.hpp>
+#include <boost/scoped_ptr.hpp>
+#include <cstddef>
+#include <algorithm>
+#include <string>
+#include <vector>
+
+namespace Gosu
+{
+    class Resource;
+    
+    enum ByteOrder { boLittle, boBig, boDontCare };
+#ifdef __BIG_ENDIAN__
+    const ByteOrder nativeByteOrder = boBig, otherByteOrder = boLittle;
+#else
+    const ByteOrder nativeByteOrder = boLittle, otherByteOrder = boBig;
+#endif
+
+    //! Utility class that points to a specific position in a resource
+    //! and offers an interface for sequential reading.
+    class Reader
+    {
+        const Resource* res;
+        std::size_t pos;
+
+    public:
+        Reader(const Resource& resource, std::size_t position)
+        : res(&resource), pos(position)
+        {
+        }
+
+        const Resource& resource() const
+        {
+            return *res;
+        }
+
+        std::size_t position() const
+        {
+            return pos;
+        }
+
+        void setPosition(std::size_t value)
+        {
+            // TODO: Check?
+            pos = value;
+        }
+
+        void seek(std::ptrdiff_t offset)
+        {
+            // TODO: Check?
+            pos += offset;
+        }
+
+        void read(void* destBuffer, std::size_t length);
+        
+        //! Convenience function; equivalent to read(&t, sizeof t).
+        template<typename T>
+        void readPod(T& t, ByteOrder bo = boDontCare)
+        {
+            read(&t, sizeof t);
+            if (bo == otherByteOrder)
+            {
+                char* begin = reinterpret_cast<char*>(&t);
+                std::reverse(begin, begin + sizeof t);
+            }
+        }
+
+        //! Similar to readPod(T&), but returns the read value instead.
+        template<typename T>
+        T getPod(ByteOrder bo = boDontCare)
+        {
+            T t;
+            readPod<T>(t, bo);
+            return t;
+        }
+    };
+    
+    //! Utility class that points to a specific position in a resource
+    //! and offers an interface for sequential writing.
+    class Writer
+    {
+        Resource* res;
+        std::size_t pos;
+
+    public:
+        Writer(Resource& resource, std::size_t position)
+        : res(&resource), pos(position)
+        {
+        }
+
+        Resource& resource() const
+        {
+            return *res;
+        }
+
+        std::size_t position() const
+        {
+            return pos;
+        }
+
+        void setPosition(std::size_t value)
+        {
+            // TODO: Check?
+            pos = value;
+        }
+
+        void seek(std::ptrdiff_t offset)
+        {
+            // TODO: Check?
+            pos += offset;
+        }
+
+        void write(const void* sourceBuffer, std::size_t length);
+
+        //! Convenience function; equivalent to write(&t, sizeof t).
+        template<typename T>
+        void writePod(const T& t, ByteOrder bo = boDontCare)
+        {
+            if (bo == otherByteOrder)
+            {
+                char buf[sizeof t];
+                const char* begin = reinterpret_cast<const char*>(&t);
+                std::reverse_copy(begin, begin + sizeof t, buf);
+                write(buf, sizeof buf);
+            }
+            else
+                write(&t, sizeof t);
+        }
+    };
+
+    //! Base class for resources. A resource in Gosu is nothing more but a
+    //! piece of binary data that can be read or written, for example files
+    //! or simply areas of allocated memory.
+    //! A resource always knows its size and can resize itself, thereby either
+    //! truncating its content or allocating room for more data.
+    class Resource : boost::noncopyable
+    {
+    public:
+        virtual ~Resource()
+        {
+        }
+
+        //! Convenience: Creates a new Reader that reads from the start of
+        //! the resource.
+        Reader frontReader() const
+        {
+            return Reader(*this, 0);
+        }
+
+        //! Convenience: Creates a new Writer that appends data at the
+        //! end of the resource.
+        Writer backWriter()
+        {
+            return Writer(*this, size());
+        }
+
+        virtual std::size_t size() const = 0;
+
+        virtual void resize(std::size_t newSize) = 0;
+
+        virtual void read(std::size_t offset, std::size_t length,
+            void* destBuffer) const = 0;
+
+        virtual void write(std::size_t offset, std::size_t length,
+            const void* sourceBuffer) = 0;
+    };
+
+    //! Piece of memory with the Resource interface.
+    class Buffer : public Resource
+    {
+        std::vector<char> buf;
+
+    public:
+        Buffer()
+        {
+        }
+
+        Buffer(const Buffer& other)
+        : buf(other.buf)
+        {
+        }
+
+        Buffer& operator=(const Buffer& other)
+        {
+            buf = other.buf;
+            return *this;
+        }
+
+        std::size_t size() const
+        {
+            return buf.size();
+        }
+
+        void resize(std::size_t newSize)
+        {
+            buf.resize(newSize);
+        }
+
+        void read(std::size_t offset, std::size_t length,
+            void* destBuffer) const;
+
+        void write(std::size_t offset, std::size_t length,
+            const void* sourceBuffer);
+
+        const void* data() const
+        {
+            return &buf[0];
+        }
+
+        void* data()
+        {
+            return &buf[0];
+        }
+    };
+
+    enum FileMode
+    {
+        //! Opens an existing file for reading; throws an exception if the file
+        //! cannot be found.
+        fmRead,
+        //! Writes data to a file. If the file already exists, is emptied on
+        //! opening. If the file does not exist, it is created.
+        fmReplace,
+        //! Opens or creates a file with writing access, but does not clear
+        //! existing contents.
+        fmAlter
+    };
+
+    //! File with the Resource interface.
+    class File : public Resource
+    {
+        struct Impl;
+        boost::scoped_ptr<Impl> pimpl;
+
+    public:
+        explicit File(const std::wstring& filename, FileMode mode = fmRead);
+        ~File();
+
+        std::size_t size() const;
+        void resize(std::size_t newSize);
+        void read(std::size_t offset, std::size_t length,
+            void* destBuffer) const;
+        void write(std::size_t offset, std::size_t length,
+            const void* sourceBuffer);
+    };
+
+    //! Loads a whole file into a buffer.
+    void loadFile(Buffer& buffer, const std::wstring& filename);
+    //! Creates or overwrites a file with the contents of a buffer.
+    void saveFile(const Buffer& buffer, const std::wstring& filename);
+}
+
+#endif