ruby-libgd 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86d2d815f83b82844f6e052eedcd00481e53bf8d270dc8db48a5c4bc18bcecbb
-  data.tar.gz: fd3bea0c6cbeb6d6bc5d0f31716b0c32d57b62f3cad20f7955cbe695360bb87c
+  metadata.gz: 5f72abe4a18b66efb49a1e30a5ef170e69a31f4a3eb0ccf308e9c9f85603c229
+  data.tar.gz: c17c93e69f330862bc24bd655fbc7abb8017be59d0bd57723d5aeb7c9301e70f
 SHA512:
-  metadata.gz: 1389a01c9e0de55a8a2aad3cda2781016c292fe6ddc44aebcb768f89e73c103f6a28466a253e92466f84990ea22e28cd76432464aa19f8a4894ad5d3d59a15bd
-  data.tar.gz: 68453f430c861714bf37ce2c2c7016cafb22543f19d5c22c964d303c6c4bf163ee4d50ac3370ee37551c1e206aec6dff03897036052c2cde94cb2b7a9cd7aad5
+  metadata.gz: 7667691652b3fbb70b7945071ac3f0719d8162adb231b80c3b1e7eb17514db6714e1562791f6bdd20676bc77b3d96fc85b1dec0b5bfb7c07678efa86ec82fc48
+  data.tar.gz: f02dc5751f96bd1bd25ac4b693f4e18b968cc2fcaceaa687efd269572cca60a8ef506de4b3a79870a98fb91a8c164fd8bea78eb7df6bca1a1b1ab0b255647531

data/README.md

@@ -0,0 +1,301 @@
+# Ruby Libgd
+
+<p align="center">
+  <a href="https://rubystacknews.com">
+    <img src="https://img.shields.io/badge/RubyStackNews-CC342D?style=for-the-badge&logo=ruby&logoColor=white" />
+  </a>
+  <a href="https://x.com/ruby_stack_news">
+    <img src="https://img.shields.io/badge/Twitter%20%40RubyStackNews-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white" />
+  </a>
+  <a href="https://www.linkedin.com/in/germ%C3%A1n-silva-56a12622/">
+    <img src="https://img.shields.io/badge/Germán%20Silva-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white" />
+  </a>
+</p>
+
+<p align="right">
+  <img src="docs/images/logo.png" width="160" />
+</p>
+
+## Library Status
+
+![CI](https://github.com/ggerman/libgd-gis/actions/workflows/ci.yml/badge.svg)
+
+| Implemented | Implemented | Coming Next |
+| :--: | :--: | :--: |
+| <img src="./examples/charts/images/fruit_chart_with_text.png" width="250"> | <img src="./examples/charts/images/pie_chart.png" width="250"> | <img src="./examples/maps/parana_paracao_route.png" width="250"> |
+| <img src="./examples/image_processing/images/processed.jpg" width="250"> | <img src="./examples/charts/images/stem_plot.png" width="250"> | <img src="./examples/maps/parana_paracao_polygon.png" width="250"> |
+| <img src="./examples/basics/images/vintage.jpg" width="250">  | <img src="./examples/basics/images/antialias_demo.png" width="250"> |  |
+
+**Note:** The images shown in Table 1, along with the code used to generate them, are available in the `examples/` folder.
+
+# Native GD bindings for modern Ruby
+
+## What is ruby-libgd?
+
+ruby-libgd is a modern native Ruby binding to the GD Graphics Library, providing Ruby with a fast, embeddable, server-side graphics engine.
+
+It enables Ruby to generate images, charts, dashboards, GIS tiles, and scientific graphics without spawning external processes.
+
+## 🐧Installation (Debian / Ubuntu /Dockerfile)
+
+`gem install ruby-libgd`
+
+System dependencies:
+
+`apt install -y libgd-dev pkg-config`
+
+---
+
+## 🍎 macOS (Intel & Apple Silicon)
+
+ruby-libgd is a native extension and depends on libgd, which must be installed via Homebrew.
+
+Install libgd
+
+```bash
+brew install gd
+```
+Verify Homebrew’s install path:
+
+```bash
+brew --prefix gd
+```
+
+Typical values:
+Apple Silicon (**M1 / M2 / M3**): /opt/homebrew
+
+Intel Macs: /usr/local
+
+### Install ruby-libgd
+
+Apple Silicon (**M1 / M2 / M3**)
+
+Homebrew installs libraries into **/opt/homebrew**, which Ruby’s native extension builder does not detect automatically.
+
+## Install using:
+
+```bash
+gem install ruby-libgd -- --with-gd-dir=/opt/homebrew
+```
+
+## Intel macOS
+
+```bash
+gem install ruby-libgd
+```
+
+---
+
+## 📚 Documentation
+
+- 🇬🇧 **English**: https://ggerman.github.io/ruby-libgd/en/
+- 🇯🇵 **日本語**: https://ggerman.github.io/ruby-libgd/jp/
+
+---
+
+## Examples:
+
+All runnable examples live in:
+
+examples/
+  basics/
+  image_processing/
+  charts/
+  images/
+
+Each Ruby script in examples/ generates an image in examples/images/.
+
+
+## Links
+
+GitHub: https://github.com/ggerman/ruby-libgd  
+RubyGems: https://rubygems.org/gems/ruby-libgd  
+Article: https://rubystacknews.com/2026/01/05/ruby-can-create-images-again/
+
+---
+
+## Build & Runtime Environment
+
+**ruby-libgd** is developed and tested against **libgd 2.3.3** using a reproducible Docker environment.
+
+This ensures that the native extension is compiled against a known, stable GD ABI and behaves consistently across systems.
+
+Reference **Dockerfile**
+```dockerfile
+FROM ruby:3.3
+
+RUN apt update && apt -y upgrade
+RUN apt install -y \
+  libgd-dev \
+  libgd3 \
+  libgd-tools \
+  pkg-config \
+  ruby-dev \
+  build-essential \
+  valgrind
+
+RUN printf "prefix=/usr\n\
+exec_prefix=\${prefix}\n\
+libdir=\${exec_prefix}/lib/x86_64-linux-gnu\n\
+includedir=\${prefix}/include\n\
+\n\
+Name: gd\n\
+Description: GD Graphics Library\n\
+Version: 2.3\n\
+Libs: -L\${libdir} -lgd\n\
+Cflags: -I\${includedir}\n" \
+> /usr/lib/x86_64-linux-gnu/pkgconfig/gd.pc
+
+ENV PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig
+
+WORKDIR /app
+
+COPY Gemfile Gemfile.lock ./
+RUN bundle install
+
+# Enforce dependency lockfile reproducibility
+RUN bundle config --global frozen 1
+
+COPY . .
+
+```
+
+## Why this matters
+
+**ruby-libgd** is a native **C** extension. The exact **libgd** version and build flags directly affect:
+
+- Alpha blending
+
+- Color accuracy
+
+- Filter behavior
+
+- Memory safety
+
+
+Using a pinned, containerized build environment guarantees that:
+
+- The extension is compiled against libgd 2.3.x
+
+- pkg-config resolves the correct headers and linker flags
+
+- CI, contributors, and users see identical behavior
+
+
+This is especially important for GIS, map tiles, and image pipelines where pixel-level consistency matters.
+
+## Example:
+
+![RubyStackNews](examples/images/rubystacknews-banner.png)
+
+```Ruby
+require "gd"
+
+WIDTH  = 800
+HEIGHT = 400
+
+img = GD::Image.new(WIDTH, HEIGHT)
+
+# ----------------------------
+# Pastel palette
+# ----------------------------
+bg_top    = [244, 240, 255]   # lavender
+bg_bottom = [230, 248, 255]   # light sky
+
+accent1 = [255, 140, 180]    # pastel pink
+accent2 = [120, 200, 255]    # pastel blue
+text_main = [60, 70, 120]    # deep indigo
+shadow = [180, 190, 220]
+
+# ----------------------------
+# Soft gradient background
+# ----------------------------
+(0...HEIGHT).each do |y|
+  t = y.to_f / (HEIGHT - 1)
+
+  r = (bg_top[0] + (bg_bottom[0] - bg_top[0]) * t).to_i
+  g = (bg_top[1] + (bg_bottom[1] - bg_top[1]) * t).to_i
+  b = (bg_top[2] + (bg_bottom[2] - bg_top[2]) * t).to_i
+
+  img.line(0, y, WIDTH - 1, y, [r, g, b])
+end
+
+# ----------------------------
+# Floating pastel blobs
+# ----------------------------
+img.filled_circle(120, 100, 80, accent2)
+img.filled_circle(680, 280, 100, accent1)
+img.filled_circle(700, 80, 50, [200, 230, 255])
+
+# ----------------------------
+# Text
+# ----------------------------
+font = "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
+title_size = 52
+subtitle_size = 20
+
+title = "RubyStackNews"
+subtitle = "The pulse of the Ruby ecosystem"
+
+# Manual centering
+title_x = 80
+title_y = 190
+
+# Soft shadow
+img.text(title, {
+  x: title_x + 2,
+  y: title_y + 2,
+  size: title_size,
+  color: shadow,
+  font: font
+})
+
+# Main title
+img.text(title, {
+  x: title_x,
+  y: title_y,
+  size: title_size,
+  color: text_main,
+  font: font
+})
+
+# Subtitle
+img.text(subtitle, {
+  x: title_x,
+  y: title_y + 45,
+  size: subtitle_size,
+  color: [100,110,160],
+  font: font
+})
+
+# ----------------------------
+# Call-to-action pill
+# ----------------------------
+pill_x = 80
+pill_y = 260
+pill_w = 260
+pill_h = 44
+
+img.filled_rectangle(pill_x, pill_y, pill_x + pill_w, pill_y + pill_h, [255,255,255])
+img.rectangle(pill_x, pill_y, pill_x + pill_w, pill_y + pill_h, accent2, thickness: 2)
+
+img.text("rubystacknews.com", {
+  x: pill_x + 22,
+  y: pill_y + 30,
+  size: 20,
+  color: text_main,
+  font: font
+})
+
+# ----------------------------
+# Save
+# ----------------------------
+img.save("images/rubystacknews-banner.png")
+puts "Saved images/rubystacknews-banner.png"
+
+```
+
+## License
+
+MIT License.
+Copyright (c) 2025 Germán Alberto Giménez Silva.

data/ext/gd/Makefile

@@ -140,9 +140,9 @@ extout_prefix =
 target_prefix = /gd
 LOCAL_LIBS = 
 LIBS = $(LIBRUBYARG_SHARED) -lm -lgd  -lm -lpthread  -lc
-ORIG_SRCS = arc.c blit.c char.c circle.c clip.c color.c draw_line.c ellipse.c encode.c fill.c filter.c gd.c image.c pixel.c polygon.c rectangle.c text.c transform.c version.c
+ORIG_SRCS = arc.c blit.c char.c circle.c clip.c color.c draw_line.c ellipse.c encode.c fill.c filter.c gd.c gif.c image.c pixel.c polygon.c rectangle.c text.c transform.c version.c
 SRCS = $(ORIG_SRCS) 
-OBJS = arc.o blit.o char.o circle.o clip.o color.o draw_line.o ellipse.o encode.o fill.o filter.o gd.o image.o pixel.o polygon.o rectangle.o text.o transform.o version.o
+OBJS = arc.o blit.o char.o circle.o clip.o color.o draw_line.o ellipse.o encode.o fill.o filter.o gd.o gif.o image.o pixel.o polygon.o rectangle.o text.o transform.o version.o
 HDRS = $(srcdir)/clip.h $(srcdir)/ruby_gd.h
 LOCAL_HDRS = 
 TARGET = gd

data/ext/gd/gd.c

@@ -83,6 +83,8 @@ void Init_gd(void) {
   gd_define_transform(cGDImage);
   gd_define_encode(cGDImage);
 
+  gd_define_gif(mGD);
+
   gd_define_color(mGD);
   gd_define_version(mGD);
 }

data/ext/gd/gif.c

@@ -0,0 +1,151 @@
+#include "ruby_gd.h"
+
+typedef struct {
+  FILE *out;
+  gdImagePtr prev;
+  VALUE prev_rb;
+  int started;
+  int loop;
+} gd_gif_wrapper;
+
+static void gd_gif_free(void *p) {
+  gd_gif_wrapper *gif = (gd_gif_wrapper *)p;
+
+  if (gif->out) {
+    if (gif->started) {
+      gdImageGifAnimEnd(gif->out);
+    }
+    fclose(gif->out);
+  }
+
+  xfree(gif);
+}
+
+static size_t gd_gif_memsize(const void *p) {
+  return sizeof(gd_gif_wrapper);
+}
+
+static const rb_data_type_t gd_gif_type = {
+  "GD::Gif",
+  {
+    0,
+    gd_gif_free,
+    gd_gif_memsize,
+  },
+  0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+static VALUE gd_gif_alloc(VALUE klass) {
+  gd_gif_wrapper *gif;
+  VALUE obj = TypedData_Make_Struct(klass, gd_gif_wrapper, &gd_gif_type, gif);
+
+  gif->out = NULL;
+  gif->prev = NULL;
+  gif->prev_rb = Qnil;
+  gif->started = 0;
+  gif->loop = 0;
+
+  return obj;
+}
+
+/*
+ * GD::Gif.new("file.gif", loop: true)
+ */
+static VALUE gd_gif_initialize(int argc, VALUE *argv, VALUE self) {
+  VALUE path, opts;
+  rb_scan_args(argc, argv, "11", &path, &opts);
+
+  gd_gif_wrapper *gif;
+  TypedData_Get_Struct(self, gd_gif_wrapper, &gd_gif_type, gif);
+
+  const char *filename = StringValueCStr(path);
+  gif->out = fopen(filename, "wb");
+  if (!gif->out) rb_sys_fail(filename);
+
+  gif->started = 0;
+  gif->prev = NULL;
+  gif->prev_rb = Qnil;
+
+  gif->loop = 0;
+  if (opts != Qnil) {
+    VALUE loopv = rb_hash_aref(opts, ID2SYM(rb_intern("loop")));
+    if (loopv == Qfalse) {
+      gif->loop = -1;
+    }
+  }
+
+  return self;
+}
+
+/*
+ * gif.add_frame(img, delay: 50)
+ */
+static VALUE gd_gif_add_frame(int argc, VALUE *argv, VALUE self) {
+  VALUE rb_img, opts;
+  rb_scan_args(argc, argv, "11", &rb_img, &opts);
+
+  gd_image_wrapper *wrap;
+  TypedData_Get_Struct(rb_img, gd_image_wrapper, &gd_image_type, wrap);
+
+  gd_gif_wrapper *gif;
+  TypedData_Get_Struct(self, gd_gif_wrapper, &gd_gif_type, gif);
+
+  int delay = 50;
+  if (opts != Qnil) {
+    VALUE d = rb_hash_aref(opts, ID2SYM(rb_intern("delay")));
+    if (!NIL_P(d)) delay = NUM2INT(d);
+  }
+
+  if (!gif->started) {
+    gdImageGifAnimBegin(wrap->img, gif->out, 1, gif->loop);
+    gif->started = 1;
+  }
+
+  gdImageGifAnimAdd(
+    wrap->img,
+    gif->out,
+    1,
+    0, 0,
+    delay,
+    1,
+    gif->prev
+  );
+
+  gif->prev = wrap->img;
+  gif->prev_rb = rb_img;   /* prevent GC */
+
+  return Qtrue;
+}
+
+/*
+ * gif.close
+ */
+static VALUE gd_gif_close(VALUE self) {
+  gd_gif_wrapper *gif;
+  TypedData_Get_Struct(self, gd_gif_wrapper, &gd_gif_type, gif);
+
+  if (gif->out) {
+    if (gif->started) {
+      gdImageGifAnimEnd(gif->out);
+    }
+    fclose(gif->out);
+    gif->out = NULL;
+  }
+
+  gif->prev = NULL;
+  gif->prev_rb = Qnil;
+
+  return Qtrue;
+}
+
+/*
+ * Init hook
+ */
+void gd_define_gif(VALUE mGD) {
+  VALUE cGif = rb_define_class_under(mGD, "Gif", rb_cObject);
+
+  rb_define_alloc_func(cGif, gd_gif_alloc);
+  rb_define_method(cGif, "initialize", gd_gif_initialize, -1);
+  rb_define_method(cGif, "add_frame", gd_gif_add_frame, -1);
+  rb_define_method(cGif, "close", gd_gif_close, 0);
+}

data/ext/gd/image.c

@@ -36,13 +36,6 @@ static VALUE gd_image_initialize(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
-static VALUE gd_image_initialize_empty(VALUE self) {
-  gd_image_wrapper *wrap;
-  TypedData_Get_Struct(self, gd_image_wrapper, &gd_image_type, wrap);
-  wrap->img = NULL;
-  return self;
-}
-
 static VALUE gd_image_initialize_true_color(VALUE self, VALUE width, VALUE height) {
   gd_image_wrapper *wrap;
   TypedData_Get_Struct(self, gd_image_wrapper, &gd_image_type, wrap);
@@ -123,21 +116,6 @@ static VALUE gd_image_alloc(VALUE klass) {
   return obj;
 }
 
-static VALUE gd_image_new(VALUE klass, VALUE w, VALUE h) {
-  VALUE obj = rb_class_new_instance(0, NULL, klass);
-  gd_image_wrapper *wrap;
-  TypedData_Get_Struct(obj, gd_image_wrapper, &gd_image_type, wrap);
-
-  int width  = NUM2INT(w);
-  int height = NUM2INT(h);
-  if (width <= 0 || height <= 0)
-    rb_raise(rb_eArgError, "width and height must be positive");
-
-  wrap->img = gdImageCreateTrueColor(width, height);
-  if (!wrap->img) rb_raise(rb_eRuntimeError, "gdImageCreateTrueColor failed");
-  return obj;
-}
-
 static VALUE gd_image_open(VALUE klass, VALUE path) {
   const char *filename = StringValueCStr(path);
 

data/ext/gd/ruby_gd.h

@@ -32,6 +32,8 @@ void gd_define_transform(VALUE cGDImage);
 void gd_define_filter(VALUE cGDImage);
 void gd_define_encode(VALUE cGDImage);
 
+void gd_define_gif(VALUE mGD);
+
 /* Color */
 void gd_define_color(VALUE mGD);
 void gd_define_version(VALUE mGD);

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-libgd
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Germán Alberto Giménez Silva
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-14 00:00:00.000000000 Z
+date: 2026-01-15 00:00:00.000000000 Z
 dependencies: []
 description: High-performance native Ruby bindings to libgd for image generation,
   drawing, filters, alpha blending, and transformations.
@@ -48,6 +48,8 @@ files:
 - ext/gd/gd.c
 - ext/gd/gd.o
 - ext/gd/gd.so
+- ext/gd/gif.c
+- ext/gd/gif.o
 - ext/gd/image.c
 - ext/gd/image.o
 - ext/gd/mkmf.log