sfml3-rb 0.2.2 → 0.3.1

data/ext/graphics/font.c

@@ -10,17 +10,16 @@
 
 static VALUE rb_cFont;
 
-static void Font_free(void *ptr) {
+static void Font_free(void* ptr) {
     sfFont_destroy(ptr);
 }
 
 static const rb_data_type_t Font_data_type = {
     .wrap_struct_name = "SFML::Font",
     .function = {.dmark = NULL, .dfree = Font_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
-static VALUE Font_wrap(VALUE klass, sfFont *font) {
+static VALUE Font_wrap(VALUE klass, sfFont* font) {
     if (font == NULL) {
         rb_raise(rb_eRuntimeError, "failed to load font");
     }
@@ -28,30 +27,69 @@ static VALUE Font_wrap(VALUE klass, sfFont *font) {
     return TypedData_Wrap_Struct(klass, &Font_data_type, font);
 }
 
+/* call-seq:
+ *   Font.from_file(path) -> Font
+ *
+ * Loads a font from the font file at +filename+.
+ *
+ * @return [Font]
+ * @raise [RuntimeError] if the file cannot be loaded
+ */
 static VALUE Font_from_file(VALUE klass, VALUE rb_path) {
     return Font_wrap(klass, sfFont_createFromFile(StringValueCStr(rb_path)));
 }
 
+/* call-seq:
+ *   Font.from_memory(data) -> Font
+ *
+ * Loads a font from an in-memory font file buffer.
+ *
+ * @return [Font]
+ * @raise [RuntimeError] if the font data cannot be parsed
+ */
 static VALUE Font_from_memory(VALUE klass, VALUE rb_data) {
     StringValue(rb_data);
 
-    return Font_wrap(klass, sfFont_createFromMemory(RSTRING_PTR(rb_data), (size_t) RSTRING_LEN(rb_data)));
+    return Font_wrap(klass,
+                     sfFont_createFromMemory(RSTRING_PTR(rb_data), (size_t)RSTRING_LEN(rb_data)));
 }
 
+/* call-seq:
+ *   Font.from_stream(stream) -> Font
+ *
+ * +stream+ is any object responding to the InputStream protocol (see
+ * InputStream).
+ *
+ * @return [Font]
+ * @raise [RuntimeError] if the font cannot be loaded
+ */
 static VALUE Font_from_stream(VALUE klass, VALUE rb_stream) {
     VALUE holder = Qnil;
-    sfInputStream *stream = input_stream_from_rb(rb_stream, &holder);
+    sfInputStream* stream = input_stream_from_rb(rb_stream, &holder);
 
-    (void) holder;
+    (void)holder;
 
     return Font_wrap(klass, sfFont_createFromStream(stream));
 }
 
+/* call-seq: copy -> Font
+ *
+ * Returns a deep copy of the object.
+ *
+ * @return [Font] an independent copy
+ */
 static VALUE Font_copy(VALUE self) {
     return Font_wrap(Get_Klass_Font(), sfFont_copy(Get_Font_Struct(self)));
 }
 
-static VALUE Font_get_glyph(int argc, VALUE *argv, VALUE self) {
+/* call-seq:
+ *   glyph(codepoint, size, bold=false, outline_thickness=0) -> Glyph
+ *
+ * Returns the glyph for +codepoint+ at the given +character_size+.
+ *
+ * @return [Glyph]
+ */
+static VALUE Font_get_glyph(int argc, VALUE* argv, VALUE self) {
     VALUE rb_codepoint, rb_size, rb_bold, rb_outline;
     bool bold = false;
     float outline = 0;
@@ -66,58 +104,139 @@ static VALUE Font_get_glyph(int argc, VALUE *argv, VALUE self) {
         outline = NUM2DBL(rb_outline);
     }
 
-    return glyph_from_c(sfFont_getGlyph(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_codepoint),
-                                        (unsigned int) NUM2UINT(rb_size), bold, outline));
+    return glyph_from_c(sfFont_getGlyph(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_codepoint),
+                                        (unsigned int)NUM2UINT(rb_size), bold, outline));
 }
 
+/* call-seq: has_glyph?(codepoint) -> true or false
+ *
+ * Returns +true+ if the font contains a glyph for +codepoint+.
+ *
+ * @return [Boolean] whether this font has a glyph for the given Unicode
+ *   codepoint
+ */
 static VALUE Font_has_glyph(VALUE self, VALUE rb_codepoint) {
-    return BOOL2RB(sfFont_hasGlyph(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_codepoint)));
+    return BOOL2RB(sfFont_hasGlyph(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_codepoint)));
 }
 
+/* call-seq: kerning(first, second, size) -> Float
+ *
+ * Returns the kerning between two code points at the given size.
+ *
+ * @return [Float] the kerning offset between two consecutive glyphs at the
+ *   given character size
+ */
 static VALUE Font_get_kerning(VALUE self, VALUE rb_first, VALUE rb_second, VALUE rb_size) {
-    return DBL2NUM(sfFont_getKerning(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_first),
-                                     (uint32_t) NUM2UINT(rb_second), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(sfFont_getKerning(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_first),
+                                     (uint32_t)NUM2UINT(rb_second),
+                                     (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: bold_kerning(first, second, size) -> Float
+ *
+ * Returns the kerning of the bold variant between two code points.
+ *
+ * @return [Float] the kerning offset between two consecutive bold glyphs at
+ *   the given character size
+ */
 static VALUE Font_get_bold_kerning(VALUE self, VALUE rb_first, VALUE rb_second, VALUE rb_size) {
-    return DBL2NUM(sfFont_getBoldKerning(Get_Font_Struct(self), (uint32_t) NUM2UINT(rb_first),
-                                         (uint32_t) NUM2UINT(rb_second), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(sfFont_getBoldKerning(Get_Font_Struct(self), (uint32_t)NUM2UINT(rb_first),
+                                         (uint32_t)NUM2UINT(rb_second),
+                                         (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: line_spacing(size) -> Float
+ *
+ * Returns the line spacing for the given character size.
+ *
+ * @return [Float] the distance between two consecutive lines at the given
+ *   character size
+ */
 static VALUE Font_get_line_spacing(VALUE self, VALUE rb_size) {
-    return DBL2NUM(sfFont_getLineSpacing(Get_Font_Struct(self), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(sfFont_getLineSpacing(Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: underline_position(size) -> Float
+ *
+ * Returns the position of the underline for the given size.
+ *
+ * @return [Float] the position of the underline, relative to the baseline,
+ *   at the given character size
+ */
 static VALUE Font_get_underline_position(VALUE self, VALUE rb_size) {
-    return DBL2NUM(sfFont_getUnderlinePosition(Get_Font_Struct(self), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(
+        sfFont_getUnderlinePosition(Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: underline_thickness(size) -> Float
+ *
+ * Returns the thickness of the underline for the given size.
+ *
+ * @return [Float] the thickness of the underline at the given character size
+ */
 static VALUE Font_get_underline_thickness(VALUE self, VALUE rb_size) {
-    return DBL2NUM(sfFont_getUnderlineThickness(Get_Font_Struct(self), (unsigned int) NUM2UINT(rb_size)));
+    return DBL2NUM(
+        sfFont_getUnderlineThickness(Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq: texture(size) -> Texture
+ *
+ * Returns the texture atlas holding rendered glyphs for the given size.
+ *
+ * @return [Texture] the texture atlas holding rendered glyphs for the given
+ *   character size. Owned by the font; do not modify or free it directly.
+ */
 static VALUE Font_get_texture(VALUE self, VALUE rb_size) {
-    return texture_from_borrowed(sfFont_getTexture((sfFont *) Get_Font_Struct(self),
-                                                   (unsigned int) NUM2UINT(rb_size)));
+    return texture_from_borrowed(
+        sfFont_getTexture((sfFont*)Get_Font_Struct(self), (unsigned int)NUM2UINT(rb_size)));
 }
 
+/* call-seq:
+ *   smooth=(value) -> Boolean
+ *
+ * Enables or disables smooth rendering.
+ *
+ * @return [Boolean] +value+
+ */
 static VALUE Font_set_smooth(VALUE self, VALUE rb_smooth) {
-    sfFont_setSmooth((sfFont *) Get_Font_Struct(self), RTEST(rb_smooth));
+    sfFont_setSmooth((sfFont*)Get_Font_Struct(self), RTEST(rb_smooth));
     return rb_smooth;
 }
 
+/* call-seq: smooth? -> true or false
+ *
+ * Returns +true+ if smooth rendering is enabled.
+ *
+ * @return [Boolean]
+ */
 static VALUE Font_is_smooth(VALUE self) {
     return BOOL2RB(sfFont_isSmooth(Get_Font_Struct(self)));
 }
 
+/* call-seq: info -> String
+ *
+ * Returns the font's family name.
+ *
+ * @return [String] the font family name
+ */
 static VALUE Font_get_info(VALUE self) {
     sfFontInfo info = sfFont_getInfo(Get_Font_Struct(self));
 
     return rb_str_new_cstr(info.family != NULL ? info.family : "");
 }
 
-void Init_Font(VALUE rb_module) {
-    rb_cFont = rb_define_class_under(rb_module, "Font", rb_cObject);
+static VALUE Font_alloc(VALUE klass) {
+    (void)klass;
+    rb_raise(rb_eNotImpError, "use Font.from_file, Font.from_memory or Font.from_stream");
+}
+
+/* Document-class: SFML::Font
+ * A font face used to render text, loaded from a file, memory buffer or
+ * stream. Glyphs are rasterized and cached lazily per character size.
+ */
+void Init_Font(VALUE rb_mSFML) {
+    rb_cFont = rb_define_class_under(rb_mSFML, "Font", rb_cObject);
+    rb_define_alloc_func(rb_cFont, Font_alloc);
 
     rb_define_singleton_method(rb_cFont, "from_file", Font_from_file, 1);
     rb_define_singleton_method(rb_cFont, "from_memory", Font_from_memory, 1);
@@ -141,8 +260,8 @@ VALUE Get_Klass_Font(void) {
     return rb_cFont;
 }
 
-const sfFont *Get_Font_Struct(VALUE self) {
-    sfFont *ptr;
+const sfFont* Get_Font_Struct(VALUE self) {
+    sfFont* ptr;
     TypedData_Get_Struct(self, sfFont, &Font_data_type, ptr);
     return ptr;
 }

data/ext/graphics/glyph.c

@@ -11,44 +11,74 @@ typedef struct {
 
 static VALUE rb_cGlyph;
 
-static void Glyph_free(void *ptr) {
+static void Glyph_free(void* ptr) {
     free(ptr);
 }
 
 static const rb_data_type_t Glyph_data_type = {
     .wrap_struct_name = "SFML::Glyph",
     .function = {.dmark = NULL, .dfree = Glyph_free, .dsize = NULL},
-    .flags = RUBY_TYPED_FREE_IMMEDIATELY
-};
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY};
 
 VALUE glyph_from_c(sfGlyph glyph) {
-    Glyph *ptr = malloc(sizeof(Glyph));
+    Glyph* ptr = malloc(sizeof(Glyph));
 
     ptr->glyph = glyph;
 
     return TypedData_Wrap_Struct(rb_cGlyph, &Glyph_data_type, ptr);
 }
 
-static Glyph *Get_Glyph(VALUE self) {
-    Glyph *ptr;
+static Glyph* Get_Glyph(VALUE self) {
+    Glyph* ptr;
     TypedData_Get_Struct(self, Glyph, &Glyph_data_type, ptr);
     return ptr;
 }
 
+/* call-seq: advance -> Float
+ *
+ * Returns the glyph's horizontal advance.
+ *
+ * @return [Float] the horizontal offset to advance to the next character
+ */
 static VALUE Glyph_get_advance(VALUE self) {
     return DBL2NUM(Get_Glyph(self)->glyph.advance);
 }
 
+/* call-seq: bounds -> Rect
+ *
+ * Returns the glyph's bounding box.
+ *
+ * @return [Rect] the glyph's bounding box, relative to the baseline and
+ *   the cursor position
+ */
 static VALUE Glyph_get_bounds(VALUE self) {
     return rect_to_rb(Get_Glyph(self)->glyph.bounds);
 }
 
+/* call-seq: texture_rect -> Rect
+ *
+ * Returns the sub-rectangle of the texture displayed on the object.
+ *
+ * @return [Rect] the sub-rectangle of the font's texture holding this
+ *   glyph's pixels
+ */
 static VALUE Glyph_get_texture_rect(VALUE self) {
     return int_rect_to_rb(Get_Glyph(self)->glyph.textureRect);
 }
 
-void Init_Glyph(VALUE rb_module) {
-    rb_cGlyph = rb_define_class_under(rb_module, "Glyph", rb_cObject);
+static VALUE Glyph_alloc(VALUE klass) {
+    (void)klass;
+    rb_raise(rb_eNotImpError,
+             "glyph objects are returned by Font#glyph and cannot be constructed directly");
+}
+
+/* Document-class: SFML::Glyph
+ * A single character's rendering metrics and texture location, as returned
+ * by Font#glyph. Read-only.
+ */
+void Init_Glyph(VALUE rb_mSFML) {
+    rb_cGlyph = rb_define_class_under(rb_mSFML, "Glyph", rb_cObject);
+    rb_define_alloc_func(rb_cGlyph, Glyph_alloc);
 
     rb_define_method(rb_cGlyph, "advance", Glyph_get_advance, 0);
     rb_define_method(rb_cGlyph, "bounds", Glyph_get_bounds, 0);