sfml3-rb 0.2.2 → 0.3.0

data/ext/system/vec3.c

@@ -12,19 +12,31 @@ typedef struct {
 
 static VALUE rb_cVector3;
 
-static void Vector3_free(void *ptr) {
+static void Vector3_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t Vector3_data_type = {
     .wrap_struct_name = "SFML::Vector3",
     .function = {.dmark = NULL, .dfree = Vector3_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
-
-static VALUE Vector3_new(int argc, VALUE *argv, VALUE klass) {
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
+
+/* call-seq:
+ *   Vector3.new                -> Vector3(0, 0, 0)
+ *   Vector3.new(x, y, z)       -> Vector3(x, y, z)
+ *   Vector3.new([x, y, z])     -> Vector3(x, y, z)
+ *   Vector3.new(other_vector3) -> copy of +other_vector3+
+ *
+ * Creates a new 3D vector from three coordinates, a 3-element Array, or
+ * another Vector3.
+ *
+ * @return [Vector3]
+ * @raise [ArgumentError] if given an Array shorter than 3 elements, or an
+ *   argument count other than 0, 1 or 3
+ */
+static VALUE Vector3_new(int argc, VALUE* argv, VALUE klass) {
     VALUE self;
-    Vector3 *ptr;
+    Vector3* ptr;
     float x = 0;
     float y = 0;
     float z = 0;
@@ -51,6 +63,11 @@ static VALUE Vector3_new(int argc, VALUE *argv, VALUE klass) {
     }
 
     ptr = malloc(sizeof(Vector3));
+
+    if (ptr == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate vector");
+    }
+
     ptr->vec.x = x;
     ptr->vec.y = y;
     ptr->vec.z = z;
@@ -60,41 +77,92 @@ static VALUE Vector3_new(int argc, VALUE *argv, VALUE klass) {
     return self;
 }
 
+/* call-seq: x -> Float
+ *
+ * Returns the X component of the vector.
+ *
+ * @return [Float] the X component
+ */
 static VALUE Vector3_get_x(VALUE self) {
-    return DBL2NUM(((Vector3 *) Get_Vector3_Struct(self))->vec.x);
+    return DBL2NUM(((Vector3*)Get_Vector3_Struct(self))->vec.x);
 }
 
+/* call-seq: y -> Float
+ *
+ * Returns the Y component of the vector.
+ *
+ * @return [Float] the Y component
+ */
 static VALUE Vector3_get_y(VALUE self) {
-    return DBL2NUM(((Vector3 *) Get_Vector3_Struct(self))->vec.y);
+    return DBL2NUM(((Vector3*)Get_Vector3_Struct(self))->vec.y);
 }
 
+/* call-seq: z -> Float
+ *
+ * Returns the Z component of the vector.
+ *
+ * @return [Float] the Z component
+ */
 static VALUE Vector3_get_z(VALUE self) {
-    return DBL2NUM(((Vector3 *) Get_Vector3_Struct(self))->vec.z);
+    return DBL2NUM(((Vector3*)Get_Vector3_Struct(self))->vec.z);
 }
 
+/* call-seq:
+ *   x=(value) -> Float
+ *
+ * Sets the X component. +value+ is any Float-convertible number.
+ *
+ * @return [Float] +value+
+ */
 static VALUE Vector3_set_x(VALUE self, VALUE rb_x) {
-    ((Vector3 *) Get_Vector3_Struct(self))->vec.x = NUM2DBL(rb_x);
+    ((Vector3*)Get_Vector3_Struct(self))->vec.x = NUM2DBL(rb_x);
     return rb_x;
 }
 
+/* call-seq:
+ *   y=(value) -> Float
+ *
+ * Sets the Y component. +value+ is any Float-convertible number.
+ *
+ * @return [Float] +value+
+ */
 static VALUE Vector3_set_y(VALUE self, VALUE rb_y) {
-    ((Vector3 *) Get_Vector3_Struct(self))->vec.y = NUM2DBL(rb_y);
+    ((Vector3*)Get_Vector3_Struct(self))->vec.y = NUM2DBL(rb_y);
     return rb_y;
 }
 
+/* call-seq:
+ *   z=(value) -> Float
+ *
+ * Sets the Z component. +value+ is any Float-convertible number.
+ *
+ * @return [Float] +value+
+ */
 static VALUE Vector3_set_z(VALUE self, VALUE rb_z) {
-    ((Vector3 *) Get_Vector3_Struct(self))->vec.z = NUM2DBL(rb_z);
+    ((Vector3*)Get_Vector3_Struct(self))->vec.z = NUM2DBL(rb_z);
     return rb_z;
 }
 
+/* call-seq: to_a -> Array
+ *
+ * Returns the vector's components as a three-element Array.
+ *
+ * @return [Array<Float>] +[x, y, z]+
+ */
 static VALUE Vector3_to_a(VALUE self) {
-    Vector3 *vec = Get_Vector3_Struct(self);
+    Vector3* vec = Get_Vector3_Struct(self);
 
     return rb_ary_new_from_args(3, DBL2NUM(vec->vec.x), DBL2NUM(vec->vec.y), DBL2NUM(vec->vec.z));
 }
 
+/* call-seq: each { |component| ... } -> self
+ *
+ * Yields +x+, +y+, then +z+.
+ *
+ * @return [self]
+ */
 static VALUE Vector3_each(VALUE self) {
-    Vector3 *vec = Get_Vector3_Struct(self);
+    Vector3* vec = Get_Vector3_Struct(self);
 
     rb_yield(DBL2NUM(vec->vec.x));
     rb_yield(DBL2NUM(vec->vec.y));
@@ -103,16 +171,29 @@ static VALUE Vector3_each(VALUE self) {
     return self;
 }
 
+/* call-seq: size -> Integer
+ *
+ * Returns the number of components, always 3.
+ *
+ * @return [Integer] always 3
+ */
 static VALUE Vector3_size(VALUE self) {
     return INT2NUM(3);
 }
 
+/* call-seq:
+ *   self == other -> true or false
+ *
+ * +other+ may be a Vector3 or a 3-element Array.
+ *
+ * @return [Boolean]
+ */
 static VALUE Vector3_eql(VALUE self, VALUE rb_other) {
-    Vector3 *a = Get_Vector3_Struct(self);
+    Vector3* a = Get_Vector3_Struct(self);
     sfVector3f b;
 
     if (rb_obj_is_kind_of(rb_other, rb_cVector3)) {
-        b = ((Vector3 *) Get_Vector3_Struct(rb_other))->vec;
+        b = ((Vector3*)Get_Vector3_Struct(rb_other))->vec;
     } else if (RB_TYPE_P(rb_other, T_ARRAY) && RARRAY_LEN(rb_other) >= 3) {
         b = vec3f_from_rb(rb_other);
     } else {
@@ -122,29 +203,56 @@ static VALUE Vector3_eql(VALUE self, VALUE rb_other) {
     return BOOL2RB(a->vec.x == b.x && a->vec.y == b.y && a->vec.z == b.z);
 }
 
+/* call-seq:
+ *   self + other -> Vector3
+ *
+ * +other+ may be a Vector3 or a 3-element Array.
+ *
+ * @return [Vector3] componentwise sum
+ */
 static VALUE Vector3_add(VALUE self, VALUE rb_other) {
-    Vector3 *a = Get_Vector3_Struct(self);
+    Vector3* a = Get_Vector3_Struct(self);
     sfVector3f b = vec3f_from_rb(rb_other);
 
-    return vec3f_to_rb((sfVector3f) {a->vec.x + b.x, a->vec.y + b.y, a->vec.z + b.z});
+    return vec3f_to_rb((sfVector3f){a->vec.x + b.x, a->vec.y + b.y, a->vec.z + b.z});
 }
 
+/* call-seq:
+ *   self - other -> Vector3
+ *
+ * +other+ may be a Vector3 or a 3-element Array.
+ *
+ * @return [Vector3] componentwise difference
+ */
 static VALUE Vector3_sub(VALUE self, VALUE rb_other) {
-    Vector3 *a = Get_Vector3_Struct(self);
+    Vector3* a = Get_Vector3_Struct(self);
     sfVector3f b = vec3f_from_rb(rb_other);
 
-    return vec3f_to_rb((sfVector3f) {a->vec.x - b.x, a->vec.y - b.y, a->vec.z - b.z});
+    return vec3f_to_rb((sfVector3f){a->vec.x - b.x, a->vec.y - b.y, a->vec.z - b.z});
 }
 
+/* call-seq:
+ *   self * scalar -> Vector3
+ *
+ * Multiplies all three components by +scalar+.
+ *
+ * @return [Vector3]
+ */
 static VALUE Vector3_mul(VALUE self, VALUE rb_scalar) {
-    Vector3 *a = Get_Vector3_Struct(self);
+    Vector3* a = Get_Vector3_Struct(self);
     float scalar = NUM2DBL(rb_scalar);
 
-    return vec3f_to_rb((sfVector3f) {a->vec.x * scalar, a->vec.y * scalar, a->vec.z * scalar});
+    return vec3f_to_rb((sfVector3f){a->vec.x * scalar, a->vec.y * scalar, a->vec.z * scalar});
 }
 
+/* call-seq: to_s -> String
+ *
+ * Returns a human-readable +"(x, y, z)"+ representation.
+ *
+ * @return [String] +"(x, y, z)"+
+ */
 static VALUE Vector3_to_s(VALUE self) {
-    Vector3 *a = Get_Vector3_Struct(self);
+    Vector3* a = Get_Vector3_Struct(self);
     char buffer[96];
 
     snprintf(buffer, sizeof(buffer), "(%g, %g, %g)", a->vec.x, a->vec.y, a->vec.z);
@@ -152,8 +260,29 @@ static VALUE Vector3_to_s(VALUE self) {
     return rb_str_new2(buffer);
 }
 
-void Init_Vector3(VALUE rb_module) {
-    rb_cVector3 = rb_define_class_under(rb_module, "Vector3", rb_cObject);
+/* Document-class: SFML::Vector3
+ * A 3D vector of floats, used for positions, sizes and directions in 3D
+ * space (e.g. Listener and SoundSource position/direction/velocity).
+ *
+ * Includes +Enumerable+ and behaves like a 3-element sequence: it responds to
+ * #each and #to_a, and can be compared or combined with a plain
+ * +[x, y, z]+ Array anywhere a Vector3 is accepted.
+ *
+ * @!attribute x
+ *   Returns the X component.
+ *
+ *   @return [Float] the X component
+ * @!attribute y
+ *   Returns the Y component.
+ *
+ *   @return [Float] the Y component
+ * @!attribute z
+ *   Returns the Z component.
+ *
+ *   @return [Float] the Z component
+ */
+void Init_Vector3(VALUE rb_mSFML) {
+    rb_cVector3 = rb_define_class_under(rb_mSFML, "Vector3", rb_cObject);
 
     rb_include_module(rb_cVector3, rb_mEnumerable);
 
@@ -182,15 +311,15 @@ VALUE Get_Klass_Vector3(void) {
     return rb_cVector3;
 }
 
-void *Get_Vector3_Struct(VALUE self) {
-    Vector3 *ptr;
+void* Get_Vector3_Struct(VALUE self) {
+    Vector3* ptr;
     TypedData_Get_Struct(self, Vector3, &Vector3_data_type, ptr);
     return ptr;
 }
 
 sfVector3f vec3f_from_rb(VALUE rb_vec) {
     if (rb_obj_is_kind_of(rb_vec, rb_cVector3)) {
-        return ((Vector3 *) Get_Vector3_Struct(rb_vec))->vec;
+        return ((Vector3*)Get_Vector3_Struct(rb_vec))->vec;
     }
 
     if (RB_TYPE_P(rb_vec, T_ARRAY)) {
@@ -198,20 +327,22 @@ sfVector3f vec3f_from_rb(VALUE rb_vec) {
             raise_invalid_array_length(3);
         }
 
-        return (sfVector3f) {
-            (float) NUM2DBL(rb_ary_entry(rb_vec, 0)),
-            (float) NUM2DBL(rb_ary_entry(rb_vec, 1)),
-            (float) NUM2DBL(rb_ary_entry(rb_vec, 2))
-        };
+        return (sfVector3f){(float)NUM2DBL(rb_ary_entry(rb_vec, 0)),
+                            (float)NUM2DBL(rb_ary_entry(rb_vec, 1)),
+                            (float)NUM2DBL(rb_ary_entry(rb_vec, 2))};
     }
 
     raise_invalid_argument_class(rb_cVector3);
 
-    return (sfVector3f) {0, 0, 0};
+    return (sfVector3f){0, 0, 0};
 }
 
 VALUE vec3f_to_rb(sfVector3f c_vec) {
-    Vector3 *ptr = malloc(sizeof(Vector3));
+    Vector3* ptr = malloc(sizeof(Vector3));
+
+    if (ptr == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate vector");
+    }
 
     ptr->vec = c_vec;
 

data/ext/window/clipboard.c

@@ -5,41 +5,61 @@
 
 #include "core/sfml.h"
 
-static void unicode_char_to_utf8(sfChar32 code, char buffer[4], int *length) {
+static void unicode_char_to_utf8(sfChar32 code, char buffer[4], int* length) {
     if (code < 0x80) {
-        buffer[0] = (char) code;
+        buffer[0] = (char)code;
         *length = 1;
     } else if (code < 0x800) {
-        buffer[0] = (char) (0xC0 | (code >> 6));
-        buffer[1] = (char) (0x80 | (code & 0x3F));
+        buffer[0] = (char)(0xC0 | (code >> 6));
+        buffer[1] = (char)(0x80 | (code & 0x3F));
         *length = 2;
     } else if (code < 0x10000) {
-        buffer[0] = (char) (0xE0 | (code >> 12));
-        buffer[1] = (char) (0x80 | ((code >> 6) & 0x3F));
-        buffer[2] = (char) (0x80 | (code & 0x3F));
+        buffer[0] = (char)(0xE0 | (code >> 12));
+        buffer[1] = (char)(0x80 | ((code >> 6) & 0x3F));
+        buffer[2] = (char)(0x80 | (code & 0x3F));
         *length = 3;
     } else {
-        buffer[0] = (char) (0xF0 | (code >> 18));
-        buffer[1] = (char) (0x80 | ((code >> 12) & 0x3F));
-        buffer[2] = (char) (0x80 | ((code >> 6) & 0x3F));
-        buffer[3] = (char) (0x80 | (code & 0x3F));
+        buffer[0] = (char)(0xF0 | (code >> 18));
+        buffer[1] = (char)(0x80 | ((code >> 12) & 0x3F));
+        buffer[2] = (char)(0x80 | ((code >> 6) & 0x3F));
+        buffer[3] = (char)(0x80 | (code & 0x3F));
         *length = 4;
     }
 }
 
+/* call-seq: string -> String
+ *
+ * Returns the current system clipboard contents as a plain String.
+ *
+ * @return [String] the current system clipboard contents
+ */
 static VALUE Clipboard_get_string(VALUE module) {
-    const char *string = sfClipboard_getString();
+    const char* string = sfClipboard_getString();
 
     return rb_utf8_str_new_cstr(string != NULL ? string : "");
 }
 
+/* call-seq:
+ *   string=(value) -> String
+ *
+ * Sets the system clipboard to +value+.
+ *
+ * @return [String] +value+
+ */
 static VALUE Clipboard_set_string(VALUE module, VALUE rb_text) {
     sfClipboard_setString(StringValueCStr(rb_text));
     return rb_text;
 }
 
+/* call-seq: unicode_string -> String
+ *
+ * Returns the current system clipboard contents, decoding UTF-32 to UTF-8.
+ *
+ * @return [String] the current system clipboard contents, decoded from
+ *   UTF-32 to a UTF-8 Ruby String
+ */
 static VALUE Clipboard_get_unicode_string(VALUE module) {
-    const sfChar32 *chars = sfClipboard_getUnicodeString();
+    const sfChar32* chars = sfClipboard_getUnicodeString();
     VALUE string = rb_utf8_str_new("", 0);
 
     if (chars == NULL) {
@@ -57,10 +77,17 @@ static VALUE Clipboard_get_unicode_string(VALUE module) {
     return string;
 }
 
+/* call-seq:
+ *   unicode_string=(value) -> String
+ *
+ * Sets the system clipboard to +value+, encoding it to UTF-32 first.
+ *
+ * @return [String] +value+
+ */
 static VALUE Clipboard_set_unicode_string(VALUE module, VALUE rb_text) {
     VALUE codepoints;
     long count;
-    sfChar32 *chars;
+    sfChar32* chars;
 
     StringValue(rb_text);
     codepoints = rb_funcall(rb_text, rb_intern("codepoints"), 0);
@@ -68,7 +95,7 @@ static VALUE Clipboard_set_unicode_string(VALUE module, VALUE rb_text) {
     chars = ALLOC_N(sfChar32, count + 1);
 
     for (long i = 0; i < count; i++) {
-        chars[i] = (sfChar32) NUM2UINT(rb_ary_entry(codepoints, i));
+        chars[i] = (sfChar32)NUM2UINT(rb_ary_entry(codepoints, i));
     }
 
     chars[count] = 0;
@@ -79,8 +106,11 @@ static VALUE Clipboard_set_unicode_string(VALUE module, VALUE rb_text) {
     return rb_text;
 }
 
-void Init_Clipboard(VALUE rb_module) {
-    VALUE rb_mClipboard = rb_define_module_under(rb_module, "Clipboard");
+/* Document-module: SFML::Clipboard
+ * Access to the system clipboard, as plain text or Unicode text.
+ */
+void Init_Clipboard(VALUE rb_mSFML) {
+    VALUE rb_mClipboard = rb_define_module_under(rb_mSFML, "Clipboard");
 
     rb_define_module_function(rb_mClipboard, "string", Clipboard_get_string, 0);
     rb_define_module_function(rb_mClipboard, "string=", Clipboard_set_string, 1);

data/ext/window/context.c

@@ -8,24 +8,31 @@
 
 static VALUE rb_cContext;
 
-static void Context_free(void *ptr) {
+static void Context_free(void* ptr) {
     sfContext_destroy(ptr);
 }
 
 static const rb_data_type_t Context_data_type = {
     .wrap_struct_name = "SFML::Context",
     .function = {.dmark = NULL, .dfree = Context_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static sfContext *Get_Context_Struct(VALUE self) {
-    sfContext *ptr;
+static sfContext* Get_Context_Struct(VALUE self) {
+    sfContext* ptr;
     TypedData_Get_Struct(self, sfContext, &Context_data_type, ptr);
     return ptr;
 }
 
+/* call-seq:
+ *   Context.new -> Context
+ *
+ * Creates and activates a new OpenGL context on the current thread.
+ *
+ * @return [Context]
+ * @raise [RuntimeError] if context creation fails
+ */
 static VALUE Context_new(VALUE klass) {
-    sfContext *context = sfContext_create();
+    sfContext* context = sfContext_create();
     VALUE self;
 
     if (context == NULL) {
@@ -37,28 +44,71 @@ static VALUE Context_new(VALUE klass) {
     return self;
 }
 
+/* call-seq:
+ *   extension_available?(name) -> true or false
+ *
+ * Returns +true+ if the OpenGL extension +name+ is available in the currently
+ * active context.
+ *
+ * @return [Boolean] whether the OpenGL extension +name+ is available in the
+ *   currently active context
+ */
 static VALUE Context_extension_available(VALUE klass, VALUE rb_name) {
     return BOOL2RB(sfContext_isExtensionAvailable(StringValueCStr(rb_name)));
 }
 
+/* call-seq:
+ *   active=(value) -> true or false
+ *
+ * Activates or deactivates this context as the current one on the calling
+ * thread.
+ *
+ * @return [Boolean] whether activation succeeded
+ */
 static VALUE Context_set_active(VALUE self, VALUE rb_active) {
     return BOOL2RB(sfContext_setActive(Get_Context_Struct(self), RTEST(rb_active)));
 }
 
+/* call-seq:
+ *   function(name) -> Integer
+ *
+ * Returns the address of the OpenGL function +name+ as an Integer, or 0 when
+ * it is not available.
+ *
+ * @return [Integer] the address of the OpenGL function +name+, as a raw
+ *   pointer value, or 0 if it is not available
+ */
 static VALUE Context_get_function(VALUE klass, VALUE rb_name) {
-    return ULL2NUM((unsigned long long) (uintptr_t) sfContext_getFunction(StringValueCStr(rb_name)));
+    return ULL2NUM((unsigned long long)(uintptr_t)sfContext_getFunction(StringValueCStr(rb_name)));
 }
 
+/* call-seq: settings -> ContextSettings
+ *
+ * Returns the settings this context was created with.
+ *
+ * @return [ContextSettings] the settings this context was created with
+ */
 static VALUE Context_get_settings(VALUE self) {
     return context_settings_to_rb(sfContext_getSettings(Get_Context_Struct(self)));
 }
 
+/* call-seq: active_context_id -> Integer
+ *
+ * Returns the unique identifier of the currently active context on the
+ * calling thread, or 0 if none is active.
+ *
+ * @return [Integer] the unique identifier of the currently active context on
+ *   the calling thread, or 0 if none is active
+ */
 static VALUE Context_active_context_id(VALUE klass) {
     return ULL2NUM(sfContext_getActiveContextId());
 }
 
-void Init_Context(VALUE rb_module) {
-    rb_cContext = rb_define_class_under(rb_module, "Context", rb_cObject);
+/* Document-class: SFML::Context
+ * A raw OpenGL context, usable off-screen or on a thread without a Window.
+ */
+void Init_Context(VALUE rb_mSFML) {
+    rb_cContext = rb_define_class_under(rb_mSFML, "Context", rb_cObject);
 
     rb_define_singleton_method(rb_cContext, "new", Context_new, 0);
     rb_define_singleton_method(rb_cContext, "extension_available?", Context_extension_available, 1);