rgame 0.1.0

data/ext/rgame_core/ruby/font_ext.c

@@ -0,0 +1,168 @@
+/*
+ * font_ext.c — the Ruby binding for RGame::Core::Font.
+ *
+ *   font = RGame::Core::Font.new(app, 18)                        # the shipped font
+ *   font = RGame::Core::Font.new(app, 18, path: 'assets/x.ttf')
+ *   font.height        # => 18
+ *   font.text_width('Score: 1200')
+ *
+ * The atlas, the cache and the metrics are in font_atlas.c, font.c, atlas.c and
+ * glyph_cache.c — three of those four are pure and Check-tested. This file is
+ * the wrapper: argument checking, turning a NULL return into an exception that
+ * says why, and keeping the app reachable for as long as the font is.
+ *
+ * The default path is *not* here. It is a packaging question — where a gem
+ * installs its data — so lib/rgame/core/font.rb owns it and passes a path down.
+ *
+ * The C layer has no opinion about where fonts live and there is **no
+ * font-name lookup at all**: a font is a file. Asking the operating system for
+ * one by name would mean a font-database backend per platform — fontconfig on
+ * Linux, CoreText on macOS, GDI on Windows — and a system dependency this
+ * engine otherwise does not have. It would also mean text renders differently
+ * on different machines, which is a layout bug nobody can reproduce. See
+ * vendor/README.md.
+ */
+
+#include "ruby/core_ext.h"
+
+#include "text/font_internal.h"
+#include "rgame/core.h"
+
+typedef struct {
+    rgame_font *font;
+    VALUE app_object; /* marked: the atlas pages live in this window's context */
+} rgame_font_ref;
+
+static void font_ref_mark(void *ptr) {
+    rgame_font_ref *ref = ptr;
+    rb_gc_mark(ref->app_object);
+}
+
+static void font_ref_free(void *ptr) {
+    rgame_font_ref *ref = ptr;
+    rgame_font_destroy(ref->font); /* NULL-safe */
+    xfree(ref);
+}
+
+static size_t font_ref_size(const void *ptr) {
+    (void)ptr;
+    return sizeof(rgame_font_ref);
+}
+
+static const rb_data_type_t font_data_type = {
+    .wrap_struct_name = "rgame_font",
+    .function = {
+        .dmark = font_ref_mark,
+        .dfree = font_ref_free,
+        .dsize = font_ref_size,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE cFont;
+
+static rgame_font_ref *font_unwrap(VALUE self) {
+    rgame_font_ref *ref;
+    TypedData_Get_Struct(self, rgame_font_ref, &font_data_type, ref);
+    if (!ref->font) {
+        rb_raise(rb_eRuntimeError, "font is not initialized");
+    }
+    return ref;
+}
+
+rgame_font *rgame_font_unwrap(VALUE font) {
+    return font_unwrap(font)->font;
+}
+
+static VALUE font_alloc(VALUE klass) {
+    rgame_font_ref *ref;
+    VALUE object = TypedData_Make_Struct(klass, rgame_font_ref, &font_data_type, ref);
+    ref->font = NULL;
+    ref->app_object = Qnil;
+    return object;
+}
+
+/* Font.new(app, pixel_height, path) — the path is supplied by the Ruby half,
+ * which defaults it to the shipped font. */
+static VALUE font_initialize(VALUE self, VALUE app, VALUE pixel_height, VALUE path) {
+    rgame_font_ref *ref;
+    TypedData_Get_Struct(self, rgame_font_ref, &font_data_type, ref);
+
+    rgame_app *engine_app = rgame_app_unwrap(app); /* raises TypeError otherwise */
+    const char *path_str = StringValueCStr(path);
+    int height = NUM2INT(pixel_height);
+
+    char error[256] = {0};
+    rgame_font *font = rgame_font_load(engine_app, path_str, height, error, sizeof(error));
+    if (!font) {
+        rb_raise(rb_const_get(cFont, rb_intern("LoadError")), "%s", error);
+    }
+
+    ref->font = font;
+    ref->app_object = app;
+    return self;
+}
+
+/* The size it was loaded at, and the amount to step by for a second line. */
+static VALUE font_height(VALUE self) {
+    return INT2NUM(rgame_font_height(font_unwrap(self)->font));
+}
+
+/*
+ * #text_width(string) — what #text would occupy, in pixels.
+ *
+ * Deliberately usable outside `draw`: measuring touches no GL, and laying out a
+ * menu happens while updating, not while drawing.
+ */
+static VALUE font_text_width(VALUE self, VALUE string) {
+    rgame_font_ref *ref = font_unwrap(self);
+
+    /* Raises TypeError rather than letting RSTRING_PTR read a non-String's
+     * innards as a char*, which segfaults. See renderer_ext.c's #draw_text. */
+    StringValue(string);
+
+    /* The bytes as Ruby holds them. No copy, no per-call allocation, and the
+     * codepoint walk happens in C where it costs nothing. */
+    const char *text = RSTRING_PTR(string);
+    long length = RSTRING_LEN(string);
+    double width = rgame_font_measure(ref->font, text, (size_t)length);
+
+    /* Keeps `string` alive across the call above, which matters because
+     * RSTRING_PTR hands out a pointer the GC does not know we are holding. */
+    RB_GC_GUARD(string);
+    return DBL2NUM(width);
+}
+
+/* How many atlas pages exist across every live font. Test-only, and named so:
+ * a leaked page is invisible — nothing looks wrong until video memory runs
+ * out. The image side has the same counter for the same reason. */
+static VALUE font_s_debug_live_pages(VALUE klass) {
+    (void)klass;
+    return LONG2NUM(rgame_font_live_pages());
+}
+
+static VALUE font_inspect(VALUE self) {
+    rgame_font_ref *ref;
+    TypedData_Get_Struct(self, rgame_font_ref, &font_data_type, ref);
+    if (!ref->font) {
+        return rb_sprintf("#<%" PRIsVALUE " (uninitialized)>", rb_obj_class(self));
+    }
+
+    return rb_sprintf("#<%" PRIsVALUE " %dpx>", rb_obj_class(self),
+                      rgame_font_height(ref->font));
+}
+
+void rgame_init_font(VALUE mCore) {
+    cFont = rb_define_class_under(mCore, "Font", rb_cObject);
+
+    /* Raised when a file cannot be read or is not a TrueType font — an everyday
+     * condition, so it gets a name a game can rescue. */
+    rb_define_class_under(cFont, "LoadError", rb_eStandardError);
+
+    rb_define_alloc_func(cFont, font_alloc);
+    rb_define_method(cFont, "initialize", font_initialize, 3);
+    rb_define_method(cFont, "height", font_height, 0);
+    rb_define_method(cFont, "text_width", font_text_width, 1);
+    rb_define_method(cFont, "inspect", font_inspect, 0);
+    rb_define_singleton_method(cFont, "debug_live_pages", font_s_debug_live_pages, 0);
+}

data/ext/rgame_core/ruby/image_ext.c

@@ -0,0 +1,230 @@
+/*
+ * image_ext.c — the Ruby binding for RGame::Core::Image.
+ *
+ * The decode and upload are in image.c; the rectangle arithmetic behind
+ * subimages and tiles is in texture.c and is Check-tested with no GPU. This
+ * file is only the wrapper: argument checking, turning C's "returned NULL"
+ * into a Ruby exception that says why, and keeping the app object reachable
+ * for as long as any image made from it is.
+ *
+ *   img   = RGame::Core::Image.new(app, 'hero.png')
+ *   img.width; img.height
+ *   sub   = img.subimage(0, 0, 16, 16)
+ *   tiles = RGame::Core::Image.load_tiles(app, 'sheet.png', 16, 16)
+ *
+ * Slicing never re-decodes: every image above shares one GPU texture, and the
+ * texture goes when the last of them does.
+ */
+
+#include "ruby/core_ext.h"
+
+#include "rgame/core.h"
+#include "graphics/texture.h"
+
+/*
+ * The Ruby object's payload. Two members, and the second is the interesting
+ * one: `app` is the Ruby App object this image was loaded from, marked so the
+ * collector treats the app as reachable from every image.
+ *
+ * That is a deliberate ownership statement, not just GC hygiene. An image is
+ * meaningless without the context its pixels live in, and a game that keeps a
+ * sprite around has, by definition, not finished with the window. (The C layer
+ * survives the other order too — see rgame_app_gl_retain — but a Ruby user
+ * should never be in a position to observe it.)
+ */
+typedef struct {
+    rgame_image *image;
+    VALUE app;
+} rgame_image_ref;
+
+static void image_ref_mark(void *ptr) {
+    rgame_image_ref *ref = ptr;
+    rb_gc_mark(ref->app);
+}
+
+static void image_ref_free(void *ptr) {
+    rgame_image_ref *ref = ptr;
+    rgame_image_destroy(ref->image); /* NULL-safe */
+    xfree(ref);
+}
+
+static size_t image_ref_size(const void *ptr) {
+    (void)ptr;
+    return sizeof(rgame_image_ref);
+}
+
+static const rb_data_type_t image_data_type = {
+    .wrap_struct_name = "rgame_image",
+    .function = {
+        .dmark = image_ref_mark,
+        .dfree = image_ref_free,
+        .dsize = image_ref_size,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE cImage;
+
+static rgame_image_ref *image_ref_unwrap(VALUE self) {
+    rgame_image_ref *ref;
+    TypedData_Get_Struct(self, rgame_image_ref, &image_data_type, ref);
+    if (!ref->image) {
+        rb_raise(rb_eRuntimeError, "image is not initialized");
+    }
+    return ref;
+}
+
+/* The accessor other files in this extension use (see core_ext.h) — the
+ * renderer needs the C handle to draw. TypedData_Get_Struct raises TypeError on
+ * anything that is not an Image, so the type check comes for free. */
+rgame_image *rgame_image_unwrap(VALUE image) {
+    return image_ref_unwrap(image)->image;
+}
+
+/*
+ * Wraps a C handle in a fresh Ruby object. Takes ownership: if allocating the
+ * Ruby side raises, the handle would leak, so the payload is filled in before
+ * anything else can fail.
+ */
+static VALUE image_wrap(rgame_image *image, VALUE app) {
+    rgame_image_ref *ref;
+    VALUE object = TypedData_Make_Struct(cImage, rgame_image_ref, &image_data_type, ref);
+    ref->image = image;
+    ref->app = app;
+    return object;
+}
+
+/*
+ * Image.new(app, path)
+ *
+ * `app` comes first and is required, rather than being implied by "the window
+ * that happens to be open". Textures belong to one GL context, so an image
+ * genuinely is an image *of* an app — and saying so is what lets the object
+ * hold the app reachable, and what makes two windows work at all.
+ */
+static VALUE image_initialize(VALUE self, VALUE app, VALUE path) {
+    rgame_image_ref *ref;
+    TypedData_Get_Struct(self, rgame_image_ref, &image_data_type, ref);
+
+    /* Unwrapping raises TypeError on anything that is not an App, so there is
+     * no separate type check to keep in step with this one. */
+    rgame_app *engine_app = rgame_app_unwrap(app);
+    const char *path_str = StringValueCStr(path);
+
+    char error[256] = {0};
+    rgame_image *image = rgame_image_load(engine_app, path_str, error, sizeof(error));
+    if (!image) {
+        rb_raise(rb_const_get(cImage, rb_intern("LoadError")), "%s", error);
+    }
+
+    ref->image = image;
+    ref->app = app;
+    return self;
+}
+
+static VALUE image_alloc(VALUE klass) {
+    rgame_image_ref *ref;
+    VALUE object = TypedData_Make_Struct(klass, rgame_image_ref, &image_data_type, ref);
+    ref->image = NULL;
+    ref->app = Qnil;
+    return object;
+}
+
+static VALUE image_width(VALUE self) {
+    return INT2NUM(rgame_image_width(image_ref_unwrap(self)->image));
+}
+
+static VALUE image_height(VALUE self) {
+    return INT2NUM(rgame_image_height(image_ref_unwrap(self)->image));
+}
+
+/*
+ * #subimage(x, y, width, height)
+ *
+ * Raises rather than returning nil on a rect that does not fit. A nil here
+ * would travel a long way — into an asset table, out of it three scenes
+ * later — before failing as a NoMethodError with nothing left pointing at the
+ * bad coordinates.
+ */
+static VALUE image_subimage(VALUE self, VALUE x, VALUE y, VALUE width, VALUE height) {
+    rgame_image_ref *ref = image_ref_unwrap(self);
+
+    rgame_image *sub = rgame_image_subimage(ref->image, NUM2INT(x), NUM2INT(y), NUM2INT(width),
+                                            NUM2INT(height));
+    if (!sub) {
+        rb_raise(rb_eArgError,
+                 "subimage %" PRIsVALUE ",%" PRIsVALUE " %" PRIsVALUE "x%" PRIsVALUE
+                 " does not fit in a %dx%d image",
+                 x, y, width, height, rgame_image_width(ref->image),
+                 rgame_image_height(ref->image));
+    }
+
+    return image_wrap(sub, ref->app);
+}
+
+/* #tile_count(tile_width, tile_height) — whole tiles only. */
+static VALUE image_tile_count(VALUE self, VALUE tile_width, VALUE tile_height) {
+    return INT2NUM(rgame_image_tile_count(image_ref_unwrap(self)->image, NUM2INT(tile_width),
+                                          NUM2INT(tile_height)));
+}
+
+/* #tile(tile_width, tile_height, index) — row-major, left to right then down. */
+static VALUE image_tile(VALUE self, VALUE tile_width, VALUE tile_height, VALUE index) {
+    rgame_image_ref *ref = image_ref_unwrap(self);
+
+    rgame_image *tile = rgame_image_tile(ref->image, NUM2INT(tile_width), NUM2INT(tile_height),
+                                         NUM2INT(index));
+    if (!tile) {
+        rb_raise(rb_eIndexError, "tile %" PRIsVALUE " is out of range (%d tiles of %" PRIsVALUE
+                                 "x%" PRIsVALUE ")",
+                 index,
+                 rgame_image_tile_count(ref->image, NUM2INT(tile_width), NUM2INT(tile_height)),
+                 tile_width, tile_height);
+    }
+
+    return image_wrap(tile, ref->app);
+}
+
+static VALUE image_inspect(VALUE self) {
+    rgame_image_ref *ref;
+    TypedData_Get_Struct(self, rgame_image_ref, &image_data_type, ref);
+    if (!ref->image) {
+        return rb_sprintf("#<%" PRIsVALUE " (uninitialized)>", rb_obj_class(self));
+    }
+
+    return rb_sprintf("#<%" PRIsVALUE " %dx%d>", rb_obj_class(self),
+                      rgame_image_width(ref->image), rgame_image_height(ref->image));
+}
+
+/*
+ * Image.debug_live_textures — how many GPU textures the engine is holding.
+ *
+ * Test-only, and named so. A leaked texture is silent: nothing is slower and
+ * nothing looks wrong until video memory runs out an hour into play. This is
+ * what lets a spec assert that dropping a sheet and all its tiles actually
+ * releases the upload — including in the case that only a garbage collector
+ * can produce, where an app and its images are swept in an arbitrary order.
+ */
+static VALUE image_s_debug_live_textures(VALUE klass) {
+    (void)klass;
+    return LONG2NUM(rgame_texture_live_sheets());
+}
+
+void rgame_init_image(VALUE mCore) {
+    cImage = rb_define_class_under(mCore, "Image", rb_cObject);
+
+    /* Raised when a file cannot be read or decoded — an everyday condition
+     * (a typo'd path, a truncated asset), so it gets a name a game can rescue
+     * rather than a bare RuntimeError. */
+    rb_define_class_under(cImage, "LoadError", rb_eStandardError);
+
+    rb_define_alloc_func(cImage, image_alloc);
+    rb_define_method(cImage, "initialize", image_initialize, 2);
+    rb_define_method(cImage, "width", image_width, 0);
+    rb_define_method(cImage, "height", image_height, 0);
+    rb_define_method(cImage, "subimage", image_subimage, 4);
+    rb_define_method(cImage, "tile_count", image_tile_count, 2);
+    rb_define_method(cImage, "tile", image_tile, 3);
+    rb_define_method(cImage, "inspect", image_inspect, 0);
+    rb_define_singleton_method(cImage, "debug_live_textures", image_s_debug_live_textures, 0);
+}

data/ext/rgame_core/ruby/recording_ext.c

@@ -0,0 +1,186 @@
+/*
+ * recording_ext.c — the Ruby binding for RGame::Core::Recording.
+ *
+ * A recording is made by `RGame::Core::Renderer#record`, never by `new`:
+ *
+ *     ground = renderer.record { tiles.each { |t| renderer.image(t.image, t.x, t.y) } }
+ *     ground.draw(-camera.x, -camera.y)
+ *
+ * The baking and the replay are in recording.c and canvas.c, both pure. What
+ * this file adds is the two things only Ruby can do: hold the images the
+ * recording drew, so their GPU textures cannot be freed while a recording still
+ * references them, and refuse a replay outside a frame.
+ *
+ * ---------------------------------------------------------------------------
+ * Why the images have to be held
+ * ---------------------------------------------------------------------------
+ *
+ * A baked batch stores a GL texture *name* — a number. If the Image it came
+ * from is collected, its texture is deleted and that number now refers to
+ * nothing; replaying would draw whatever the driver put there next, or nothing
+ * at all, with no error. So the renderer collects the images drawn during a
+ * recording, and the recording marks them for as long as it lives. Holding a
+ * texture alive while something still draws it is the same rule as everywhere
+ * else here; it just has to be spelled out at this layer, because the C side
+ * only ever saw a number.
+ */
+
+#include "ruby/core_ext.h"
+
+#include "graphics/recording.h"
+#include "rgame/core.h"
+
+typedef struct {
+    rgame_recording *recording;
+    rgame_app *app;
+    VALUE app_object; /* marked: the textures live in this window's context */
+    VALUE images;     /* marked: an Array of every Image baked into this */
+} rgame_recording_ref;
+
+static void recording_mark(void *ptr) {
+    rgame_recording_ref *ref = ptr;
+    rb_gc_mark(ref->app_object);
+    rb_gc_mark(ref->images);
+}
+
+static void recording_free(void *ptr) {
+    rgame_recording_ref *ref = ptr;
+    rgame_recording_free(ref->recording); /* NULL-safe */
+    xfree(ref);
+}
+
+static size_t recording_size(const void *ptr) {
+    (void)ptr;
+    return sizeof(rgame_recording_ref);
+}
+
+static const rb_data_type_t recording_data_type = {
+    .wrap_struct_name = "rgame_recording",
+    .function = {
+        .dmark = recording_mark,
+        .dfree = recording_free,
+        .dsize = recording_size,
+    },
+    .flags = RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+static VALUE cRecording;
+
+static rgame_recording_ref *recording_unwrap(VALUE self) {
+    rgame_recording_ref *ref;
+    TypedData_Get_Struct(self, rgame_recording_ref, &recording_data_type, ref);
+    if (!ref->recording) {
+        rb_raise(rb_eRuntimeError, "recording is not initialized");
+    }
+    return ref;
+}
+
+/*
+ * Declared even though `new` is refused below: wrapping a TypedData payload in
+ * a class that still has Object's allocator makes Ruby undefine it for us and
+ * warn about it. Saying so up front is one line and keeps the load quiet.
+ */
+static VALUE recording_alloc(VALUE klass) {
+    rgame_recording_ref *ref;
+    VALUE object = TypedData_Make_Struct(klass, rgame_recording_ref, &recording_data_type, ref);
+    ref->recording = NULL;
+    ref->app = NULL;
+    ref->app_object = Qnil;
+    ref->images = Qnil;
+    return object;
+}
+
+VALUE rgame_recording_wrap(rgame_recording *recording, VALUE app_object, rgame_app *app,
+                           VALUE images) {
+    rgame_recording_ref *ref;
+    VALUE object = TypedData_Make_Struct(cRecording, rgame_recording_ref, &recording_data_type,
+                                         ref);
+    ref->recording = recording;
+    ref->app = app;
+    ref->app_object = app_object;
+    ref->images = images;
+    return object;
+}
+
+/*
+ * #draw_at(x, y, z, rgba) — the raw form; RGame::Core::Recording#draw in
+ * lib/rgame/core/recording.rb is the one with keywords and colour coercion.
+ */
+static VALUE recording_draw_at(VALUE self, VALUE x, VALUE y, VALUE z, VALUE color) {
+    rgame_recording_ref *ref = recording_unwrap(self);
+
+    /* The app that owns these textures has to be the one mid-frame. Anything
+     * else would append to a canvas nobody is about to submit, and draw
+     * nothing at all. */
+    if (!rgame_app_is_drawing(ref->app)) {
+        rb_raise(rb_eRuntimeError,
+                 "drawing is only allowed inside #draw (the frame is not open)");
+    }
+
+    rgame_app_draw_recording(ref->app, ref->recording, (float)NUM2DBL(x), (float)NUM2DBL(y),
+                             (unsigned int)(NUM2ULONG(color) & 0xFFFFFFFFul), NUM2DBL(z));
+    return self;
+}
+
+/* How many GL calls a replay costs — one per texture. Mostly for tests and for
+ * seeing whether a bake did what was hoped. */
+static VALUE recording_batch_count(VALUE self) {
+    return UINT2NUM(rgame_recording_batch_count(recording_unwrap(self)->recording));
+}
+
+static VALUE recording_vertex_count(VALUE self) {
+    return UINT2NUM(rgame_recording_vertex_count(recording_unwrap(self)->recording));
+}
+
+static VALUE recording_empty_p(VALUE self) {
+    return rgame_recording_vertex_count(recording_unwrap(self)->recording) == 0 ? Qtrue : Qfalse;
+}
+
+/* The size of what was baked, so a game can skip replaying an off-screen
+ * layer. Measured in the recording's own coordinates. */
+static VALUE recording_width(VALUE self) {
+    float min_x = 0.0f, max_x = 0.0f;
+    rgame_recording_bounds(recording_unwrap(self)->recording, &min_x, NULL, &max_x, NULL);
+    return DBL2NUM((double)(max_x - min_x));
+}
+
+static VALUE recording_height(VALUE self) {
+    float min_y = 0.0f, max_y = 0.0f;
+    rgame_recording_bounds(recording_unwrap(self)->recording, NULL, &min_y, NULL, &max_y);
+    return DBL2NUM((double)(max_y - min_y));
+}
+
+static VALUE recording_inspect(VALUE self) {
+    rgame_recording_ref *ref;
+    TypedData_Get_Struct(self, rgame_recording_ref, &recording_data_type, ref);
+    if (!ref->recording) {
+        return rb_sprintf("#<%" PRIsVALUE " (uninitialized)>", rb_obj_class(self));
+    }
+
+    return rb_sprintf("#<%" PRIsVALUE " %u batches, %u vertices>", rb_obj_class(self),
+                      rgame_recording_batch_count(ref->recording),
+                      rgame_recording_vertex_count(ref->recording));
+}
+
+/* Recordings come out of Renderer#record, so `new` is not part of the API —
+ * there is nothing a caller could pass that would make a valid one. */
+static VALUE recording_s_new(int argc, VALUE *argv, VALUE klass) {
+    (void)argc;
+    (void)argv;
+    rb_raise(rb_eNoMethodError, "%" PRIsVALUE " is created by Renderer#record, not by .new",
+             klass);
+}
+
+void rgame_init_recording(VALUE mCore) {
+    cRecording = rb_define_class_under(mCore, "Recording", rb_cObject);
+
+    rb_define_alloc_func(cRecording, recording_alloc);
+    rb_define_singleton_method(cRecording, "new", recording_s_new, -1);
+    rb_define_method(cRecording, "draw_at", recording_draw_at, 4);
+    rb_define_method(cRecording, "batch_count", recording_batch_count, 0);
+    rb_define_method(cRecording, "vertex_count", recording_vertex_count, 0);
+    rb_define_method(cRecording, "empty?", recording_empty_p, 0);
+    rb_define_method(cRecording, "width", recording_width, 0);
+    rb_define_method(cRecording, "height", recording_height, 0);
+    rb_define_method(cRecording, "inspect", recording_inspect, 0);
+}