sfml3-rb 0.2.2 → 0.3.0

data/ext/window/context_settings.c

@@ -13,25 +13,28 @@ typedef struct {
 
 static VALUE rb_cContextSettings;
 
-static void ContextSettings_free(void *ptr) {
+static void ContextSettings_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t ContextSettings_data_type = {
     .wrap_struct_name = "SFML::ContextSettings",
     .function = {.dmark = NULL, .dfree = ContextSettings_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 static VALUE ContextSettings_wrap(sfContextSettings settings) {
-    ContextSettings *ptr = malloc(sizeof(ContextSettings));
+    ContextSettings* ptr = malloc(sizeof(ContextSettings));
+
+    if (ptr == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate context settings");
+    }
 
     ptr->settings = settings;
 
     return TypedData_Wrap_Struct(rb_cContextSettings, &ContextSettings_data_type, ptr);
 }
 
-static const char *context_flag_name(VALUE value) {
+static const char* context_flag_name(VALUE value) {
     if (SYMBOL_P(value)) {
         return rb_id2name(SYM2ID(value));
     }
@@ -39,38 +42,46 @@ static const char *context_flag_name(VALUE value) {
     return StringValueCStr(value);
 }
 
-static VALUE ContextSettings_new(int argc, VALUE *argv, VALUE klass) {    sfContextSettings settings = {0, 0, 0, 1, 1, sfContextDefault, false};
+/* call-seq:
+ *   ContextSettings.new(depth_bits = 0, stencil_bits = 0, antialiasing_level = 0, major_version =
+ * 1, minor_version = 1, flags = :default, srgb_capable = false) -> ContextSettings
+ *
+ * @return [ContextSettings]
+ * @raise [ArgumentError] if +flags+ contains an unknown attribute name
+ */
+static VALUE ContextSettings_new(int argc, VALUE* argv, VALUE klass) {
+    sfContextSettings settings = {0, 0, 0, 1, 1, sfContextDefault, false};
     VALUE rb_depth, rb_stencil, rb_antialiasing, rb_major, rb_minor, rb_flags, rb_srgb;
     VALUE self;
 
-    rb_scan_args(argc, argv, "07", &rb_depth, &rb_stencil, &rb_antialiasing, &rb_major, &rb_minor, &rb_flags,
-                 &rb_srgb);
+    rb_scan_args(argc, argv, "07", &rb_depth, &rb_stencil, &rb_antialiasing, &rb_major, &rb_minor,
+                 &rb_flags, &rb_srgb);
 
     if (!NIL_P(rb_depth)) {
-        settings.depthBits = (unsigned int) NUM2UINT(rb_depth);
+        settings.depthBits = (unsigned int)NUM2UINT(rb_depth);
     }
 
     if (!NIL_P(rb_stencil)) {
-        settings.stencilBits = (unsigned int) NUM2UINT(rb_stencil);
+        settings.stencilBits = (unsigned int)NUM2UINT(rb_stencil);
     }
 
     if (!NIL_P(rb_antialiasing)) {
-        settings.antiAliasingLevel = (unsigned int) NUM2UINT(rb_antialiasing);
+        settings.antiAliasingLevel = (unsigned int)NUM2UINT(rb_antialiasing);
     }
 
     if (!NIL_P(rb_major)) {
-        settings.majorVersion = (unsigned int) NUM2UINT(rb_major);
+        settings.majorVersion = (unsigned int)NUM2UINT(rb_major);
     }
 
     if (!NIL_P(rb_minor)) {
-        settings.minorVersion = (unsigned int) NUM2UINT(rb_minor);
+        settings.minorVersion = (unsigned int)NUM2UINT(rb_minor);
     }
 
     if (!NIL_P(rb_flags)) {
         uint32_t flags = 0;
 
         if (RB_INTEGER_TYPE_P(rb_flags)) {
-            flags = (uint32_t) NUM2UINT(rb_flags);
+            flags = (uint32_t)NUM2UINT(rb_flags);
         } else if (SYMBOL_P(rb_flags) || RB_TYPE_P(rb_flags, T_STRING)) {
             rb_flags = rb_ary_new_from_args(1, rb_flags);
         }
@@ -78,7 +89,7 @@ static VALUE ContextSettings_new(int argc, VALUE *argv, VALUE klass) {    sfCont
         if (RB_TYPE_P(rb_flags, T_ARRAY)) {
             for (long i = 0; i < RARRAY_LEN(rb_flags); i++) {
                 VALUE entry = rb_ary_entry(rb_flags, i);
-                const char *name = context_flag_name(entry);
+                const char* name = context_flag_name(entry);
 
                 if (strcmp(name, "core") == 0) {
                     flags |= sfContextCore;
@@ -102,23 +113,37 @@ static VALUE ContextSettings_new(int argc, VALUE *argv, VALUE klass) {    sfCont
     return self;
 }
 
-#define CONTEXT_SETTINGS_UINT_ACCESSOR(name, field)                          \
-    static VALUE ContextSettings_get_##name(VALUE self) {                    \
-        return UINT2NUM(((ContextSettings *) Get_ContextSettings_Struct(self))->settings.field); \
-    }                                                                        \
-    static VALUE ContextSettings_set_##name(VALUE self, VALUE rb_value) {     \
-        ((ContextSettings *) Get_ContextSettings_Struct(self))->settings.field = (unsigned int) NUM2UINT(rb_value); \
-        return rb_value;                                                     \
+#define CONTEXT_SETTINGS_UINT_ACCESSOR(name, field)                                                \
+    static VALUE ContextSettings_get_##name(VALUE self) {                                          \
+        return UINT2NUM(((ContextSettings*)Get_ContextSettings_Struct(self))->settings.field);     \
+    }                                                                                              \
+    static VALUE ContextSettings_set_##name(VALUE self, VALUE rb_value) {                          \
+        rb_check_frozen(self);                                                                     \
+        ((ContextSettings*)Get_ContextSettings_Struct(self))->settings.field =                     \
+            (unsigned int)NUM2UINT(rb_value);                                                      \
+        return rb_value;                                                                           \
     }
 
+/* Macro-generated accessor pairs (depth_bits, stencil_bits,
+ * antialiasing_level, major_version, minor_version); documented together via
+ * Document-class's @!attribute tags below since the comment can't attach to
+ * an individual macro expansion. */
 CONTEXT_SETTINGS_UINT_ACCESSOR(depth_bits, depthBits)
 CONTEXT_SETTINGS_UINT_ACCESSOR(stencil_bits, stencilBits)
 CONTEXT_SETTINGS_UINT_ACCESSOR(antialiasing_level, antiAliasingLevel)
 CONTEXT_SETTINGS_UINT_ACCESSOR(major_version, majorVersion)
 CONTEXT_SETTINGS_UINT_ACCESSOR(minor_version, minorVersion)
 
+/* Document-method: SFML::ContextSettings#attribute_flags
+ * call-seq: attribute_flags -> Array<Symbol>
+ *
+ * Returns the context attribute flags as a list of symbols.
+ *
+ * @return [Array<Symbol>] a subset of +[:core, :debug]+, or +[:default]+ if
+ *   neither is set
+ */
 static VALUE ContextSettings_get_attribute_flags(VALUE self) {
-    uint32_t flags = ((ContextSettings *) Get_ContextSettings_Struct(self))->settings.attributeFlags;
+    uint32_t flags = ((ContextSettings*)Get_ContextSettings_Struct(self))->settings.attributeFlags;
     VALUE array = rb_ary_new();
 
     if ((flags & sfContextCore) != 0) {
@@ -136,18 +161,28 @@ static VALUE ContextSettings_get_attribute_flags(VALUE self) {
     return array;
 }
 
+/* Document-method: SFML::ContextSettings#attribute_flags=
+ * call-seq: attribute_flags = value -> value
+ *
+ * Sets the context attribute flags from +value+, an Integer bitmask or a
+ * Symbol/Array of +:core+ and +:debug+.
+ *
+ * @return [Integer, Array<Symbol>] +value+
+ */
 static VALUE ContextSettings_set_attribute_flags(VALUE self, VALUE rb_value) {
-    ContextSettings *settings = Get_ContextSettings_Struct(self);
+    ContextSettings* settings = Get_ContextSettings_Struct(self);
     uint32_t flags = 0;
 
+    rb_check_frozen(self);
+
     if (RB_INTEGER_TYPE_P(rb_value)) {
-        flags = (uint32_t) NUM2UINT(rb_value);
+        flags = (uint32_t)NUM2UINT(rb_value);
     } else {
         VALUE array = RB_TYPE_P(rb_value, T_ARRAY) ? rb_value : rb_ary_new_from_args(1, rb_value);
 
         for (long i = 0; i < RARRAY_LEN(array); i++) {
             VALUE entry = rb_ary_entry(array, i);
-            const char *name = context_flag_name(entry);
+            const char* name = context_flag_name(entry);
 
             if (strcmp(name, "core") == 0) {
                 flags |= sfContextCore;
@@ -162,34 +197,77 @@ static VALUE ContextSettings_set_attribute_flags(VALUE self, VALUE rb_value) {
     return rb_value;
 }
 
+/* call-seq: srgb_capable? -> true or false
+ *
+ * Returns +true+ if the context was created with sRGB-capable framebuffers.
+ *
+ * @return [Boolean]
+ */
 static VALUE ContextSettings_get_srgb(VALUE self) {
-    return BOOL2RB(((ContextSettings *) Get_ContextSettings_Struct(self))->settings.sRgbCapable);
+    return BOOL2RB(((ContextSettings*)Get_ContextSettings_Struct(self))->settings.sRgbCapable);
 }
 
+/* call-seq:
+ *   srgb_capable=(value) -> true or false
+ *
+ * Requests sRGB-capable framebuffers when +value+ is +true+.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE ContextSettings_set_srgb(VALUE self, VALUE rb_value) {
-    ((ContextSettings *) Get_ContextSettings_Struct(self))->settings.sRgbCapable = RTEST(rb_value);
+    rb_check_frozen(self);
+    ((ContextSettings*)Get_ContextSettings_Struct(self))->settings.sRgbCapable = RTEST(rb_value);
     return rb_value;
 }
 
-void Init_ContextSettings(VALUE rb_module) {
-    rb_cContextSettings = rb_define_class_under(rb_module, "ContextSettings", rb_cObject);
+/* Document-class: SFML::ContextSettings
+ * Settings requested when creating a Window or Context: depth/stencil buffer
+ * sizes, antialiasing level, requested OpenGL version, and attribute flags.
+ *
+ * The +depth_bits+/+stencil_bits+/+antialiasing_level+/+major_version+/
+ * +minor_version+ accessors are generated through a shared C macro, so
+ * (unlike this class's other accessors) they are documented here rather than
+ * above their own definitions.
+ *
+ * @!attribute depth_bits
+ *   Number of bits per pixel requested for the depth buffer.
+ *   @return [Integer] requested depth buffer bits per pixel
+ * @!attribute stencil_bits
+ *   Number of bits per pixel requested for the stencil buffer.
+ *   @return [Integer] requested stencil buffer bits per pixel
+ * @!attribute antialiasing_level
+ *   Requested antialiasing level.
+ *   @return [Integer] requested antialiasing level
+ * @!attribute major_version
+ *   Requested OpenGL major version.
+ *   @return [Integer] requested OpenGL major version
+ * @!attribute minor_version
+ *   Requested OpenGL minor version.
+ *   @return [Integer] requested OpenGL minor version
+ */
+void Init_ContextSettings(VALUE rb_mSFML) {
+    rb_cContextSettings = rb_define_class_under(rb_mSFML, "ContextSettings", rb_cObject);
 
     rb_define_singleton_method(rb_cContextSettings, "new", ContextSettings_new, -1);
 
     rb_define_method(rb_cContextSettings, "depth_bits", ContextSettings_get_depth_bits, 0);
     rb_define_method(rb_cContextSettings, "stencil_bits", ContextSettings_get_stencil_bits, 0);
-    rb_define_method(rb_cContextSettings, "antialiasing_level", ContextSettings_get_antialiasing_level, 0);
+    rb_define_method(rb_cContextSettings, "antialiasing_level",
+                     ContextSettings_get_antialiasing_level, 0);
     rb_define_method(rb_cContextSettings, "major_version", ContextSettings_get_major_version, 0);
     rb_define_method(rb_cContextSettings, "minor_version", ContextSettings_get_minor_version, 0);
-    rb_define_method(rb_cContextSettings, "attribute_flags", ContextSettings_get_attribute_flags, 0);
+    rb_define_method(rb_cContextSettings, "attribute_flags", ContextSettings_get_attribute_flags,
+                     0);
     rb_define_method(rb_cContextSettings, "srgb_capable?", ContextSettings_get_srgb, 0);
 
     rb_define_method(rb_cContextSettings, "depth_bits=", ContextSettings_set_depth_bits, 1);
     rb_define_method(rb_cContextSettings, "stencil_bits=", ContextSettings_set_stencil_bits, 1);
-    rb_define_method(rb_cContextSettings, "antialiasing_level=", ContextSettings_set_antialiasing_level, 1);
+    rb_define_method(rb_cContextSettings,
+                     "antialiasing_level=", ContextSettings_set_antialiasing_level, 1);
     rb_define_method(rb_cContextSettings, "major_version=", ContextSettings_set_major_version, 1);
     rb_define_method(rb_cContextSettings, "minor_version=", ContextSettings_set_minor_version, 1);
-    rb_define_method(rb_cContextSettings, "attribute_flags=", ContextSettings_set_attribute_flags, 1);
+    rb_define_method(rb_cContextSettings, "attribute_flags=", ContextSettings_set_attribute_flags,
+                     1);
     rb_define_method(rb_cContextSettings, "srgb_capable=", ContextSettings_set_srgb, 1);
 }
 
@@ -197,22 +275,22 @@ VALUE Get_Klass_ContextSettings(void) {
     return rb_cContextSettings;
 }
 
-void *Get_ContextSettings_Struct(VALUE self) {
-    ContextSettings *ptr;
+void* Get_ContextSettings_Struct(VALUE self) {
+    ContextSettings* ptr;
     TypedData_Get_Struct(self, ContextSettings, &ContextSettings_data_type, ptr);
     return ptr;
 }
 
 sfContextSettings context_settings_from_rb(VALUE rb_settings) {
     if (NIL_P(rb_settings)) {
-        return (sfContextSettings) {0, 0, 0, 1, 1, sfContextDefault, false};
+        return (sfContextSettings){0, 0, 0, 1, 1, sfContextDefault, false};
     }
 
     if (!rb_obj_is_kind_of(rb_settings, rb_cContextSettings)) {
         raise_invalid_argument_class(rb_cContextSettings);
     }
 
-    return ((ContextSettings *) Get_ContextSettings_Struct(rb_settings))->settings;
+    return ((ContextSettings*)Get_ContextSettings_Struct(rb_settings))->settings;
 }
 
 VALUE context_settings_to_rb(sfContextSettings settings) {

data/ext/window/cursor.c

@@ -9,17 +9,16 @@
 
 static VALUE rb_cCursor;
 
-static void Cursor_free(void *ptr) {
+static void Cursor_free(void* ptr) {
     sfCursor_destroy(ptr);
 }
 
 static const rb_data_type_t Cursor_data_type = {
     .wrap_struct_name = "SFML::Cursor",
     .function = {.dmark = NULL, .dfree = Cursor_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE Cursor_wrap(sfCursor *cursor) {
+static VALUE Cursor_wrap(sfCursor* cursor) {
     if (cursor == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create cursor");
     }
@@ -27,19 +26,50 @@ static VALUE Cursor_wrap(sfCursor *cursor) {
     return TypedData_Wrap_Struct(rb_cCursor, &Cursor_data_type, cursor);
 }
 
+/* call-seq:
+ *   Cursor.from_pixels(pixels, size, hotspot) -> Cursor
+ *
+ * Creates a cursor from RGBA32 pixel data (+width * height * 4+ bytes,
+ * row-major, top-to-bottom).
+ *
+ * @return [Cursor]
+ * @raise [ArgumentError] if +pixels+ is shorter than required
+ * @raise [RuntimeError] if cursor creation fails
+ */
 static VALUE Cursor_from_pixels(VALUE klass, VALUE rb_pixels, VALUE rb_size, VALUE rb_hotspot) {
+    sfVector2u size = vec2u_from_rb(rb_size);
+    size_t expected = (size_t)size.x * size.y * 4;
+
     StringValue(rb_pixels);
 
-    return Cursor_wrap(sfCursor_createFromPixels((const uint8_t *) RSTRING_PTR(rb_pixels), vec2u_from_rb(rb_size),
+    if ((size_t)RSTRING_LEN(rb_pixels) < expected) {
+        rb_raise(rb_eArgError, "pixel data too short: expected %zu bytes", expected);
+    }
+
+    return Cursor_wrap(sfCursor_createFromPixels((const uint8_t*)RSTRING_PTR(rb_pixels), size,
                                                  vec2u_from_rb(rb_hotspot)));
 }
 
+/* call-seq:
+ *   Cursor.from_system(type) -> Cursor
+ *
+ * Creates a cursor from a native system cursor type (a Symbol, e.g.
+ * +:arrow+, +:hand+, +:crosshair+; see the cursor type symbols this binding
+ * accepts).
+ *
+ * @return [Cursor]
+ * @raise [RuntimeError] if cursor creation fails
+ */
 static VALUE Cursor_from_system(VALUE klass, VALUE rb_type) {
     return Cursor_wrap(sfCursor_createFromSystem(cursor_type_from_rb(rb_type)));
 }
 
-void Init_Cursor(VALUE rb_module) {
-    rb_cCursor = rb_define_class_under(rb_module, "Cursor", rb_cObject);
+/* Document-class: SFML::Cursor
+ * A native mouse cursor, either built from raw pixel data or one of the
+ * platform's built-in system cursors. Assign to Window#cursor= to apply.
+ */
+void Init_Cursor(VALUE rb_mSFML) {
+    rb_cCursor = rb_define_class_under(rb_mSFML, "Cursor", rb_cObject);
 
     rb_define_singleton_method(rb_cCursor, "from_pixels", Cursor_from_pixels, 3);
     rb_define_singleton_method(rb_cCursor, "from_system", Cursor_from_system, 1);
@@ -49,8 +79,8 @@ VALUE Get_Klass_Cursor(void) {
     return rb_cCursor;
 }
 
-const sfCursor *Get_Cursor_Struct(VALUE self) {
-    sfCursor *ptr;
+const sfCursor* Get_Cursor_Struct(VALUE self) {
+    sfCursor* ptr;
     TypedData_Get_Struct(self, sfCursor, &Cursor_data_type, ptr);
     return ptr;
 }