Generate sources (79beccf)

Author: Robot

README.md

@@ -5,17 +5,19 @@
 Documentation
 -------------
 
-#### [Introduction](#introduction)
-#### [Installation](#installation)
-#### [Tutorials][]
-#### [API Documentation][]
-#### [Examples](examples) / [Demos][]
+- **[Installation](#installation)**
+
+- **[Tutorials][]**
+
+- **[API Documentation][]**
+
+- **[Examples](examples)** / **[Demos][]**
 
 
 Introduction
 ------------
 
-**Note to existing users**: *CrSFML* has been recently rewritten from scratch. See the [release notes][releases] for information.
+**Note to existing users**: *CrSFML* has been recently rewritten from scratch. *CrSFML* releases since 2.4 have an entirely different installation procedure, and multiple important API changes.
 
 *CrSFML* is a library that allows SFML to be used with the Crystal programming language. [SFML][] is a library written in C++, so *CrSFML* also needs to ship C bindings to SFML, called *VoidCSFML*.
 
@@ -25,7 +27,7 @@ To quote the official site of SFML,
 
 Indeed, SFML is most often used to make video games. It provides features such as hardware-accelerated 2D graphics, handling keyboard, mouse and gamepad input, vector and matrix manipulation, managing windows (can also be used as a base for OpenGL drawing), working with multiple image formats, audio playback and recording, basic networking... Check out some [demos][] of *CrSFML* to see what it can do.
 
-*CrSFML* consists almost entirely of automatically generated code, based on SFML's header files. The *dev* git branch contains the [generator program](generate.cr) and the small manually written source files. The generated source code can be viewed at the [sources][] branch.
+*CrSFML* consists almost entirely of automatically generated code, based on SFML's header files. The *master* git branch contains the [generator program](generate.cr) and the small manually written source files. The generated source code can be viewed at the [sources][] branch.
 
 ### Differences between SFML and CrSFML
 
@@ -49,12 +51,14 @@ The API of *CrSFML* (a library for Crystal) attempts to be similar to SFML (a C+
 Installation
 ------------
 
+Note that using [Shards][] is not enough to install *CrSFML*.
+
 This section defines two sets of step-by-step instructions to install *CrSFML* but these are not the only ways to do it; they can even be mixed (see [VoidCSFML installation instructions](voidcsfml/README.md#installation) for an alternative look)
 
 - [Approach 1](#approach-1): Generate latest *CrSFML* and *VoidCSFML* source code "from scratch"; build and use them from a local directory
     - Advantages:
         - The bindings can be fine-tuned to your system.
-        - Should support any SFML 2.3.x, maybe even other versions.
+        - Supports multiple recent [SFML versions](#install-sfml).
         - This is the right setup if you wish to contribute to *CrSFML*.
     - Disadvantages:
         - Need to always provide full path to *VoidCSFML* libraries when running a program using *CrSFML*.
@@ -63,16 +67,20 @@ This section defines two sets of step-by-step instructions to install *CrSFML* b
     - Advantages:
         - Easier installation.
     - Disadvantages:
-        - Tied to a particular version of SFML.
+        - Tied to a particular version of SFML (only SFML 2.4 right now).
         - Although sizes of SFML objects seem to always be of equal or smaller sizes than on Linux 64-bit with latest GCC (where the sources are generated), this is not completely guaranteed. So, in case of a mismatch, data may be written outside of the memory region allocated for an object.
 
 ### Install SFML
 
 The first step is to install the [SFML][] library itself. There are detailed [official instructions][sfml-install] on how to install it manually, however, on many systems there are easier ways.
 
+SFML versions 2.4.x and 2.3.x are supported by *CrSFML*.
+
 #### Linux
 
-Linux-based systems known to provide SFML 2.3.2 through their package manager: Ubuntu 16.04, Arch Linux, Fedora. Note that if you're installing an older version of SFML, it is not guaranteed to work (in fact, installation with [Approach 2](#approach-2) is almost guaranteed **not** to work).
+Many Linux-based systems provide SFML through their package manager. Make sure to install the *-dev* packages if there is such a separation in your Linux distribution of choice.
+
+Note that most often the packages provided by Linux distributions are outdated. If you're installing an older version of SFML (not recommended), make sure that it's still [supported by *CrSFML*](#install-sfml). For installation with [Approach 2](#approach-2) getting the latest version is even more important.
 
 For information on building SFML from source, check out [this article][sfml-install-linux] (but no need to install CSFML). It is as simple as downloading the source code and running:
 
@@ -101,7 +109,7 @@ Prerequisites: [Git][], [CMake][], [Crystal][], a C++ compiler
 #### Download latest generator source code
 
 ```bash
-git clone -b dev https://github.com/blaxpirit/crsfml
+git clone https://github.com/blaxpirit/crsfml
 cd crsfml
 ```
 
@@ -152,7 +160,7 @@ Prerequisites: [CMake][], [Crystal][], a C++ compiler
 
 #### Download a release of CrSFML
 
-Find the release of *CrSFML* that corresponds to your installed version of *SFML* (latest is strongly recommended) at the [releases][] page.
+Find the release of *CrSFML* that corresponds to your installed version of *SFML* (latest is strongly recommended) at the [releases][] page. Note that only releases starting at 2.4 are applicable, and only SFML versions since 2.4 are supported in this approach. The older releases are legacy CSFML-based releases.
 
 Download and extract it, and remember the version of the release (let's say v1.2.3) for later.
 

shard.yml

@@ -1,5 +1,5 @@
 name: crsfml
-version: 2.3.10
+version: 2.4.0
 
 authors:
   - Oleh Prypin <[email protected]>

src/audio/lib.cr

@@ -134,12 +134,15 @@ lib VoidCSFML
   fun soundrecorder_getdefaultdevice(result : LibC::Char**)
   fun soundrecorder_setdevice_zkC(self : Void*, name_size : LibC::SizeT, name : LibC::Char*, result : Bool*)
   fun soundrecorder_getdevice(self : Void*, result : LibC::Char**)
+  fun soundrecorder_setchannelcount_emS(self : Void*, channel_count : LibC::UInt)
+  fun soundrecorder_getchannelcount(self : Void*, result : LibC::UInt*)
   fun soundrecorder_isavailable(result : Bool*)
   fun soundrecorder_initialize(self : Void*)
   fun soundrecorder_setprocessinginterval_f4T(self : Void*, interval : Void*)
   fun soundrecorder_onstart(self : Void*, result : Bool*)
   fun soundrecorder_onstop(self : Void*)
   fun soundbufferrecorder_initialize(self : Void*)
+  fun soundbufferrecorder_finalize(self : Void*)
   fun soundbufferrecorder_getbuffer(self : Void*, result : Void**)
   fun soundbufferrecorder_start_emS(self : Void*, sample_rate : LibC::UInt, result : Bool*)
   fun soundbufferrecorder_stop(self : Void*)
@@ -148,6 +151,8 @@ lib VoidCSFML
   fun soundbufferrecorder_getdefaultdevice(result : LibC::Char**)
   fun soundbufferrecorder_setdevice_zkC(self : Void*, name_size : LibC::SizeT, name : LibC::Char*, result : Bool*)
   fun soundbufferrecorder_getdevice(self : Void*, result : LibC::Char**)
+  fun soundbufferrecorder_setchannelcount_emS(self : Void*, channel_count : LibC::UInt)
+  fun soundbufferrecorder_getchannelcount(self : Void*, result : LibC::UInt*)
   fun soundbufferrecorder_isavailable(result : Bool*)
   fun sfml_audio_version(LibC::Int*, LibC::Int*, LibC::Int*)
 end

src/audio/obj.cr

@@ -194,7 +194,7 @@ module SF
   #
   # *See also:* `SF::Sound`, `SF::SoundStream`
   class SoundSource
-    @_soundsource : VoidCSFML::SoundSource_Buffer = VoidCSFML::SoundSource_Buffer.new(0u8)
+    @_soundsource : VoidCSFML::SoundSource_Buffer
     # Enumeration of the sound source states
     enum Status
       # Sound is not playing
@@ -362,6 +362,13 @@ module SF
       VoidCSFML.soundsource_getattenuation(to_unsafe, out result)
       return result
     end
+    # Default constructor
+    #
+    # This constructor is meant to be called by derived classes only.
+    protected def initialize()
+      @_soundsource = uninitialized VoidCSFML::SoundSource_Buffer
+      VoidCSFML.soundsource_initialize(to_unsafe)
+    end
     include AlResource
     # :nodoc:
     def to_unsafe()
@@ -457,7 +464,7 @@ module SF
   #
   # *See also:* `SF::Music`
   abstract class SoundStream < SoundSource
-    @_soundstream : VoidCSFML::SoundStream_Buffer = VoidCSFML::SoundStream_Buffer.new(0u8)
+    @_soundstream : VoidCSFML::SoundStream_Buffer
     # Destructor
     def finalize()
       VoidCSFML.soundstream_finalize(to_unsafe)
@@ -567,7 +574,7 @@ module SF
     # Default constructor
     #
     # This constructor is only meant to be called by derived classes.
-    def initialize()
+    protected def initialize()
       @_soundsource = uninitialized VoidCSFML::SoundSource_Buffer
       @_soundstream = uninitialized VoidCSFML::SoundStream_Buffer
       raise "Unexpected memory layout" if as(Void*) + sizeof(LibC::Int) != to_unsafe
@@ -727,7 +734,7 @@ module SF
   #
   # *See also:* `SF::Sound`, `SF::SoundStream`
   class Music < SoundStream
-    @_music : VoidCSFML::Music_Buffer = VoidCSFML::Music_Buffer.new(0u8)
+    @_music : VoidCSFML::Music_Buffer
     # Default constructor
     def initialize()
       @_soundsource = uninitialized VoidCSFML::SoundSource_Buffer
@@ -902,6 +909,11 @@ module SF
     end
     # :nodoc:
     def initialize(channel_count : Int, sample_rate : Int)
+      @_soundsource = uninitialized VoidCSFML::SoundSource_Buffer
+      @_soundstream = uninitialized VoidCSFML::SoundStream_Buffer
+      @_music = uninitialized VoidCSFML::Music_Buffer
+      VoidCSFML.music_initialize(to_unsafe)
+      VoidCSFML.music_initialize_emSemS(to_unsafe, LibC::UInt.new(channel_count), LibC::UInt.new(sample_rate))
     end
     # :nodoc:
     def pitch=(pitch : Number)
@@ -1006,7 +1018,7 @@ module SF
   #
   # *See also:* `SF::SoundBuffer`, `SF::Music`
   class Sound < SoundSource
-    @_sound : VoidCSFML::Sound_Buffer = VoidCSFML::Sound_Buffer.new(0u8)
+    @_sound : VoidCSFML::Sound_Buffer
     # Default constructor
     def initialize()
       @_soundsource = uninitialized VoidCSFML::SoundSource_Buffer
@@ -1270,7 +1282,7 @@ module SF
   #
   # *See also:* `SF::Sound`, `SF::SoundBufferRecorder`
   class SoundBuffer
-    @_soundbuffer : VoidCSFML::SoundBuffer_Buffer = VoidCSFML::SoundBuffer_Buffer.new(0u8)
+    @_soundbuffer : VoidCSFML::SoundBuffer_Buffer
     # Default constructor
     def initialize()
       @_soundbuffer = uninitialized VoidCSFML::SoundBuffer_Buffer
@@ -1513,18 +1525,33 @@ module SF
   # by calling setDevice() with the appropriate device. Otherwise
   # the default capturing device will be used.
   #
+  # By default the recording is in 16-bit mono. Using the
+  # setChannelCount method you can change the number of channels
+  # used by the audio capture device to record. Note that you
+  # have to decide whether you want to record in mono or stereo
+  # before starting the recording.
+  #
   # It is important to note that the audio capture happens in a
   # separate thread, so that it doesn't block the rest of the
   # program. In particular, the onProcessSamples virtual function
   # (but not onStart and not onStop) will be called
   # from this separate thread. It is important to keep this in
   # mind, because you may have to take care of synchronization
   # issues if you share data between threads.
+  # Another thing to bear in mind is that you must call stop()
+  # in the destructor of your derived class, so that the recording
+  # thread finishes before your object is destroyed.
   #
   # Usage example:
   # ```c++
   # class CustomRecorder : public sf::SoundRecorder
   # {
+  #     ~CustomRecorder()
+  #     {
+  #         // Make sure to stop the recording thread
+  #         stop();
+  #     }
+  #
   #     virtual bool onStart() // optional
   #     {
   #         // Initialize whatever has to be done before the capture starts
@@ -1565,7 +1592,7 @@ module SF
   #
   # *See also:* `SF::SoundBufferRecorder`
   abstract class SoundRecorder
-    @_soundrecorder : VoidCSFML::SoundRecorder_Buffer = VoidCSFML::SoundRecorder_Buffer.new(0u8)
+    @_soundrecorder : VoidCSFML::SoundRecorder_Buffer
     # destructor
     def finalize()
       VoidCSFML.soundrecorder_finalize(to_unsafe)
@@ -1654,6 +1681,31 @@ module SF
       VoidCSFML.soundrecorder_getdevice(to_unsafe, out result)
       return String.new(result)
     end
+    # Set the channel count of the audio capture device
+    #
+    # This method allows you to specify the number of channels
+    # used for recording. Currently only 16-bit mono and
+    # 16-bit stereo are supported.
+    #
+    # * *channel_count* - Number of channels. Currently only
+    #                     mono (1) and stereo (2) are supported.
+    #
+    # *See also:* getChannelCount
+    def channel_count=(channel_count : Int)
+      VoidCSFML.soundrecorder_setchannelcount_emS(to_unsafe, LibC::UInt.new(channel_count))
+    end
+    # Get the number of channels used by this recorder
+    #
+    # Currently only mono and stereo are supported, so the
+    # value is either 1 (for mono) or 2 (for stereo).
+    #
+    # *Returns:* Number of channels
+    #
+    # *See also:* setChannelCount
+    def channel_count() : UInt32
+      VoidCSFML.soundrecorder_getchannelcount(to_unsafe, out result)
+      return result
+    end
     # Check if the system supports audio capture
     #
     # This function should always be called before using
@@ -1669,7 +1721,7 @@ module SF
     # Default constructor
     #
     # This constructor is only meant to be called by derived classes.
-    def initialize()
+    protected def initialize()
       @_soundrecorder = uninitialized VoidCSFML::SoundRecorder_Buffer
       raise "Unexpected memory layout" if as(Void*) + sizeof(LibC::Int) != to_unsafe
       VoidCSFML.soundrecorder_initialize(to_unsafe)
@@ -1770,12 +1822,16 @@ module SF
   #
   # *See also:* `SF::SoundRecorder`
   class SoundBufferRecorder < SoundRecorder
-    @_soundbufferrecorder : VoidCSFML::SoundBufferRecorder_Buffer = VoidCSFML::SoundBufferRecorder_Buffer.new(0u8)
+    @_soundbufferrecorder : VoidCSFML::SoundBufferRecorder_Buffer
     def initialize()
       @_soundrecorder = uninitialized VoidCSFML::SoundRecorder_Buffer
       @_soundbufferrecorder = uninitialized VoidCSFML::SoundBufferRecorder_Buffer
       VoidCSFML.soundbufferrecorder_initialize(to_unsafe)
     end
+    # destructor
+    def finalize()
+      VoidCSFML.soundbufferrecorder_finalize(to_unsafe)
+    end
     # Get the sound buffer containing the captured audio data
     #
     # The sound buffer is valid only after the capture has ended.
@@ -1839,6 +1895,15 @@ module SF
       return String.new(result)
     end
     # :nodoc:
+    def channel_count=(channel_count : Int)
+      VoidCSFML.soundbufferrecorder_setchannelcount_emS(to_unsafe, LibC::UInt.new(channel_count))
+    end
+    # :nodoc:
+    def channel_count() : UInt32
+      VoidCSFML.soundbufferrecorder_getchannelcount(to_unsafe, out result)
+      return result
+    end
+    # :nodoc:
     def self.available?() : Bool
       VoidCSFML.soundbufferrecorder_isavailable(out result)
       return result
@@ -1855,9 +1920,10 @@ module SF
       to_s(io)
     end
   end
-  #:nodoc:
+  # :nodoc:
   class SoundBuffer::Reference < SoundBuffer
     def initialize(@this : Void*, @parent : SoundBufferRecorder)
+      @_soundbuffer = uninitialized VoidCSFML::SoundBuffer_Buffer
     end
     def finalize()
     end

src/common.cr

@@ -1,8 +1,8 @@
 require "./sizes"
 
 module SF
-  VERSION = "2.3.10"
-  SFML_VERSION = "2.3.2"
+  VERSION = "2.4.0"
+  SFML_VERSION = "2.4.0"
 
   # Raised in shorthand class methods if initialization or resource loading fails
   class InitError < Exception