sfml3-rb 0.2.2 → 0.3.0

data/ext/ports.rb

@@ -34,10 +34,17 @@ module Ports
     'x86-linux-gnu' => { triple: 'i686-linux-gnu', multiarch: 'i386-linux-gnu',
                          os: :linux, cpu: 'i686' },
     'aarch64-linux-gnu' => { triple: 'aarch64-linux-gnu', os: :linux, cpu: 'aarch64' },
+    'arm-linux-gnu' => { triple: 'arm-linux-gnueabihf', os: :linux, cpu: 'arm' },
     'x86_64-linux-musl' => { triple: 'x86_64-unknown-linux-musl', os: :linux, cpu: 'x86_64' },
     'x86-linux-musl' => { triple: 'i686-unknown-linux-musl', os: :linux, cpu: 'i686' },
+    # These two deliberately omit the -unknown- Debian-musl entries above use:
+    # the triple must match musl-cross-make's TARGET exactly, since that string
+    # is both the compiler prefix and the sysroot path (see musl_sysroot).
+    'aarch64-linux-musl' => { triple: 'aarch64-linux-musl', os: :linux, cpu: 'aarch64' },
+    'arm-linux-musl' => { triple: 'arm-linux-musleabihf', os: :linux, cpu: 'arm' },
     'x64-mingw-ucrt' => { triple: 'x86_64-w64-mingw32', os: :windows, cpu: 'x86_64' },
     'x86-mingw32' => { triple: 'i686-w64-mingw32', os: :windows, cpu: 'i686' },
+    'aarch64-mingw-ucrt' => { triple: 'aarch64-w64-mingw32', os: :windows, cpu: 'arm64' },
     'x86_64-darwin' => { triple: 'x86_64-apple-darwin', os: :darwin, cpu: 'x86_64' },
     'arm64-darwin' => { triple: 'aarch64-apple-darwin', os: :darwin, cpu: 'arm64' }
   }.freeze

data/ext/system/buffer.c

@@ -7,23 +7,30 @@
 
 static VALUE rb_cBuffer;
 
-static void Buffer_free(void *ptr) {
+static void Buffer_free(void* ptr) {
     sfBuffer_destroy(ptr);
 }
 
 static const rb_data_type_t Buffer_data_type = {
     .wrap_struct_name = "SFML::Buffer",
     .function = {.dmark = NULL, .dfree = Buffer_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE Buffer_wrap(VALUE klass, sfBuffer *buffer) {
+static VALUE Buffer_wrap(VALUE klass, sfBuffer* buffer) {
     return TypedData_Wrap_Struct(klass, &Buffer_data_type, buffer);
 }
 
+/* call-seq:
+ *   Buffer.new -> Buffer
+ *
+ * Creates a new, empty byte buffer.
+ *
+ * @return [Buffer] a new, empty buffer
+ * @raise [NoMemoryError] if the underlying buffer could not be allocated
+ */
 static VALUE Buffer_new(VALUE klass) {
     VALUE self;
-    sfBuffer *buffer = sfBuffer_create();
+    sfBuffer* buffer = sfBuffer_create();
 
     if (buffer == NULL) {
         rb_raise(rb_eNoMemError, "could not create buffer");
@@ -34,28 +41,50 @@ static VALUE Buffer_new(VALUE klass) {
     return self;
 }
 
+/* call-seq: size -> Integer
+ *
+ * Returns the size of the buffer in bytes.
+ *
+ * @return [Integer] size in bytes
+ */
 static VALUE Buffer_get_size(VALUE self) {
     return SIZET2NUM(sfBuffer_getSize(Get_Buffer_Struct(self)));
 }
 
+/* call-seq: data -> String
+ *
+ * Returns the raw bytes held by the buffer.
+ *
+ * @return [String] the raw bytes, as a binary String
+ */
 static VALUE Buffer_get_data(VALUE self) {
-    sfBuffer *buffer = Get_Buffer_Struct(self);
+    sfBuffer* buffer = Get_Buffer_Struct(self);
     size_t size = sfBuffer_getSize(buffer);
-    const uint8_t *data = sfBuffer_getData(buffer);
+    const uint8_t* data = sfBuffer_getData(buffer);
 
     if (data == NULL || size == 0) {
         return rb_str_new("", 0);
     }
 
-    return rb_str_new((const char *) data, (long) size);
+    return rb_str_new((const char*)data, (long)size);
 }
 
+/* call-seq: empty? -> true or false
+ *
+ * Returns +true+ if the buffer holds no bytes.
+ *
+ * @return [Boolean]
+ */
 static VALUE Buffer_is_empty(VALUE self) {
     return BOOL2RB(sfBuffer_getSize(Get_Buffer_Struct(self)) == 0);
 }
 
-void Init_Buffer(VALUE rb_module) {
-    rb_cBuffer = rb_define_class_under(rb_module, "Buffer", rb_cObject);
+/* Document-class: SFML::Buffer
+ * A raw byte buffer, as used for encoded/decoded audio and image data
+ * elsewhere in the library.
+ */
+void Init_Buffer(VALUE rb_mSFML) {
+    rb_cBuffer = rb_define_class_under(rb_mSFML, "Buffer", rb_cObject);
 
     rb_define_singleton_method(rb_cBuffer, "new", Buffer_new, 0);
 
@@ -70,8 +99,8 @@ VALUE Get_Klass_Buffer(void) {
     return rb_cBuffer;
 }
 
-void *Get_Buffer_Struct(VALUE self) {
-    sfBuffer *ptr;
+void* Get_Buffer_Struct(VALUE self) {
+    sfBuffer* ptr;
     TypedData_Get_Struct(self, sfBuffer, &Buffer_data_type, ptr);
     return ptr;
 }

data/ext/system/clock.c

@@ -9,23 +9,26 @@
 
 static VALUE rb_cClock;
 
-static sfClock *Clock_create() {
+static sfClock* Clock_create() {
     return sfClock_create();
 }
 
-static void Clock_free(void *ptr) {
+static void Clock_free(void* ptr) {
     sfClock_destroy(ptr);
 }
 
 static const rb_data_type_t Clock_data_type = {
     .wrap_struct_name = "SFML::Clock",
     .function = {.dmark = NULL, .dfree = Clock_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE Clock_new_from(VALUE klass, sfClock *clock) {
+static VALUE Clock_new_from(VALUE klass, sfClock* clock) {
     VALUE self;
 
+    if (clock == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate clock");
+    }
+
     self = TypedData_Wrap_Struct(klass, &Clock_data_type, clock);
 
     rb_obj_call_init(self, 0, NULL);
@@ -33,6 +36,13 @@ static VALUE Clock_new_from(VALUE klass, sfClock *clock) {
     return self;
 }
 
+/* call-seq:
+ *   Clock.new -> Clock
+ *
+ * Creates a new clock and starts it immediately.
+ *
+ * @return [Clock]
+ */
 static VALUE Clock_new(VALUE klass) {
     return Clock_new_from(klass, Clock_create());
 }
@@ -41,38 +51,87 @@ static VALUE Clock_init(VALUE self) {
     return self;
 }
 
+/* call-seq: elapsed_time -> Time
+ *
+ * Returns the time elapsed on the clock.
+ *
+ * @return [Time] time elapsed since the clock was created, started, or last
+ *   restarted/reset, whichever is most recent
+ */
 static VALUE Clock_get_elapsed_time(VALUE self) {
     return time_to_rb(sfClock_getElapsedTime(Get_Clock_Struct(self)));
 }
 
+/* call-seq: restart! -> Time
+ *
+ * Restarts the clock (equivalent to #reset! followed by #start!) and
+ * returns the time elapsed before restarting.
+ *
+ * @return [Time]
+ */
 static VALUE Clock_restart(VALUE self) {
     return time_to_rb(sfClock_restart(Get_Clock_Struct(self)));
 }
 
+/* call-seq: reset! -> Time
+ *
+ * Stops the clock and resets its elapsed time to zero, returning the time
+ * elapsed before resetting.
+ *
+ * @return [Time]
+ */
 static VALUE Clock_reset(VALUE self) {
     return time_to_rb(sfClock_reset(Get_Clock_Struct(self)));
 }
 
+/* call-seq: running? -> true or false
+ *
+ * Returns +true+ while the clock is running, +false+ once it is stopped.
+ *
+ * @return [Boolean]
+ */
 static VALUE Clock_is_running(VALUE self) {
     return BOOL2RB(sfClock_isRunning(Get_Clock_Struct(self)));
 }
 
+/* call-seq: start! -> self
+ *
+ * Resumes a stopped clock without resetting its elapsed time.
+ *
+ * @return [self]
+ */
 static VALUE Clock_start(VALUE self) {
     sfClock_start(Get_Clock_Struct(self));
     return self;
 }
 
+/* call-seq: stop! -> self
+ *
+ * Pauses the clock; #elapsed_time keeps returning the time at which it
+ * was stopped until #start! or #restart! is called.
+ *
+ * @return [self]
+ */
 static VALUE Clock_stop(VALUE self) {
     sfClock_stop(Get_Clock_Struct(self));
     return self;
 }
 
+/* call-seq: copy -> Clock
+ *
+ * Returns an independent copy of the clock.
+ *
+ * @return [Clock] an independent copy with the same elapsed/running state
+ */
 static VALUE Clock_copy(VALUE self) {
     return Clock_new_from(Get_Klass_Clock(), sfClock_copy(Get_Clock_Struct(self)));
 }
 
-void Init_Clock(VALUE rb_module) {
-    rb_cClock = rb_define_class_under(rb_module, "Clock", rb_cObject);
+/* Document-class: SFML::Clock
+ * A stopwatch for measuring elapsed time.
+ */
+void Init_Clock(VALUE rb_mSFML) {
+    rb_cClock = rb_define_class_under(rb_mSFML, "Clock", rb_cObject);
 
     rb_define_singleton_method(rb_cClock, "new", Clock_new, 0);
 
@@ -89,8 +148,8 @@ void Init_Clock(VALUE rb_module) {
     rb_define_method(rb_cClock, "running?", Clock_is_running, 0);
 }
 
-void *Get_Clock_Struct(VALUE self) {
-    sfClock *clock;
+void* Get_Clock_Struct(VALUE self) {
+    sfClock* clock;
     TypedData_Get_Struct(self, sfClock, &Clock_data_type, clock);
     return clock;
 }

data/ext/system/input_stream.c

@@ -16,21 +16,20 @@ typedef struct {
 
 static VALUE rb_cInputStream;
 
-static void InputStream_mark(void *ptr) {
-    InputStream *stream = ptr;
+static void InputStream_mark(void* ptr) {
+    InputStream* stream = ptr;
 
     rb_gc_mark(stream->rb_io);
 }
 
-static void InputStream_free(void *ptr) {
+static void InputStream_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t InputStream_data_type = {
     .wrap_struct_name = "SFML::InputStream",
     .function = {.dmark = InputStream_mark, .dfree = InputStream_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 /* Callbacks run from C++ (SFML), so a Ruby exception must never unwind through
    those frames. Each body runs under rb_protect and reports failure as a
@@ -38,12 +37,12 @@ static const rb_data_type_t InputStream_data_type = {
 typedef struct {
     VALUE io;
     size_t size;
-    void *data;
+    void* data;
     int64_t result;
 } ReadContext;
 
 static VALUE InputStream_read_body(VALUE v) {
-    ReadContext *ctx = (ReadContext *) v;
+    ReadContext* ctx = (ReadContext*)v;
     VALUE str = rb_funcall(ctx->io, rb_intern("read"), 1, SIZET2NUM(ctx->size));
 
     if (NIL_P(str)) {
@@ -55,25 +54,31 @@ static VALUE InputStream_read_body(VALUE v) {
 
     long length = RSTRING_LEN(str);
 
-    if ((size_t) length > ctx->size) {
-        length = (long) ctx->size;
+    if ((size_t)length > ctx->size) {
+        length = (long)ctx->size;
     }
 
     if (length > 0) {
-        memcpy(ctx->data, RSTRING_PTR(str), (size_t) length);
+        const unsigned char* src = (const unsigned char*)RSTRING_PTR(str);
+        unsigned char* dest = ctx->data;
+        long i;
+
+        for (i = 0; i < length; i++) {
+            dest[i] = src[i];
+        }
     }
 
-    ctx->result = (int64_t) length;
+    ctx->result = (int64_t)length;
 
     return Qnil;
 }
 
-static int64_t InputStream_read(void *data, size_t size, void *userData) {
-    InputStream *stream = userData;
+static int64_t InputStream_read(void* data, size_t size, void* userData) {
+    InputStream* stream = userData;
     ReadContext ctx = {.io = stream->rb_io, .size = size, .data = data, .result = -1};
     int state = 0;
 
-    rb_protect(InputStream_read_body, (VALUE) &ctx, &state);
+    rb_protect(InputStream_read_body, (VALUE)&ctx, &state);
 
     if (state) {
         rb_set_errinfo(Qnil);
@@ -90,20 +95,20 @@ typedef struct {
 } SeekContext;
 
 static VALUE InputStream_seek_body(VALUE v) {
-    SeekContext *ctx = (SeekContext *) v;
+    SeekContext* ctx = (SeekContext*)v;
 
     rb_funcall(ctx->io, rb_intern("seek"), 2, SIZET2NUM(ctx->position), INT2NUM(SEEK_SET));
-    ctx->result = (int64_t) ctx->position;
+    ctx->result = (int64_t)ctx->position;
 
     return Qnil;
 }
 
-static int64_t InputStream_seek(size_t position, void *userData) {
-    InputStream *stream = userData;
+static int64_t InputStream_seek(size_t position, void* userData) {
+    InputStream* stream = userData;
     SeekContext ctx = {.io = stream->rb_io, .position = position, .result = -1};
     int state = 0;
 
-    rb_protect(InputStream_seek_body, (VALUE) &ctx, &state);
+    rb_protect(InputStream_seek_body, (VALUE)&ctx, &state);
 
     if (state) {
         rb_set_errinfo(Qnil);
@@ -113,55 +118,91 @@ static int64_t InputStream_seek(size_t position, void *userData) {
     return ctx.result;
 }
 
+typedef struct {
+    VALUE io;
+    int64_t result;
+} Int64Context;
+
+/* NUM2LL is done here, inside the rb_protect-called body, rather than after
+   rb_protect returns: if the IO's #tell/#pos/#size/#length returns something
+   that doesn't convert cleanly to a C integer (a String, nil, a Bignum too
+   large for int64_t, a #to_int that itself raises), NUM2LL raises directly --
+   and unprotected, that exception would unwind straight through CSFML's (and
+   possibly SFML's C++) stack frames, exactly what rb_protect exists to
+   prevent here. */
 static VALUE InputStream_tell_body(VALUE v) {
-    VALUE io = (VALUE) v;
+    Int64Context* ctx = (Int64Context*)v;
+    VALUE result;
 
-    if (rb_respond_to(io, rb_intern("tell"))) {
-        return rb_funcall(io, rb_intern("tell"), 0);
+    if (rb_respond_to(ctx->io, rb_intern("tell"))) {
+        result = rb_funcall(ctx->io, rb_intern("tell"), 0);
+    } else {
+        result = rb_funcall(ctx->io, rb_intern("pos"), 0);
     }
 
-    return rb_funcall(io, rb_intern("pos"), 0);
+    ctx->result = NUM2LL(result);
+
+    return Qnil;
 }
 
-static int64_t InputStream_tell(void *userData) {
-    InputStream *stream = userData;
+static int64_t InputStream_tell(void* userData) {
+    InputStream* stream = userData;
+    Int64Context ctx = {.io = stream->rb_io, .result = -1};
     int state = 0;
-    VALUE result = rb_protect(InputStream_tell_body, stream->rb_io, &state);
+
+    rb_protect(InputStream_tell_body, (VALUE)&ctx, &state);
 
     if (state) {
         rb_set_errinfo(Qnil);
         return -1;
     }
 
-    return NUM2LL(result);
+    return ctx.result;
 }
 
 static VALUE InputStream_get_size_body(VALUE v) {
-    VALUE io = (VALUE) v;
+    Int64Context* ctx = (Int64Context*)v;
+    VALUE result;
 
-    if (rb_respond_to(io, rb_intern("size"))) {
-        return rb_funcall(io, rb_intern("size"), 0);
+    if (rb_respond_to(ctx->io, rb_intern("size"))) {
+        result = rb_funcall(ctx->io, rb_intern("size"), 0);
+    } else {
+        result = rb_funcall(ctx->io, rb_intern("length"), 0);
     }
 
-    return rb_funcall(io, rb_intern("length"), 0);
+    ctx->result = NUM2LL(result);
+
+    return Qnil;
 }
 
-static int64_t InputStream_get_size(void *userData) {
-    InputStream *stream = userData;
+static int64_t InputStream_get_size(void* userData) {
+    InputStream* stream = userData;
+    Int64Context ctx = {.io = stream->rb_io, .result = -1};
     int state = 0;
-    VALUE result = rb_protect(InputStream_get_size_body, stream->rb_io, &state);
+
+    rb_protect(InputStream_get_size_body, (VALUE)&ctx, &state);
 
     if (state) {
         rb_set_errinfo(Qnil);
         return -1;
     }
 
-    return NUM2LL(result);
+    return ctx.result;
 }
 
+/* call-seq:
+ *   InputStream.new(io) -> InputStream
+ *
+ * Wraps a Ruby object that responds to +#read+ (and ideally +#seek+/+#tell+
+ * or +#pos+, and +#size+ or +#length+) so it can be passed anywhere the
+ * library accepts a stream-based data source.
+ *
+ * @return [InputStream]
+ * @raise [ArgumentError] if +io+ does not respond to +#read+
+ */
 static VALUE InputStream_new(VALUE klass, VALUE rb_io) {
     VALUE self;
-    InputStream *stream;
+    InputStream* stream;
 
     if (!rb_respond_to(rb_io, rb_intern("read"))) {
         rb_raise(rb_eArgError, "stream object must respond to #read");
@@ -181,12 +222,23 @@ static VALUE InputStream_new(VALUE klass, VALUE rb_io) {
     return self;
 }
 
+/* call-seq: io -> Object
+ *
+ * Returns the IO-like object the stream was created from.
+ *
+ * @return [Object] the wrapped IO-like object
+ */
 static VALUE InputStream_get_io(VALUE self) {
-    return ((InputStream *) Get_InputStream_Struct(self))->rb_io;
+    return ((InputStream*)Get_InputStream_Struct(self))->rb_io;
 }
 
-void Init_InputStream(VALUE rb_module) {
-    rb_cInputStream = rb_define_class_under(rb_module, "InputStream", rb_cObject);
+/* Document-class: SFML::InputStream
+ * Adapts any Ruby object that responds to +#read+ into the stream interface
+ * SFML's loaders expect, so resources can be loaded from something other
+ * than a filesystem path (e.g. an in-memory StringIO, or a custom source).
+ */
+void Init_InputStream(VALUE rb_mSFML) {
+    rb_cInputStream = rb_define_class_under(rb_mSFML, "InputStream", rb_cObject);
 
     rb_define_singleton_method(rb_cInputStream, "new", InputStream_new, 1);
 
@@ -197,8 +249,8 @@ VALUE Get_Klass_InputStream(void) {
     return rb_cInputStream;
 }
 
-sfInputStream *Get_InputStream_Struct(VALUE self) {
-    InputStream *ptr;
+sfInputStream* Get_InputStream_Struct(VALUE self) {
+    InputStream* ptr;
     TypedData_Get_Struct(self, InputStream, &InputStream_data_type, ptr);
     return &ptr->stream;
 }
@@ -207,7 +259,7 @@ int InputStream_is_stream(VALUE rb_stream) {
     return rb_obj_is_kind_of(rb_stream, rb_cInputStream) ? 1 : 0;
 }
 
-sfInputStream *input_stream_from_rb(VALUE rb_stream, VALUE *holder) {
+sfInputStream* input_stream_from_rb(VALUE rb_stream, VALUE* holder) {
     if (InputStream_is_stream(rb_stream)) {
         return Get_InputStream_Struct(rb_stream);
     }

data/ext/system/sleep.c

@@ -5,12 +5,20 @@
 #include "system/time.h"
 #include "core/sfml.h"
 
+/* call-seq:
+ *   SFML.sleep(duration) -> duration
+ *
+ * Blocks the calling thread for +duration+, which may be a Time, a number
+ * of seconds, or anything #to_f-convertible.
+ *
+ * @return [Time, Numeric] +duration+
+ */
 static VALUE Sleep_sleep(VALUE module, VALUE rb_duration) {
     sfSleep(time_from_rb(rb_duration));
 
     return rb_duration;
 }
 
-void Init_Sleep(VALUE rb_module) {
-    rb_define_module_function(rb_module, "sleep", Sleep_sleep, 1);
+void Init_Sleep(VALUE rb_mSFML) {
+    rb_define_module_function(rb_mSFML, "sleep", Sleep_sleep, 1);
 }