sfml3-rb 0.2.2 → 0.3.1

data/ext/audio/sound.c

@@ -33,15 +33,29 @@ static void* Sound_destroy_without_gvl(void* handle) {
 static void Sound_free(void* ptr) {
     Sound* sound = ptr;
 
+    /* Destroy (which blocks until CSFML guarantees no in-flight audio-thread
+       callback still references this source) before releasing the effect
+       slot, not after: releasing first opens a window where another Ruby
+       thread's effect_processor_acquire could reuse the slot number for an
+       unrelated new source while this source's callback might still be
+       executing against it. */
+    if (sound->source.handle != NULL) {
+        rb_thread_call_without_gvl(Sound_destroy_without_gvl, sound->source.handle, RUBY_UBF_IO,
+                                   NULL);
+    }
+
     effect_processor_release(sound->source.effect_slot);
-    rb_thread_call_without_gvl(Sound_destroy_without_gvl, sound->source.handle, RUBY_UBF_IO, NULL);
     free(sound);
 }
 
+/* Deliberately no RUBY_TYPED_FREE_IMMEDIATELY: Sound_free releases the GVL for
+   sfSound_destroy, and freeing during GC (which the flag requests) would let
+   another thread allocate while GC is mid-cycle, which Ruby aborts on as
+   "object allocation during garbage collection phase". Deferred finalization
+   runs the same free with the GVL held and no GC in progress. */
 static const rb_data_type_t Sound_data_type = {
     .wrap_struct_name = "SFML::Sound",
-    .function = {.dmark = Sound_mark, .dfree = Sound_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
+    .function = {.dmark = Sound_mark, .dfree = Sound_free, .dsize = NULL}};
 
 static VALUE Sound_wrap(VALUE klass, sfSound* handle, VALUE rb_buffer) {
     Sound* ptr;
@@ -58,14 +72,61 @@ static VALUE Sound_wrap(VALUE klass, sfSound* handle, VALUE rb_buffer) {
     return TypedData_Wrap_Struct(klass, &Sound_data_type, ptr);
 }
 
-static VALUE Sound_new(VALUE klass, VALUE rb_buffer) {
+static VALUE Sound_initialize_copy(VALUE self, VALUE other) {
+    (void)other;
+    rb_raise(rb_eTypeError, "can't copy a %s", rb_obj_classname(self));
+}
+
+static VALUE Sound_alloc(VALUE klass) {
+    Sound* ptr = malloc(sizeof(Sound));
+
+    if (ptr == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate sound");
+    }
+
+    ptr->source.handle = NULL;
+    ptr->source.effect_slot = -1;
+    ptr->rb_buffer = Qnil;
+
+    return TypedData_Wrap_Struct(klass, &Sound_data_type, ptr);
+}
+
+/* call-seq:
+ *   Sound.new(buffer) -> Sound
+ *
+ * Creates a sound that plays the given buffer.
+ *
+ * @return [Sound]
+ * @raise [ArgumentError] if +buffer+ is not a SoundBuffer
+ */
+static VALUE Sound_initialize(VALUE self, VALUE rb_buffer) {
+    Sound* sound;
+    sfSound* handle;
+
     if (!rb_obj_is_kind_of(rb_buffer, Get_Klass_SoundBuffer())) {
         raise_invalid_argument_class(Get_Klass_SoundBuffer());
     }
 
-    return Sound_wrap(klass, sfSound_create(Get_SoundBuffer_Struct(rb_buffer)), rb_buffer);
+    sound = (Sound*)Get_Sound_Struct(self);
+
+    handle = sfSound_create(Get_SoundBuffer_Struct(rb_buffer));
+
+    if (handle == NULL) {
+        rb_raise(rb_eRuntimeError, "failed to create sound");
+    }
+
+    sound->source.handle = handle;
+    sound->rb_buffer = rb_buffer;
+
+    return self;
 }
 
+/* call-seq: copy -> Sound
+ *
+ * Creates an independent copy of the sound that shares its buffer.
+ *
+ * @return [Sound] an independent copy that shares the same SoundBuffer
+ */
 static VALUE Sound_copy(VALUE self) {
     Sound* sound = (Sound*)Get_Sound_Struct(self);
 
@@ -73,6 +134,12 @@ static VALUE Sound_copy(VALUE self) {
                       sound->rb_buffer);
 }
 
+/* call-seq: buffer -> SoundBuffer
+ *
+ * Returns the buffer currently attached to this sound.
+ *
+ * @return [SoundBuffer] the buffer currently attached to this sound
+ */
 static VALUE Sound_get_buffer(VALUE self) {
     return ((Sound*)Get_Sound_Struct(self))->rb_buffer;
 }
@@ -93,6 +160,16 @@ static void* Sound_set_buffer_without_gvl(void* raw) {
     return NULL;
 }
 
+/* call-seq:
+ *   buffer=(value) -> SoundBuffer
+ *
+ * Attaches a new SoundBuffer. If a buffer is already attached and the sound
+ * is playing, it is stopped first, which may briefly block the calling
+ * thread (see #stop).
+ *
+ * @return [SoundBuffer] +value+
+ * @raise [ArgumentError] if +value+ is not a SoundBuffer
+ */
 static VALUE Sound_set_buffer(VALUE self, VALUE rb_buffer) {
     Sound* sound = (Sound*)Get_Sound_Struct(self);
     SoundSetBufferArgs args;
@@ -116,10 +193,142 @@ static VALUE Sound_set_buffer(VALUE self, VALUE rb_buffer) {
 #undef SS_FN
 #undef SS_METHOD
 
-void Init_Sound(VALUE rb_module) {
-    rb_cSound = rb_define_class_under(rb_module, "Sound", rb_cObject);
-
-    rb_define_singleton_method(rb_cSound, "new", Sound_new, 1);
+/* Document-class: SFML::Sound
+ * A sound playing directly from a SoundBuffer held fully in memory. Suited
+ * to short effects; for long files prefer Music, which streams instead.
+ *
+ * @!method play
+ *   Starts playback, or resumes it when paused.
+ *   @return [self]
+ * @!method pause
+ *   Pauses playback, keeping the current playing offset.
+ *   @return [self]
+ * @!method stop
+ *   Stops playback and rewinds to the beginning. May briefly block the
+ *   calling thread if an audio-thread callback for this source is in
+ *   flight.
+ *   @return [self]
+ * @!method status
+ *   Returns the current playback status.
+ *   @return [Symbol] one of +:stopped+, +:paused+, +:playing+
+ * @!method looping?
+ *   Returns +true+ if playback loops back to the start on completion.
+ *   @return [Boolean]
+ * @!method looping=(value)
+ *   Enables or disables looping.
+ *   @return [Boolean]
+ * @!method pitch
+ *   Returns the pitch scaling factor.
+ *   @return [Float]
+ * @!method pitch=(value)
+ *   Sets the pitch scaling factor.
+ *   @return [Float]
+ * @!method pan
+ *   Returns the source's stereo pan.
+ *   @return [Float] stereo pan, -1 (left) to 1 (right)
+ * @!method pan=(value)
+ *   Sets the source's stereo pan.
+ *   @return [Float]
+ * @!method volume
+ *   Returns the source's volume.
+ *   @return [Float] 0 to 100
+ * @!method volume=(value)
+ *   Sets the source's volume.
+ *   @return [Float]
+ * @!method spatialization_enabled?
+ *   Returns +true+ if 3D spatialization is enabled.
+ *   @return [Boolean]
+ * @!method spatialization_enabled=(value)
+ *   Enables or disables 3D spatialization.
+ *   @return [Boolean]
+ * @!method position
+ *   Returns the source's position in 3D space.
+ *   @return [Vector3]
+ * @!method position=(value)
+ *   Sets the source's position in 3D space.
+ *   @return [Vector3]
+ * @!method direction
+ *   Returns the direction the source is facing.
+ *   @return [Vector3]
+ * @!method direction=(value)
+ *   Sets the direction the source is facing.
+ *   @return [Vector3]
+ * @!method velocity
+ *   Returns the source's velocity, used for Doppler calculations.
+ *   @return [Vector3]
+ * @!method velocity=(value)
+ *   Sets the source's velocity for Doppler calculations.
+ *   @return [Vector3]
+ * @!method cone
+ *   Returns the source's directional attenuation cone.
+ *   @return [SoundSourceCone]
+ * @!method cone=(value)
+ *   Sets the source's directional attenuation cone.
+ *   @return [SoundSourceCone]
+ * @!method doppler_factor
+ *   Returns the factor by which the Doppler effect is scaled.
+ *   @return [Float]
+ * @!method doppler_factor=(value)
+ *   Sets the factor by which the Doppler effect is scaled.
+ *   @return [Float]
+ * @!method directional_attenuation_factor
+ *   Returns the factor controlling directional attenuation.
+ *   @return [Float]
+ * @!method directional_attenuation_factor=(value)
+ *   Sets the factor controlling directional attenuation.
+ *   @return [Float]
+ * @!method relative_to_listener?
+ *   Returns +true+ if the source is positioned relative to the listener.
+ *   @return [Boolean]
+ * @!method relative_to_listener=(value)
+ *   Makes the source relative to, or independent of, the listener.
+ *   @return [Boolean]
+ * @!method min_distance
+ *   Returns the minimum distance of the distance-attenuation model.
+ *   @return [Float]
+ * @!method min_distance=(value)
+ *   Sets the minimum distance of the distance-attenuation model.
+ *   @return [Float]
+ * @!method max_distance
+ *   Returns the maximum distance of the distance-attenuation model.
+ *   @return [Float]
+ * @!method max_distance=(value)
+ *   Sets the maximum distance of the distance-attenuation model.
+ *   @return [Float]
+ * @!method min_gain
+ *   Returns the minimum gain of the distance-attenuation model.
+ *   @return [Float]
+ * @!method min_gain=(value)
+ *   Sets the minimum gain of the distance-attenuation model.
+ *   @return [Float]
+ * @!method max_gain
+ *   Returns the maximum gain of the distance-attenuation model.
+ *   @return [Float]
+ * @!method max_gain=(value)
+ *   Sets the maximum gain of the distance-attenuation model.
+ *   @return [Float]
+ * @!method attenuation
+ *   Returns the distance-attenuation factor.
+ *   @return [Float]
+ * @!method attenuation=(value)
+ *   Sets the distance-attenuation factor.
+ *   @return [Float]
+ * @!method playing_offset
+ *   Returns the current playing offset.
+ *   @return [Time]
+ * @!method playing_offset=(value)
+ *   Seeks to the given playing offset.
+ *   @return [Time]
+ * @!method effect_processor=(proc)
+ *   Installs a Proc that post-processes this source's audio in real time.
+ *   @return [Proc] +proc+
+ */
+void Init_Sound(VALUE rb_mSFML) {
+    rb_cSound = rb_define_class_under(rb_mSFML, "Sound", rb_cObject);
+
+    rb_define_alloc_func(rb_cSound, Sound_alloc);
+    rb_define_method(rb_cSound, "initialize", Sound_initialize, 1);
+    rb_define_private_method(rb_cSound, "initialize_copy", Sound_initialize_copy, 1);
 
     rb_define_method(rb_cSound, "copy", Sound_copy, 0);
     rb_define_method(rb_cSound, "buffer", Sound_get_buffer, 0);

data/ext/audio/sound_buffer.c

@@ -12,14 +12,14 @@
 #include "system/time.h"
 
 typedef struct {
-    sfSoundBuffer *buffer;
+    sfSoundBuffer* buffer;
     bool owns;
 } SoundBuffer;
 
 static VALUE rb_cSoundBuffer;
 
-static void SoundBuffer_free(void *ptr) {
-    SoundBuffer *sound_buffer = ptr;
+static void SoundBuffer_free(void* ptr) {
+    SoundBuffer* sound_buffer = ptr;
 
     if (sound_buffer->owns) {
         sfSoundBuffer_destroy(sound_buffer->buffer);
@@ -31,11 +31,10 @@ static void SoundBuffer_free(void *ptr) {
 static const rb_data_type_t SoundBuffer_data_type = {
     .wrap_struct_name = "SFML::SoundBuffer",
     .function = {.dmark = NULL, .dfree = SoundBuffer_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE SoundBuffer_wrap(VALUE klass, sfSoundBuffer *buffer) {
-    SoundBuffer *ptr;
+static VALUE SoundBuffer_wrap(VALUE klass, sfSoundBuffer* buffer) {
+    SoundBuffer* ptr;
 
     if (buffer == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create sound buffer");
@@ -48,36 +47,60 @@ static VALUE SoundBuffer_wrap(VALUE klass, sfSoundBuffer *buffer) {
     return TypedData_Wrap_Struct(klass, &SoundBuffer_data_type, ptr);
 }
 
-VALUE sound_buffer_from_borrowed(const sfSoundBuffer *buffer) {
-    SoundBuffer *ptr;
+VALUE sound_buffer_from_borrowed(const sfSoundBuffer* buffer) {
+    SoundBuffer* ptr;
 
     if (buffer == NULL) {
         return Qnil;
     }
 
     ptr = malloc(sizeof(SoundBuffer));
-    ptr->buffer = (sfSoundBuffer *) buffer;
+    ptr->buffer = (sfSoundBuffer*)buffer;
     ptr->owns = false;
 
     return TypedData_Wrap_Struct(rb_cSoundBuffer, &SoundBuffer_data_type, ptr);
 }
 
+/* call-seq:
+ *   SoundBuffer.from_file(path) -> SoundBuffer
+ *
+ * Loads and decodes an audio file into a buffer.
+ *
+ * @return [SoundBuffer]
+ * @raise [RuntimeError] if the file cannot be opened or decoded
+ */
 static VALUE SoundBuffer_from_file(VALUE klass, VALUE rb_path) {
     return SoundBuffer_wrap(klass, sfSoundBuffer_createFromFile(StringValueCStr(rb_path)));
 }
 
+/* call-seq:
+ *   SoundBuffer.from_memory(data) -> SoundBuffer
+ *
+ * Decodes audio held in a String into a buffer.
+ *
+ * @return [SoundBuffer]
+ * @raise [RuntimeError] if +data+ cannot be decoded
+ */
 static VALUE SoundBuffer_from_memory(VALUE klass, VALUE rb_data) {
     StringValue(rb_data);
 
-    return SoundBuffer_wrap(klass, sfSoundBuffer_createFromMemory(RSTRING_PTR(rb_data),
-                                                                  (size_t) RSTRING_LEN(rb_data)));
+    return SoundBuffer_wrap(
+        klass, sfSoundBuffer_createFromMemory(RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data)));
 }
 
+/* call-seq:
+ *   SoundBuffer.from_stream(stream) -> SoundBuffer
+ *
+ * Decodes audio read from an SFML InputStream into a buffer.
+ *
+ * @return [SoundBuffer]
+ * @raise [RuntimeError] if the stream cannot be decoded
+ */
 static VALUE SoundBuffer_from_stream(VALUE klass, VALUE rb_stream) {
     VALUE holder = Qnil;
-    sfInputStream *stream = input_stream_from_rb(rb_stream, &holder);
+    sfInputStream* stream = input_stream_from_rb(rb_stream, &holder);
 
-    (void) holder;
+    (void)holder;
 
     return SoundBuffer_wrap(klass, sfSoundBuffer_createFromStream(stream));
 }
@@ -85,12 +108,13 @@ static VALUE SoundBuffer_from_stream(VALUE klass, VALUE rb_stream) {
 /* SFML rejects a buffer whose channel map does not have exactly one entry per
    channel, so an omitted map is filled with the conventional layout for 1 and
    2 channels and left Unspecified beyond that. */
-static void SoundBuffer_default_channel_map(unsigned int channel_count, sfSoundChannel *map) {
+static void SoundBuffer_default_channel_map(unsigned int channel_count, sfSoundChannel* map) {
     static const sfSoundChannel surround[] = {
-        sfSoundChannelFrontLeft,      sfSoundChannelFrontRight,     sfSoundChannelFrontCenter,
-        sfSoundChannelLowFrequencyEffects, sfSoundChannelBackLeft,  sfSoundChannelBackRight,
-        sfSoundChannelSideLeft,       sfSoundChannelSideRight,      sfSoundChannelTopCenter
-    };
+        sfSoundChannelFrontLeft,   sfSoundChannelFrontRight,
+        sfSoundChannelFrontCenter, sfSoundChannelLowFrequencyEffects,
+        sfSoundChannelBackLeft,    sfSoundChannelBackRight,
+        sfSoundChannelSideLeft,    sfSoundChannelSideRight,
+        sfSoundChannelTopCenter};
     unsigned int i;
 
     for (i = 0; i < channel_count; i++) {
@@ -106,28 +130,76 @@ static void SoundBuffer_default_channel_map(unsigned int channel_count, sfSoundC
     }
 }
 
+typedef struct {
+    sfSoundChannel* channel_map;
+    VALUE rb_channel_map;
+    unsigned int channel_count;
+} ChannelMapFillContext;
+
+/* sound_channel_from_rb raises ArgumentError on an unrecognized entry; run
+   through rb_protect so the caller can free the samples/channel_map buffers
+   (already allocated by this point) before that exception propagates,
+   instead of leaking them. */
+static VALUE SoundBuffer_fill_channel_map(VALUE raw) {
+    ChannelMapFillContext* ctx = (ChannelMapFillContext*)raw;
+    long i;
+
+    for (i = 0; i < (long)ctx->channel_count; i++) {
+        ctx->channel_map[i] = sound_channel_from_rb(rb_ary_entry(ctx->rb_channel_map, i));
+    }
+
+    return Qnil;
+}
+
 /* Copies the samples into a contiguous int16 buffer: an Array is converted
-   element by element, a String is memcpy'd out of (possibly unaligned) Ruby
-   storage. The channel map, when given, is translated symbol by symbol. */
-static VALUE SoundBuffer_from_samples(int argc, VALUE *argv, VALUE klass) {
+   element by element, and a String's packed int16 samples are copied out of
+   the (possibly unaligned) Ruby storage. The channel map, when given, is
+   translated symbol by symbol. */
+/* call-seq:
+ *   SoundBuffer.from_samples(samples, channel_count, sample_rate)              -> SoundBuffer
+ *   SoundBuffer.from_samples(samples, channel_count, sample_rate, channel_map) -> SoundBuffer
+ *
+ * +samples+ is an Array of Integer samples or a packed String of int16
+ * samples, interleaved by channel. +channel_map+, if given, is an Array of
+ * channel Symbols (see SoundChannel), one per channel; if omitted, a
+ * conventional layout is assumed for 1 and 2 channels.
+ *
+ * @return [SoundBuffer]
+ * @raise [ArgumentError] if +channel_count+ is 0, +samples+ is neither an
+ *   Array nor a String, or +channel_map+ doesn't have exactly one entry per
+ *   channel
+ */
+static VALUE SoundBuffer_from_samples(int argc, VALUE* argv, VALUE klass) {
     VALUE rb_samples, rb_channel_count, rb_sample_rate, rb_channel_map;
-    int16_t *samples;
-    sfSoundChannel *channel_map;
+    int16_t* samples;
+    sfSoundChannel* channel_map;
     unsigned int channel_count;
     uint64_t sample_count;
-    sfSoundBuffer *buffer;
+    sfSoundBuffer* buffer;
 
     rb_scan_args(argc, argv, "31", &rb_samples, &rb_channel_count, &rb_sample_rate,
                  &rb_channel_map);
 
-    channel_count = (unsigned int) NUM2INT(rb_channel_count);
+    channel_count = (unsigned int)NUM2INT(rb_channel_count);
 
     if (channel_count == 0) {
         rb_raise(rb_eArgError, "channel count must be positive");
     }
 
+    /* channel_map's malloc below (sizeof(sfSoundChannel) * channel_count) can
+       wrap on the 32-bit targets this gem ships if channel_count is large
+       enough, allocating far less than the subsequent write loop assumes.
+       Check before any allocation happens, so there's nothing to clean up on
+       the raise path. (Written with channel_count as the divisor, not
+       compared directly against a constant bound, so this isn't optimized
+       away as tautological on 64-bit hosts where it can't actually trigger
+       -- it still does real work on the 32-bit targets.) */
+    if (SIZE_MAX / channel_count < sizeof(sfSoundChannel)) {
+        rb_raise(rb_eArgError, "channel count too large");
+    }
+
     if (RB_TYPE_P(rb_samples, T_STRING)) {
-        size_t bytes = (size_t) RSTRING_LEN(rb_samples);
+        size_t bytes = (size_t)RSTRING_LEN(rb_samples);
 
         if (bytes % sizeof(int16_t) != 0) {
             rb_raise(rb_eArgError, "sample string length must be a multiple of 2 bytes");
@@ -137,16 +209,21 @@ static VALUE SoundBuffer_from_samples(int argc, VALUE *argv, VALUE klass) {
         samples = malloc(bytes > 0 ? bytes : 1);
 
         if (bytes > 0) {
-            memcpy(samples, RSTRING_PTR(rb_samples), bytes);
+            const int16_t* src = (const int16_t*)RSTRING_PTR(rb_samples);
+            size_t i;
+
+            for (i = 0; i < sample_count; i++) {
+                samples[i] = src[i];
+            }
         }
     } else if (RB_TYPE_P(rb_samples, T_ARRAY)) {
         long i;
 
-        sample_count = (uint64_t) RARRAY_LEN(rb_samples);
-        samples = malloc(sizeof(int16_t) * ((size_t) sample_count + 1));
+        sample_count = (uint64_t)RARRAY_LEN(rb_samples);
+        samples = malloc(sizeof(int16_t) * ((size_t)sample_count + 1));
 
-        for (i = 0; i < (long) sample_count; i++) {
-            samples[i] = (int16_t) NUM2INT(rb_ary_entry(rb_samples, i));
+        for (i = 0; i < (long)sample_count; i++) {
+            samples[i] = (int16_t)NUM2INT(rb_ary_entry(rb_samples, i));
         }
     } else {
         rb_raise(rb_eArgError, "samples must be an Array of integers or a String");
@@ -158,23 +235,30 @@ static VALUE SoundBuffer_from_samples(int argc, VALUE *argv, VALUE klass) {
     if (NIL_P(rb_channel_map)) {
         SoundBuffer_default_channel_map(channel_count, channel_map);
     } else {
-        long i;
+        ChannelMapFillContext ctx = {.channel_map = channel_map,
+                                     .rb_channel_map = rb_channel_map,
+                                     .channel_count = channel_count};
+        int state = 0;
 
         if (!RB_TYPE_P(rb_channel_map, T_ARRAY) ||
-            (unsigned long) RARRAY_LEN(rb_channel_map) != channel_count) {
+            (unsigned long)RARRAY_LEN(rb_channel_map) != channel_count) {
             free(samples);
             free(channel_map);
             rb_raise(rb_eArgError, "channel map must have exactly one entry per channel");
         }
 
-        for (i = 0; i < (long) channel_count; i++) {
-            channel_map[i] = sound_channel_from_rb(rb_ary_entry(rb_channel_map, i));
+        rb_protect(SoundBuffer_fill_channel_map, (VALUE)&ctx, &state);
+
+        if (state) {
+            free(samples);
+            free(channel_map);
+            rb_jump_tag(state);
         }
     }
 
     buffer = sfSoundBuffer_createFromSamples(samples, sample_count, channel_count,
-                                              (unsigned int) NUM2INT(rb_sample_rate), channel_map,
-                                              channel_count);
+                                             (unsigned int)NUM2INT(rb_sample_rate), channel_map,
+                                             channel_count);
 
     free(samples);
     free(channel_map);
@@ -182,17 +266,38 @@ static VALUE SoundBuffer_from_samples(int argc, VALUE *argv, VALUE klass) {
     return SoundBuffer_wrap(klass, buffer);
 }
 
+/* call-seq: copy -> SoundBuffer
+ *
+ * Creates an independent copy of the buffer.
+ *
+ * @return [SoundBuffer] an independent copy
+ */
 static VALUE SoundBuffer_copy(VALUE self) {
     return SoundBuffer_wrap(Get_Klass_SoundBuffer(),
                             sfSoundBuffer_copy(Get_SoundBuffer_Struct(self)));
 }
 
+/* call-seq:
+ *   save_to_file(path) -> true or false
+ *
+ * Writes the buffer to an audio file.
+ *
+ * @return [Boolean] whether the file was written successfully
+ */
 static VALUE SoundBuffer_save_to_file(VALUE self, VALUE rb_path) {
-    return BOOL2RB(sfSoundBuffer_saveToFile(Get_SoundBuffer_Struct(self), StringValueCStr(rb_path)));
+    return BOOL2RB(
+        sfSoundBuffer_saveToFile(Get_SoundBuffer_Struct(self), StringValueCStr(rb_path)));
 }
 
+/* call-seq: samples -> Array<Integer>
+ *
+ * Returns the buffer's raw audio samples as Integers.
+ *
+ * @return [Array<Integer>] the raw int16 audio samples, interleaved by
+ *   channel
+ */
 static VALUE SoundBuffer_samples(VALUE self) {
-    const int16_t *samples = sfSoundBuffer_getSamples(Get_SoundBuffer_Struct(self));
+    const int16_t* samples = sfSoundBuffer_getSamples(Get_SoundBuffer_Struct(self));
     uint64_t count = sfSoundBuffer_getSampleCount(Get_SoundBuffer_Struct(self));
     VALUE rb_array;
     uint64_t i;
@@ -201,7 +306,7 @@ static VALUE SoundBuffer_samples(VALUE self) {
         return rb_ary_new();
     }
 
-    rb_array = rb_ary_new_capa((long) count);
+    rb_array = rb_ary_new_capa((long)count);
 
     for (i = 0; i < count; i++) {
         rb_ary_push(rb_array, INT2NUM(samples[i]));
@@ -210,21 +315,46 @@ static VALUE SoundBuffer_samples(VALUE self) {
     return rb_array;
 }
 
+/* call-seq: sample_count -> Integer
+ *
+ * Returns the total number of samples stored in the buffer.
+ *
+ * @return [Integer] total number of int16 samples, across all channels
+ */
 static VALUE SoundBuffer_sample_count(VALUE self) {
     return ULL2NUM(sfSoundBuffer_getSampleCount(Get_SoundBuffer_Struct(self)));
 }
 
+/* call-seq: sample_rate -> Integer
+ *
+ * Returns the buffer's sample rate in samples per second.
+ *
+ * @return [Integer]
+ */
 static VALUE SoundBuffer_sample_rate(VALUE self) {
     return UINT2NUM(sfSoundBuffer_getSampleRate(Get_SoundBuffer_Struct(self)));
 }
 
+/* call-seq: channel_count -> Integer
+ *
+ * Returns the number of audio channels in the buffer.
+ *
+ * @return [Integer]
+ */
 static VALUE SoundBuffer_channel_count(VALUE self) {
     return UINT2NUM(sfSoundBuffer_getChannelCount(Get_SoundBuffer_Struct(self)));
 }
 
+/* call-seq: channel_map -> Array<Symbol>
+ *
+ * Returns the channel layout of the buffer.
+ *
+ * @return [Array<Symbol>] one entry per channel, e.g.
+ *   +[:front_left, :front_right]+
+ */
 static VALUE SoundBuffer_channel_map(VALUE self) {
     size_t count = 0;
-    sfSoundChannel *map = sfSoundBuffer_getChannelMap(Get_SoundBuffer_Struct(self), &count);
+    sfSoundChannel* map = sfSoundBuffer_getChannelMap(Get_SoundBuffer_Struct(self), &count);
     VALUE rb_array;
     size_t i;
 
@@ -232,7 +362,7 @@ static VALUE SoundBuffer_channel_map(VALUE self) {
         return rb_ary_new();
     }
 
-    rb_array = rb_ary_new_capa((long) count);
+    rb_array = rb_ary_new_capa((long)count);
 
     for (i = 0; i < count; i++) {
         rb_ary_push(rb_array, ID2SYM(rb_intern(sound_channel_name(map[i]))));
@@ -241,12 +371,32 @@ static VALUE SoundBuffer_channel_map(VALUE self) {
     return rb_array;
 }
 
+/* call-seq: duration -> Time
+ *
+ * Returns the buffer's total playing duration.
+ *
+ * @return [Time]
+ */
 static VALUE SoundBuffer_duration(VALUE self) {
     return time_to_rb(sfSoundBuffer_getDuration(Get_SoundBuffer_Struct(self)));
 }
 
-void Init_SoundBuffer(VALUE rb_module) {
-    rb_cSoundBuffer = rb_define_class_under(rb_module, "SoundBuffer", rb_cObject);
+static VALUE SoundBuffer_alloc(VALUE klass) {
+    (void)klass;
+    rb_raise(rb_eNotImpError,
+             "use SoundBuffer.from_file, SoundBuffer.from_memory, SoundBuffer.from_stream or "
+             "SoundBuffer.from_samples");
+}
+
+/* Document-class: SFML::SoundBuffer
+ * Audio samples held fully decoded in memory, ready to be played through one
+ * or more Sound instances (a single buffer may back several simultaneous
+ * Sounds). For long audio, prefer Music, which streams instead of loading
+ * everything up front.
+ */
+void Init_SoundBuffer(VALUE rb_mSFML) {
+    rb_cSoundBuffer = rb_define_class_under(rb_mSFML, "SoundBuffer", rb_cObject);
+    rb_define_alloc_func(rb_cSoundBuffer, SoundBuffer_alloc);
 
     rb_define_singleton_method(rb_cSoundBuffer, "from_file", SoundBuffer_from_file, 1);
     rb_define_singleton_method(rb_cSoundBuffer, "from_memory", SoundBuffer_from_memory, 1);
@@ -267,8 +417,8 @@ VALUE Get_Klass_SoundBuffer(void) {
     return rb_cSoundBuffer;
 }
 
-void *Get_SoundBuffer_Struct(VALUE self) {
-    SoundBuffer *ptr;
+void* Get_SoundBuffer_Struct(VALUE self) {
+    SoundBuffer* ptr;
     TypedData_Get_Struct(self, SoundBuffer, &SoundBuffer_data_type, ptr);
     return ptr->buffer;
 }