sfml3-rb 0.2.2 → 0.3.0

data/ext/audio/sound_recorder.c

@@ -1,33 +1,48 @@
 #include "audio/sound_recorder.h"
 
 #include <ruby.h>
-#include <ruby/thread.h>
 #include <stdint.h>
 #include <stdlib.h>
 
 #include "audio/audio_enums.h"
+#include "core/foreign_thread.h"
 #include "core/macros.h"
 
-/* A subclassable recorder. The capture callbacks arrive on SFML's audio
-   thread, so each re-enters Ruby through rb_thread_call_with_gvl and treats an
-   exception as "stop capturing" instead of unwinding into the audio engine.
-   A subclass only has to implement #on_process; #on_start and #on_stop are
-   optional and default to continuing. */
+/* A subclassable recorder. The capture callbacks arrive on SFML's capture
+   thread -- a real OS thread never created by Ruby, exactly like the audio
+   playback thread effect_processor.c/sound_stream.c are built to handle --
+   so re-entering Ruby directly (e.g. via rb_thread_call_with_gvl, as this
+   file previously did for #on_process, or via rb_protect with no GVL
+   handling at all, as it previously did for #on_start/#on_stop) is a fatal
+   VM error. Every callback here instead posts its work to the shared
+   foreign-thread worker (core/foreign_thread.h), the same mechanism the
+   other two files use, and treats an exception as "stop capturing" rather
+   than unwinding into the audio engine. A subclass only has to implement
+   #on_process; #on_start and #on_stop are optional and default to
+   continuing. */
+
+#define SOUND_RECORDER_JOB_TIMEOUT_MS 50
 typedef struct {
     VALUE rb_self;
-    sfSoundRecorder *handle;
+    sfSoundRecorder* handle;
 } SoundRecorder;
 
 static VALUE rb_cSoundRecorder;
 
-static void SoundRecorder_mark(void *ptr) {
-    SoundRecorder *recorder = ptr;
+/* CSFML reports "no such device" as NULL; that is an absent name, not an
+   error, so it maps to nil rather than raising out of rb_str_new_cstr. */
+static VALUE SoundRecorder_nullable_string(const char* value) {
+    return value == NULL ? Qnil : rb_str_new_cstr(value);
+}
+
+static void SoundRecorder_mark(void* ptr) {
+    SoundRecorder* recorder = ptr;
 
     rb_gc_mark(recorder->rb_self);
 }
 
-static void SoundRecorder_free(void *ptr) {
-    SoundRecorder *recorder = ptr;
+static void SoundRecorder_free(void* ptr) {
+    SoundRecorder* recorder = ptr;
 
     if (recorder->handle != NULL) {
         sfSoundRecorder_destroy(recorder->handle);
@@ -39,8 +54,7 @@ static void SoundRecorder_free(void *ptr) {
 static const rb_data_type_t SoundRecorder_data_type = {
     .wrap_struct_name = "SFML::SoundRecorder",
     .function = {.dmark = SoundRecorder_mark, .dfree = SoundRecorder_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 typedef struct {
     VALUE self;
@@ -48,25 +62,31 @@ typedef struct {
 } InvokeContext;
 
 static VALUE SoundRecorder_invoke_body(VALUE raw) {
-    InvokeContext *ctx = (InvokeContext *) raw;
+    InvokeContext* ctx = (InvokeContext*)raw;
 
     return rb_funcall(ctx->self, ctx->method, 0);
 }
 
-/* Calls a zero-argument Ruby method, swallowing any exception it raises. */
-static void SoundRecorder_invoke(VALUE self, ID method) {
-    InvokeContext ctx = {.self = self, .method = method};
+/* Runs on the shared foreign-thread worker, which holds the GVL. */
+static void SoundRecorder_invoke_run(void* raw) {
     int state = 0;
 
-    rb_protect(SoundRecorder_invoke_body, (VALUE) &ctx, &state);
+    rb_protect(SoundRecorder_invoke_body, (VALUE)raw, &state);
 
     if (state) {
         rb_set_errinfo(Qnil);
     }
 }
 
-static bool SoundRecorder_on_start(void *userData) {
-    SoundRecorder *recorder = userData;
+/* Calls a zero-argument Ruby method, swallowing any exception it raises. */
+static void SoundRecorder_invoke(VALUE self, ID method) {
+    InvokeContext ctx = {.self = self, .method = method};
+
+    run_on_ruby_thread(SoundRecorder_invoke_run, &ctx, SOUND_RECORDER_JOB_TIMEOUT_MS);
+}
+
+static bool SoundRecorder_on_start(void* userData) {
+    SoundRecorder* recorder = userData;
 
     if (rb_respond_to(recorder->rb_self, rb_intern("on_start"))) {
         SoundRecorder_invoke(recorder->rb_self, rb_intern("on_start"));
@@ -76,15 +96,15 @@ static bool SoundRecorder_on_start(void *userData) {
 }
 
 typedef struct {
-    SoundRecorder *recorder;
-    const int16_t *samples;
+    SoundRecorder* recorder;
+    const int16_t* samples;
     size_t sample_count;
     int ok;
 } ProcessContext;
 
 static VALUE SoundRecorder_process_body(VALUE raw) {
-    ProcessContext *ctx = (ProcessContext *) raw;
-    VALUE rb_samples = rb_ary_new_capa((long) ctx->sample_count);
+    ProcessContext* ctx = (ProcessContext*)raw;
+    VALUE rb_samples = rb_ary_new_capa((long)ctx->sample_count);
     VALUE result;
     size_t i;
 
@@ -98,41 +118,58 @@ static VALUE SoundRecorder_process_body(VALUE raw) {
     return Qnil;
 }
 
-static void *SoundRecorder_process_gvl(void *raw) {
+/* Runs on the shared foreign-thread worker, which holds the GVL. */
+static void SoundRecorder_process_run(void* raw) {
     int state = 0;
 
-    rb_protect(SoundRecorder_process_body, (VALUE) raw, &state);
+    rb_protect(SoundRecorder_process_body, (VALUE)raw, &state);
 
     if (state) {
         rb_set_errinfo(Qnil);
-        ((ProcessContext *) raw)->ok = 0;
+        ((ProcessContext*)raw)->ok = 0;
     }
-
-    return NULL;
 }
 
-static bool SoundRecorder_on_process(const int16_t *samples, size_t sample_count, void *userData) {
-    SoundRecorder *recorder = userData;
+static bool SoundRecorder_on_process(const int16_t* samples, size_t sample_count, void* userData) {
+    SoundRecorder* recorder = userData;
     ProcessContext ctx = {
-        .recorder = recorder, .samples = samples, .sample_count = sample_count, .ok = 0
-    };
-
-    rb_thread_call_with_gvl(SoundRecorder_process_gvl, &ctx);
+        .recorder = recorder, .samples = samples, .sample_count = sample_count, .ok = 0};
+
+    if (!run_on_ruby_thread(SoundRecorder_process_run, &ctx, SOUND_RECORDER_JOB_TIMEOUT_MS)) {
+        /* Timed out before the worker even claimed the job (e.g. GVL
+           contention): drop this one chunk rather than block the capture
+           thread indefinitely, but keep recording rather than aborting the
+           whole session over one missed callback. */
+        return true;
+    }
 
     return ctx.ok ? true : false;
 }
 
-static void SoundRecorder_on_stop(void *userData) {
-    SoundRecorder *recorder = userData;
+static void SoundRecorder_on_stop(void* userData) {
+    SoundRecorder* recorder = userData;
 
     if (rb_respond_to(recorder->rb_self, rb_intern("on_stop"))) {
         SoundRecorder_invoke(recorder->rb_self, rb_intern("on_stop"));
     }
 }
 
+/* call-seq:
+ *   SoundRecorder.new -> SoundRecorder
+ *
+ * SoundRecorder must be subclassed: the subclass is required to implement
+ * +#on_process(samples)+, called from the audio thread with an Array of
+ * captured Integer samples whenever a chunk is ready (return a truthy value
+ * to keep recording, falsy to stop), and may optionally implement
+ * +#on_start+ and +#on_stop+.
+ *
+ * @return [SoundRecorder]
+ * @raise [NotImplementedError] if the subclass does not define #on_process
+ * @raise [RuntimeError] if no capture device is available
+ */
 static VALUE SoundRecorder_new(VALUE klass) {
-    SoundRecorder *ptr;
-    sfSoundRecorder *handle;
+    SoundRecorder* ptr;
+    sfSoundRecorder* handle;
     VALUE self;
 
     ptr = malloc(sizeof(SoundRecorder));
@@ -160,27 +197,59 @@ static VALUE SoundRecorder_new(VALUE klass) {
     return self;
 }
 
+/* call-seq:
+ *   start(sample_rate) -> true or false
+ *
+ * Starts capturing audio at the given sample rate.
+ *
+ * @return [Boolean] whether recording started successfully
+ */
 static VALUE SoundRecorder_start(VALUE self, VALUE rb_sample_rate) {
     return BOOL2RB(sfSoundRecorder_start(Get_SoundRecorder_Struct(self),
-                                         (unsigned int) NUM2INT(rb_sample_rate)));
+                                         (unsigned int)NUM2INT(rb_sample_rate)));
 }
 
+/* call-seq: stop -> self
+ *
+ * Stops capturing audio.
+ *
+ * @return [self]
+ */
 static VALUE SoundRecorder_stop(VALUE self) {
     sfSoundRecorder_stop(Get_SoundRecorder_Struct(self));
     return self;
 }
 
+/* call-seq: sample_rate -> Integer
+ *
+ * Returns the sample rate used for capture.
+ *
+ * @return [Integer]
+ */
 static VALUE SoundRecorder_sample_rate(VALUE self) {
     return UINT2NUM(sfSoundRecorder_getSampleRate(Get_SoundRecorder_Struct(self)));
 }
 
+/* call-seq: SoundRecorder.available? -> true or false
+ *
+ * Returns +true+ if the audio backend supports capture.
+ *
+ * @return [Boolean] whether the audio backend supports capture at all
+ */
 static VALUE SoundRecorder_available(VALUE klass) {
     return BOOL2RB(sfSoundRecorder_isAvailable());
 }
 
+/* call-seq: SoundRecorder.available_devices -> Array<String>
+ *
+ * Returns the names of the capture devices available on this system.
+ *
+ * @return [Array<String>] names of the capture devices available on this
+ *   system
+ */
 static VALUE SoundRecorder_available_devices(VALUE klass) {
     size_t count = 0;
-    const char *const *devices = sfSoundRecorder_getAvailableDevices(&count);
+    const char* const* devices = sfSoundRecorder_getAvailableDevices(&count);
     VALUE rb_array;
     size_t i;
 
@@ -188,7 +257,7 @@ static VALUE SoundRecorder_available_devices(VALUE klass) {
         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, rb_str_new_cstr(devices[i]));
@@ -197,31 +266,74 @@ static VALUE SoundRecorder_available_devices(VALUE klass) {
     return rb_array;
 }
 
+/* call-seq: SoundRecorder.default_device -> String or nil
+ *
+ * Returns the name of the system's default capture device.
+ *
+ * @return [String, nil] the name of the system's default capture device, or
+ *   +nil+ when the system reports none
+ */
 static VALUE SoundRecorder_default_device(VALUE klass) {
-    return rb_str_new_cstr(sfSoundRecorder_getDefaultDevice());
+    return SoundRecorder_nullable_string(sfSoundRecorder_getDefaultDevice());
 }
 
+/* call-seq: device -> String or nil
+ *
+ * Returns the name of the capture device in use.
+ *
+ * @return [String, nil] the name of the capture device in use, or +nil+ when
+ *   the recorder has none
+ */
 static VALUE SoundRecorder_device(VALUE self) {
-    return rb_str_new_cstr(sfSoundRecorder_getDevice(Get_SoundRecorder_Struct(self)));
+    return SoundRecorder_nullable_string(sfSoundRecorder_getDevice(Get_SoundRecorder_Struct(self)));
 }
 
+/* call-seq:
+ *   device=(value) -> true or false
+ *
+ * Must be called while not recording. Get available names from
+ * .available_devices.
+ *
+ * @return [Boolean] whether the device was set successfully
+ */
 static VALUE SoundRecorder_set_device(VALUE self, VALUE rb_name) {
     return BOOL2RB(
         sfSoundRecorder_setDevice(Get_SoundRecorder_Struct(self), StringValueCStr(rb_name)));
 }
 
+/* call-seq: channel_count -> Integer
+ *
+ * Returns the number of capture channels.
+ *
+ * @return [Integer]
+ */
 static VALUE SoundRecorder_channel_count(VALUE self) {
     return UINT2NUM(sfSoundRecorder_getChannelCount(Get_SoundRecorder_Struct(self)));
 }
 
+/* call-seq:
+ *   channel_count=(value) -> Integer
+ *
+ * Must be called while not recording.
+ *
+ * @return [Integer] +value+
+ */
 static VALUE SoundRecorder_set_channel_count(VALUE self, VALUE rb_count) {
-    sfSoundRecorder_setChannelCount(Get_SoundRecorder_Struct(self), (unsigned int) NUM2INT(rb_count));
+    sfSoundRecorder_setChannelCount(Get_SoundRecorder_Struct(self),
+                                    (unsigned int)NUM2INT(rb_count));
     return rb_count;
 }
 
+/* call-seq: channel_map -> Array<Symbol>
+ *
+ * Returns the channel layout of the recorder.
+ *
+ * @return [Array<Symbol>] one entry per channel, e.g.
+ *   +[:front_left, :front_right]+
+ */
 static VALUE SoundRecorder_channel_map(VALUE self) {
     size_t count = 0;
-    sfSoundChannel *map = sfSoundRecorder_getChannelMap(Get_SoundRecorder_Struct(self), &count);
+    sfSoundChannel* map = sfSoundRecorder_getChannelMap(Get_SoundRecorder_Struct(self), &count);
     VALUE rb_array;
     size_t i;
 
@@ -229,7 +341,7 @@ static VALUE SoundRecorder_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]))));
@@ -238,14 +350,22 @@ static VALUE SoundRecorder_channel_map(VALUE self) {
     return rb_array;
 }
 
-void Init_SoundRecorder(VALUE rb_module) {
-    rb_cSoundRecorder = rb_define_class_under(rb_module, "SoundRecorder", rb_cObject);
+/* Document-class: SFML::SoundRecorder
+ * Base class for a custom audio capture consumer. Subclasses must implement
+ * +#on_process(samples)+, called from the audio thread whenever a chunk of
+ * captured samples is ready, and may implement +#on_start+/+#on_stop+ to
+ * react to recording starting/stopping. For simply capturing into a
+ * SoundBuffer without custom processing, use SoundBufferRecorder instead.
+ */
+void Init_SoundRecorder(VALUE rb_mSFML) {
+    rb_cSoundRecorder = rb_define_class_under(rb_mSFML, "SoundRecorder", rb_cObject);
 
     rb_define_singleton_method(rb_cSoundRecorder, "new", SoundRecorder_new, 0);
     rb_define_singleton_method(rb_cSoundRecorder, "available?", SoundRecorder_available, 0);
     rb_define_singleton_method(rb_cSoundRecorder, "available_devices",
                                SoundRecorder_available_devices, 0);
-    rb_define_singleton_method(rb_cSoundRecorder, "default_device", SoundRecorder_default_device, 0);
+    rb_define_singleton_method(rb_cSoundRecorder, "default_device", SoundRecorder_default_device,
+                               0);
 
     rb_define_method(rb_cSoundRecorder, "start", SoundRecorder_start, 1);
     rb_define_method(rb_cSoundRecorder, "stop", SoundRecorder_stop, 0);
@@ -261,8 +381,8 @@ VALUE Get_Klass_SoundRecorder(void) {
     return rb_cSoundRecorder;
 }
 
-void *Get_SoundRecorder_Struct(VALUE self) {
-    SoundRecorder *ptr;
+void* Get_SoundRecorder_Struct(VALUE self) {
+    SoundRecorder* ptr;
     TypedData_Get_Struct(self, SoundRecorder, &SoundRecorder_data_type, ptr);
     return ptr->handle;
 }

data/ext/audio/sound_source_cone.c

@@ -12,84 +12,165 @@ typedef struct {
 
 static VALUE rb_cSoundSourceCone;
 
-static void SoundSourceCone_free(void *ptr) {
+static void SoundSourceCone_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t SoundSourceCone_data_type = {
     .wrap_struct_name = "SFML::SoundSourceCone",
     .function = {.dmark = NULL, .dfree = SoundSourceCone_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 static VALUE SoundSourceCone_wrap(sfSoundSourceCone cone) {
-    SoundSourceCone *ptr = malloc(sizeof(SoundSourceCone));
+    SoundSourceCone* ptr = malloc(sizeof(SoundSourceCone));
 
     ptr->cone = cone;
 
     return TypedData_Wrap_Struct(rb_cSoundSourceCone, &SoundSourceCone_data_type, ptr);
 }
 
+/* call-seq:
+ *   SoundSourceCone.new(inner_angle, outer_angle, outer_gain) -> SoundSourceCone
+ *
+ * Creates a directional attenuation cone with the given angles and gain.
+ *
+ * @return [SoundSourceCone]
+ */
 static VALUE SoundSourceCone_new(VALUE klass, VALUE rb_inner, VALUE rb_outer, VALUE rb_gain) {
-    sfSoundSourceCone cone = {
-        .innerAngle = (float) NUM2DBL(rb_inner),
-        .outerAngle = (float) NUM2DBL(rb_outer),
-        .outerGain = (float) NUM2DBL(rb_gain)
-    };
+    sfSoundSourceCone cone = {.innerAngle = (float)NUM2DBL(rb_inner),
+                              .outerAngle = (float)NUM2DBL(rb_outer),
+                              .outerGain = (float)NUM2DBL(rb_gain)};
 
     return SoundSourceCone_wrap(cone);
 }
 
+/* call-seq: inner_angle -> Float
+ *
+ * Returns the inner cone angle in degrees.
+ *
+ * @return [Float] angle, in degrees, of the inner cone within which the
+ *   source is heard at full volume
+ */
 static VALUE SoundSourceCone_get_inner_angle(VALUE self) {
-    return DBL2NUM(((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone.innerAngle);
+    return DBL2NUM(((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone.innerAngle);
 }
 
+/* call-seq: outer_angle -> Float
+ *
+ * Returns the outer cone angle in degrees.
+ *
+ * @return [Float] angle, in degrees, of the outer cone beyond which the
+ *   source is heard at +outer_gain+ volume
+ */
 static VALUE SoundSourceCone_get_outer_angle(VALUE self) {
-    return DBL2NUM(((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone.outerAngle);
+    return DBL2NUM(((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone.outerAngle);
 }
 
+/* call-seq: outer_gain -> Float
+ *
+ * Returns the gain applied outside the outer cone.
+ *
+ * @return [Float] volume factor applied outside the outer cone
+ */
 static VALUE SoundSourceCone_get_outer_gain(VALUE self) {
-    return DBL2NUM(((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone.outerGain);
+    return DBL2NUM(((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone.outerGain);
 }
 
+/* call-seq:
+ *   inner_angle=(value) -> Float
+ *
+ * Sets the inner cone angle in degrees.
+ *
+ * @return [Float] +value+
+ */
 static VALUE SoundSourceCone_set_inner_angle(VALUE self, VALUE rb_value) {
-    ((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone.innerAngle = (float) NUM2DBL(rb_value);
+    ((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone.innerAngle =
+        (float)NUM2DBL(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   outer_angle=(value) -> Float
+ *
+ * Sets the outer cone angle in degrees.
+ *
+ * @return [Float] +value+
+ */
 static VALUE SoundSourceCone_set_outer_angle(VALUE self, VALUE rb_value) {
-    ((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone.outerAngle = (float) NUM2DBL(rb_value);
+    ((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone.outerAngle =
+        (float)NUM2DBL(rb_value);
     return rb_value;
 }
 
+/* call-seq:
+ *   outer_gain=(value) -> Float
+ *
+ * Sets the gain applied outside the outer cone.
+ *
+ * @return [Float] +value+
+ */
 static VALUE SoundSourceCone_set_outer_gain(VALUE self, VALUE rb_value) {
-    ((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone.outerGain = (float) NUM2DBL(rb_value);
+    ((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone.outerGain = (float)NUM2DBL(rb_value);
     return rb_value;
 }
 
+/* call-seq: to_a -> [Float, Float, Float]
+ *
+ * Returns the cone's three components as an Array.
+ *
+ * @return [Array<Float>] +[inner_angle, outer_angle, outer_gain]+
+ */
 static VALUE SoundSourceCone_to_a(VALUE self) {
-    sfSoundSourceCone cone = ((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone;
+    sfSoundSourceCone cone = ((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone;
 
     return rb_ary_new_from_args(3, DBL2NUM(cone.innerAngle), DBL2NUM(cone.outerAngle),
                                 DBL2NUM(cone.outerGain));
 }
 
+/* call-seq:
+ *   self == other -> true or false
+ *
+ * Returns +true+ if +other+ is a cone with the same angles and gain.
+ *
+ * @return [Boolean]
+ */
 static VALUE SoundSourceCone_eql(VALUE self, VALUE rb_other) {
-    sfSoundSourceCone a = ((SoundSourceCone *) Get_SoundSourceCone_Struct(self))->cone;
+    sfSoundSourceCone a = ((SoundSourceCone*)Get_SoundSourceCone_Struct(self))->cone;
     sfSoundSourceCone b;
 
     if (!rb_obj_is_kind_of(rb_other, rb_cSoundSourceCone)) {
         return Qfalse;
     }
 
-    b = ((SoundSourceCone *) Get_SoundSourceCone_Struct(rb_other))->cone;
+    b = ((SoundSourceCone*)Get_SoundSourceCone_Struct(rb_other))->cone;
 
     return BOOL2RB(a.innerAngle == b.innerAngle && a.outerAngle == b.outerAngle &&
                    a.outerGain == b.outerGain);
 }
 
-void Init_SoundSourceCone(VALUE rb_module) {
-    rb_cSoundSourceCone = rb_define_class_under(rb_module, "SoundSourceCone", rb_cObject);
+/* Document-class: SFML::SoundSourceCone
+ * A directional attenuation cone for a SoundSource (SoundSource#cone) or the
+ * Listener (Listener.cone): within +inner_angle+ degrees of the facing
+ * direction the source is heard at full volume; beyond +outer_angle+
+ * degrees it is heard at +outer_gain+ volume, with a smooth transition in
+ * between.
+ *
+ * @!attribute inner_angle
+ *   Angle, in degrees, of the inner cone within which the source is heard at
+ *   full volume.
+ *   @return [Float] angle, in degrees, of the inner cone within which the
+ *     source is heard at full volume
+ * @!attribute outer_angle
+ *   Angle, in degrees, of the outer cone beyond which the source is heard at
+ *   +outer_gain+ volume.
+ *   @return [Float] angle, in degrees, of the outer cone beyond which the
+ *     source is heard at +outer_gain+ volume
+ * @!attribute outer_gain
+ *   Volume factor applied outside the outer cone.
+ *   @return [Float] volume factor applied outside the outer cone
+ */
+void Init_SoundSourceCone(VALUE rb_mSFML) {
+    rb_cSoundSourceCone = rb_define_class_under(rb_mSFML, "SoundSourceCone", rb_cObject);
 
     rb_define_singleton_method(rb_cSoundSourceCone, "new", SoundSourceCone_new, 3);
 
@@ -107,30 +188,28 @@ VALUE Get_Klass_SoundSourceCone(void) {
     return rb_cSoundSourceCone;
 }
 
-void *Get_SoundSourceCone_Struct(VALUE self) {
-    SoundSourceCone *ptr;
+void* Get_SoundSourceCone_Struct(VALUE self) {
+    SoundSourceCone* ptr;
     TypedData_Get_Struct(self, SoundSourceCone, &SoundSourceCone_data_type, ptr);
     return ptr;
 }
 
 sfSoundSourceCone sound_source_cone_from_rb(VALUE rb_cone) {
     if (rb_obj_is_kind_of(rb_cone, rb_cSoundSourceCone)) {
-        return ((SoundSourceCone *) Get_SoundSourceCone_Struct(rb_cone))->cone;
+        return ((SoundSourceCone*)Get_SoundSourceCone_Struct(rb_cone))->cone;
     }
 
     if (RB_TYPE_P(rb_cone, T_ARRAY) && RARRAY_LEN(rb_cone) == 3) {
-        sfSoundSourceCone cone = {
-            .innerAngle = (float) NUM2DBL(rb_ary_entry(rb_cone, 0)),
-            .outerAngle = (float) NUM2DBL(rb_ary_entry(rb_cone, 1)),
-            .outerGain = (float) NUM2DBL(rb_ary_entry(rb_cone, 2))
-        };
+        sfSoundSourceCone cone = {.innerAngle = (float)NUM2DBL(rb_ary_entry(rb_cone, 0)),
+                                  .outerAngle = (float)NUM2DBL(rb_ary_entry(rb_cone, 1)),
+                                  .outerGain = (float)NUM2DBL(rb_ary_entry(rb_cone, 2))};
 
         return cone;
     }
 
     raise_invalid_argument_class(rb_cSoundSourceCone);
 
-    return (sfSoundSourceCone) {0.0f, 0.0f, 0.0f};
+    return (sfSoundSourceCone){0.0f, 0.0f, 0.0f};
 }
 
 VALUE sound_source_cone_to_rb(sfSoundSourceCone cone) {