sfml3-rb 0.2.2 → 0.3.1

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,59 +8,112 @@
 
 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;
 }
 
-static VALUE Context_new(VALUE klass) {
-    sfContext *context = sfContext_create();
-    VALUE self;
+static VALUE Context_alloc(VALUE klass) {
+    sfContext* context = sfContext_create();
 
     if (context == NULL) {
         rb_raise(rb_eRuntimeError, "failed to create context");
     }
 
-    self = TypedData_Wrap_Struct(klass, &Context_data_type, context);
+    return TypedData_Wrap_Struct(klass, &Context_data_type, context);
+}
 
+/* 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_initialize(VALUE self) {
     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_alloc_func(rb_cContext, Context_alloc);
+    rb_define_method(rb_cContext, "initialize", Context_initialize, 0);
 
-    rb_define_singleton_method(rb_cContext, "new", Context_new, 0);
     rb_define_singleton_method(rb_cContext, "extension_available?", Context_extension_available, 1);
     rb_define_singleton_method(rb_cContext, "function", Context_get_function, 1);
     rb_define_singleton_method(rb_cContext, "active_context_id", Context_active_context_id, 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,57 @@ 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};
+static VALUE ContextSettings_alloc(VALUE klass) {
+    ContextSettings* ptr = malloc(sizeof(ContextSettings));
+
+    if (ptr == NULL) {
+        rb_raise(rb_eNoMemError, "failed to allocate context settings");
+    }
+
+    ptr->settings = (sfContextSettings){0, 0, 0, 1, 1, sfContextDefault, false};
+
+    return TypedData_Wrap_Struct(klass, &ContextSettings_data_type, ptr);
+}
+
+/* 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_initialize(int argc, VALUE* argv, VALUE self) {
+    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 +100,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;
@@ -97,28 +119,42 @@ static VALUE ContextSettings_new(int argc, VALUE *argv, VALUE klass) {    sfCont
         settings.sRgbCapable = RTEST(rb_srgb);
     }
 
-    self = ContextSettings_wrap(settings);
+    ((ContextSettings*)Get_ContextSettings_Struct(self))->settings = settings;
 
     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 +172,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 +208,78 @@ 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);
-
-    rb_define_singleton_method(rb_cContextSettings, "new", ContextSettings_new, -1);
+/* 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_alloc_func(rb_cContextSettings, ContextSettings_alloc);
+    rb_define_method(rb_cContextSettings, "initialize", ContextSettings_initialize, -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 +287,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,56 @@ 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);
+static VALUE Cursor_alloc(VALUE klass) {
+    (void)klass;
+    rb_raise(rb_eNotImpError, "use Cursor.from_system or Cursor.from_pixels");
+}
+
+/* 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_alloc_func(rb_cCursor, Cursor_alloc);
 
     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 +85,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;
 }