sfml3-rb 0.2.2 → 0.3.1

data/ext/network/udp_socket.c

@@ -9,13 +9,13 @@
 #include "network/packet.h"
 
 typedef struct {
-    sfUdpSocket *handle;
+    sfUdpSocket* handle;
 } UdpSocket;
 
 static VALUE rb_cUdpSocket;
 
-static void UdpSocket_free(void *ptr) {
-    UdpSocket *socket = ptr;
+static void UdpSocket_free(void* ptr) {
+    UdpSocket* socket = ptr;
 
     if (socket->handle != NULL) {
         sfUdpSocket_destroy(socket->handle);
@@ -27,11 +27,10 @@ static void UdpSocket_free(void *ptr) {
 static const rb_data_type_t UdpSocket_data_type = {
     .wrap_struct_name = "SFML::UdpSocket",
     .function = {.dmark = NULL, .dfree = UdpSocket_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE UdpSocket_wrap(VALUE klass, sfUdpSocket *handle) {
-    UdpSocket *ptr;
+static VALUE UdpSocket_wrap(VALUE klass, sfUdpSocket* handle) {
+    UdpSocket* ptr;
 
     if (handle == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create UDP socket");
@@ -43,60 +42,135 @@ static VALUE UdpSocket_wrap(VALUE klass, sfUdpSocket *handle) {
     return TypedData_Wrap_Struct(klass, &UdpSocket_data_type, ptr);
 }
 
-static VALUE UdpSocket_new(VALUE klass) {
+static VALUE UdpSocket_alloc(VALUE klass) {
     return UdpSocket_wrap(klass, sfUdpSocket_create());
 }
 
+/* call-seq:
+ *   UdpSocket.new -> UdpSocket
+ *
+ * Creates a new, unbound UDP socket.
+ *
+ * @return [UdpSocket] a new, unbound socket
+ */
+static VALUE UdpSocket_initialize(VALUE self) {
+    return self;
+}
+
+/* call-seq:
+ *   UdpSocket.any_port -> Integer
+ *
+ * Returns the port value that makes #bind bind to an OS-chosen port.
+ *
+ * @return [Integer] a port value that #bind interprets as "let the OS pick
+ *   an available port"
+ */
 static VALUE UdpSocket_any_port(VALUE klass) {
     return UINT2NUM(sfUdpSocket_anyPort());
 }
 
+/* call-seq:
+ *   UdpSocket.max_datagram_size -> Integer
+ *
+ * Returns the maximum size, in bytes, of a single UDP datagram.
+ *
+ * @return [Integer] the maximum number of bytes that can be sent in a
+ *   single UDP datagram (65507)
+ */
 static VALUE UdpSocket_max_datagram_size(VALUE klass) {
     return UINT2NUM(sfUdpSocket_maxDatagramSize());
 }
 
+/* call-seq: blocking? -> true or false
+ *
+ * Returns +true+ if the socket is in blocking mode.
+ *
+ * @return [Boolean]
+ */
 static VALUE UdpSocket_blocking(VALUE self) {
     return BOOL2RB(sfUdpSocket_isBlocking(Get_UdpSocket_Struct(self)));
 }
 
+/* call-seq:
+ *   blocking=(value) -> value
+ *
+ * Enables or disables blocking mode according to +value+.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE UdpSocket_set_blocking(VALUE self, VALUE rb_value) {
     sfUdpSocket_setBlocking(Get_UdpSocket_Struct(self), RTEST(rb_value));
     return rb_value;
 }
 
+/* call-seq: local_port -> Integer
+ *
+ * Returns the local port the socket is bound to.
+ *
+ * @return [Integer] the port the socket is bound to, or 0 if not bound
+ */
 static VALUE UdpSocket_local_port(VALUE self) {
     return UINT2NUM(sfUdpSocket_getLocalPort(Get_UdpSocket_Struct(self)));
 }
 
-static VALUE UdpSocket_bind(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   bind(port, address = IpAddress::ANY) -> Symbol
+ *
+ * Binds the socket to a local port, optionally restricted to a specific
+ * local network interface via +address+, so it can receive datagrams.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
+static VALUE UdpSocket_bind(int argc, VALUE* argv, VALUE self) {
     VALUE rb_port, rb_address;
 
     rb_scan_args(argc, argv, "11", &rb_port, &rb_address);
 
-    return ID2SYM(rb_intern(socket_status_name(sfUdpSocket_bind(
-        Get_UdpSocket_Struct(self), (unsigned short) NUM2INT(rb_port),
-        ip_address_from_rb(rb_address, sfIpAddress_Any)))));
+    return ID2SYM(rb_intern(socket_status_name(
+        sfUdpSocket_bind(Get_UdpSocket_Struct(self), (unsigned short)NUM2INT(rb_port),
+                         ip_address_from_rb(rb_address, sfIpAddress_Any)))));
 }
 
+/* call-seq: unbind -> self
+ *
+ * Unbinds the socket from its local port.
+ *
+ * @return [self]
+ */
 static VALUE UdpSocket_unbind(VALUE self) {
     sfUdpSocket_unbind(Get_UdpSocket_Struct(self));
     return self;
 }
 
+/* call-seq:
+ *   send(data, address, port) -> Symbol
+ *
+ * Sends a single datagram to a remote peer. +data+ must be no larger than
+ * .max_datagram_size bytes.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ */
 static VALUE UdpSocket_send(VALUE self, VALUE rb_data, VALUE rb_address, VALUE rb_port) {
     StringValue(rb_data);
 
     return ID2SYM(rb_intern(socket_status_name(sfUdpSocket_send(
-        Get_UdpSocket_Struct(self), RSTRING_PTR(rb_data), (size_t) RSTRING_LEN(rb_data),
-        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short) NUM2INT(rb_port)))));
+        Get_UdpSocket_Struct(self), RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data),
+        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short)NUM2INT(rb_port)))));
 }
 
-/* Returns [data, IpAddress, port, status]; the address and port are those of
-   the sender. */
-static VALUE UdpSocket_receive(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   receive(max_length = 1024) -> [String, IpAddress, Integer, Symbol]
+ *
+ * Returns [data, IpAddress, port, status]; the address and port are those of
+ * the sender.
+ *
+ * @return [Array(String, IpAddress, Integer, Symbol)]
+ * @raise [ArgumentError] if +max_length+ isn't positive
+ */
+static VALUE UdpSocket_receive(int argc, VALUE* argv, VALUE self) {
     VALUE rb_max_length;
     long max_length = 1024;
-    char *buffer;
+    char* buffer;
     size_t received = 0;
     sfIpAddress remote_address = sfIpAddress_None;
     unsigned short remote_port = 0;
@@ -113,13 +187,17 @@ static VALUE UdpSocket_receive(int argc, VALUE *argv, VALUE self) {
         rb_raise(rb_eArgError, "maximum length must be positive");
     }
 
-    buffer = malloc((size_t) max_length);
+    buffer = malloc((size_t)max_length);
+
+    if (buffer == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate receive buffer");
+    }
 
-    status = sfUdpSocket_receive(Get_UdpSocket_Struct(self), buffer, (size_t) max_length, &received,
+    status = sfUdpSocket_receive(Get_UdpSocket_Struct(self), buffer, (size_t)max_length, &received,
                                  &remote_address, &remote_port);
 
     rb_result = rb_ary_new_capa(4);
-    rb_ary_push(rb_result, rb_str_new(buffer, (long) received));
+    rb_ary_push(rb_result, rb_str_new(buffer, (long)received));
     rb_ary_push(rb_result, ip_address_to_rb(remote_address));
     rb_ary_push(rb_result, UINT2NUM(remote_port));
     rb_ary_push(rb_result, ID2SYM(rb_intern(socket_status_name(status))));
@@ -129,6 +207,14 @@ static VALUE UdpSocket_receive(int argc, VALUE *argv, VALUE self) {
     return rb_result;
 }
 
+/* call-seq:
+ *   send_packet(packet, address, port) -> Symbol
+ *
+ * Sends +packet+ as a datagram to the given +address+ and +port+.
+ *
+ * @return [Symbol] a SocketStatus name, +:done+ on success
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE UdpSocket_send_packet(VALUE self, VALUE rb_packet, VALUE rb_address, VALUE rb_port) {
     if (!rb_obj_is_kind_of(rb_packet, Get_Klass_Packet())) {
         rb_raise(rb_eTypeError, "expected an SFML::Packet");
@@ -136,10 +222,19 @@ static VALUE UdpSocket_send_packet(VALUE self, VALUE rb_packet, VALUE rb_address
 
     return ID2SYM(rb_intern(socket_status_name(sfUdpSocket_sendPacket(
         Get_UdpSocket_Struct(self), Get_Packet_Struct(rb_packet),
-        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short) NUM2INT(rb_port)))));
+        ip_address_from_rb(rb_address, sfIpAddress_None), (unsigned short)NUM2INT(rb_port)))));
 }
 
-/* Returns [IpAddress, port, status]. */
+/* call-seq:
+ *   receive_packet(packet) -> [IpAddress, Integer, Symbol]
+ *
+ * Fills +packet+ (replacing its previous contents) with the next datagram
+ * received. Returns [IpAddress, port, status], the address and port of the
+ * sender.
+ *
+ * @return [Array(IpAddress, Integer, Symbol)]
+ * @raise [TypeError] if +packet+ is not an SFML::Packet
+ */
 static VALUE UdpSocket_receive_packet(VALUE self, VALUE rb_packet) {
     sfIpAddress remote_address = sfIpAddress_None;
     unsigned short remote_port = 0;
@@ -161,10 +256,16 @@ static VALUE UdpSocket_receive_packet(VALUE self, VALUE rb_packet) {
     return rb_result;
 }
 
-void Init_UdpSocket(VALUE rb_module) {
-    rb_cUdpSocket = rb_define_class_under(rb_module, "UdpSocket", rb_cObject);
+/* Document-class: SFML::UdpSocket
+ * A connectionless, unreliable, datagram-oriented socket for UDP
+ * communication. Datagrams may be lost, duplicated or arrive out of order,
+ * and are capped at .max_datagram_size bytes.
+ */
+void Init_UdpSocket(VALUE rb_mSFML) {
+    rb_cUdpSocket = rb_define_class_under(rb_mSFML, "UdpSocket", rb_cObject);
+    rb_define_alloc_func(rb_cUdpSocket, UdpSocket_alloc);
 
-    rb_define_singleton_method(rb_cUdpSocket, "new", UdpSocket_new, 0);
+    rb_define_method(rb_cUdpSocket, "initialize", UdpSocket_initialize, 0);
     rb_define_singleton_method(rb_cUdpSocket, "any_port", UdpSocket_any_port, 0);
     rb_define_singleton_method(rb_cUdpSocket, "max_datagram_size", UdpSocket_max_datagram_size, 0);
 
@@ -183,8 +284,8 @@ VALUE Get_Klass_UdpSocket(void) {
     return rb_cUdpSocket;
 }
 
-void *Get_UdpSocket_Struct(VALUE self) {
-    UdpSocket *ptr;
+void* Get_UdpSocket_Struct(VALUE self) {
+    UdpSocket* ptr;
     TypedData_Get_Struct(self, UdpSocket, &UdpSocket_data_type, ptr);
     return ptr->handle;
 }

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,57 +7,88 @@
 
 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);
 }
 
-static VALUE Buffer_new(VALUE klass) {
-    VALUE self;
-    sfBuffer *buffer = sfBuffer_create();
+static VALUE Buffer_alloc(VALUE klass) {
+    sfBuffer* buffer = sfBuffer_create();
 
     if (buffer == NULL) {
         rb_raise(rb_eNoMemError, "could not create buffer");
     }
 
-    self = Buffer_wrap(klass, buffer);
+    return Buffer_wrap(klass, 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_initialize(VALUE self) {
     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);
+    rb_define_alloc_func(rb_cBuffer, Buffer_alloc);
+    rb_define_method(rb_cBuffer, "initialize", Buffer_initialize, 0);
 
     rb_define_method(rb_cBuffer, "size", Buffer_get_size, 0);
     rb_define_method(rb_cBuffer, "length", Buffer_get_size, 0);
@@ -70,8 +101,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,48 +36,110 @@ static VALUE Clock_new_from(VALUE klass, sfClock *clock) {
     return self;
 }
 
-static VALUE Clock_new(VALUE klass) {
-    return Clock_new_from(klass, Clock_create());
+static VALUE Clock_alloc(VALUE klass) {
+    sfClock* clock = Clock_create();
+
+    if (clock == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate clock");
+    }
+
+    return TypedData_Wrap_Struct(klass, &Clock_data_type, clock);
 }
 
+/* call-seq:
+ *   Clock.new -> Clock
+ *
+ * Creates a new clock and starts it immediately.
+ *
+ * @return [Clock]
+ */
 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);
+    rb_define_alloc_func(rb_cClock, Clock_alloc);
 
     // methods
     rb_define_method(rb_cClock, "initialize", Clock_init, 0);
@@ -89,8 +154,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;
 }