harfbuzz-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b56e40fbf6e75fcf2cecdcfce3d2dc685281a3283c60b96f6a6bac6c28f16fc1
+  data.tar.gz: 6c1137acb54689eedf6a05da99e47e44ea83b000cf0b98a129bdfbc4c60074ad
+SHA512:
+  metadata.gz: d4f119a1c98ec67296ec7351bd36943e1a067341305cd7c3ee7e9a1efb7d42c7a8515273951017af8dbe212f3a4252827108c40332297e2dfb2d323595c3ea25
+  data.tar.gz: 2bc37ddb7b27ef540fef758b52a2708d5df8ec41fd96763680e85adcbe43c667ede6f3dd9873b57f381847ff129c6a60398e1773fa499498e5933a146a8b9d5d

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## v1.0.0 (2026-02-27)
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,258 @@
+# HarfBuzz Ruby
+
+Ruby bindings for [HarfBuzz](https://harfbuzz.github.io/) text shaping engine.
+
+## Features
+
+- Complete HarfBuzz API bindings using Ruby-FFI
+- Two-layer architecture: low-level `HarfBuzz::C` (1:1 C binding) + high-level Ruby-idiomatic layer
+- Safe memory management with borrow/own distinction
+- Thread-safe immutable font objects
+- Cross-platform support (macOS, Linux)
+- RBS type signatures included
+
+## Requirements
+
+- Ruby 3.1+
+- HarfBuzz C library installed on your system
+- Supported platforms:
+  - macOS (Homebrew)
+  - Ubuntu / Debian
+  - Fedora / RHEL
+  - Alpine
+
+## Installation
+
+Install the HarfBuzz C library:
+
+```bash
+# macOS
+brew install harfbuzz
+
+# Ubuntu / Debian
+sudo apt-get install libharfbuzz-dev libharfbuzz-subset0
+
+# Fedora / RHEL
+sudo dnf install harfbuzz-devel
+
+# Alpine
+apk add harfbuzz-dev
+```
+
+Add to your Gemfile:
+
+```ruby
+gem 'harfbuzz-ruby'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install harfbuzz-ruby
+```
+
+### Custom Library Path
+
+To use a custom build of HarfBuzz:
+
+```bash
+export HARFBUZZ_LIB_PATH=/path/to/libharfbuzz.dylib
+```
+
+## Usage
+
+### Basic Setup
+
+```ruby
+require "harfbuzz"
+
+result = HarfBuzz.shape_text("Hello, World!", font_path: "/path/to/font.ttf")
+result.each do |info, pos|
+  puts "glyph=#{info.glyph_id} x_advance=#{pos.x_advance}"
+end
+puts "Total advance: #{result.total_advance.first}"
+```
+
+### Text Shaping Example
+
+```ruby
+require "harfbuzz"
+
+# Load font
+blob = HarfBuzz::Blob.from_file!("/path/to/font.ttf")
+face = HarfBuzz::Face.new(blob, 0)
+font = HarfBuzz::Font.new(face)
+
+# Create buffer and add text
+buffer = HarfBuzz::Buffer.new
+buffer.add_utf8("Hello, World!")
+buffer.guess_segment_properties
+
+# Shape
+HarfBuzz.shape(font, buffer)
+
+# Read results
+buffer.glyph_infos.zip(buffer.glyph_positions).each do |info, pos|
+  puts "glyph_id=#{info.glyph_id} cluster=#{info.cluster} " \
+       "x_advance=#{pos.x_advance} x_offset=#{pos.x_offset}"
+end
+```
+
+### Shaping with Features
+
+```ruby
+features = [
+  HarfBuzz::Feature.from_string("liga"),    # enable ligatures
+  HarfBuzz::Feature.from_string("-kern"),   # disable kerning
+]
+HarfBuzz.shape(font, buffer, features)
+
+# Or use a hash
+features = HarfBuzz::Feature.from_hash(liga: true, kern: false, smcp: 2)
+HarfBuzz.shape(font, buffer, features)
+```
+
+### Variable Fonts
+
+```ruby
+font = HarfBuzz::Font.new(face)
+
+# Set weight=700 and width=75
+variations = [
+  HarfBuzz::Variation.from_string("wght=700"),
+  HarfBuzz::Variation.from_string("wdth=75"),
+]
+font.variations = variations
+```
+
+### Glyph Outline Extraction
+
+```ruby
+draw = HarfBuzz::DrawFuncs.new
+
+path_commands = []
+draw.on_move_to      { |x, y, _|        path_commands << "M #{x},#{y}" }
+draw.on_line_to      { |x, y, _|        path_commands << "L #{x},#{y}" }
+draw.on_quadratic_to { |cx, cy, x, y, _| path_commands << "Q #{cx},#{cy} #{x},#{y}" }
+draw.on_cubic_to     { |c1x, c1y, c2x, c2y, x, y, _|
+                        path_commands << "C #{c1x},#{c1y} #{c2x},#{c2y} #{x},#{y}" }
+draw.on_close_path   { |_|              path_commands << "Z" }
+draw.make_immutable!
+
+font.draw_glyph(36, draw)
+puts path_commands.join(" ")
+```
+
+### Font Subsetting
+
+```ruby
+input = HarfBuzz::Subset::Input.new
+
+unicode_set = input.unicode_set
+"Hello".each_codepoint { |cp| unicode_set.add(cp) }
+
+subsetted_face = HarfBuzz::Subset.subset(face, input)
+puts "Subsetted glyph count: #{subsetted_face.glyph_count}"
+```
+
+## Examples
+
+See the `examples/` directory for more complete examples:
+
+- `basic_shaping.rb` - Basic text shaping
+- `glyph_outlines.rb` - Glyph outline extraction
+- `opentype_features.rb` - OpenType feature queries
+- `variable_fonts.rb` - Variable font axis manipulation
+- `render_svg.rb` - Render shaped text to SVG and open in browser
+- `render_waterfall.rb` - Variable font weight waterfall (HTML + SVG)
+
+Run an example:
+
+```bash
+bundle exec ruby examples/basic_shaping.rb
+```
+
+Rendering examples generate SVG/HTML and open them in the default browser:
+
+```bash
+bundle exec ruby examples/render_svg.rb "Hello, HarfBuzz!"
+bundle exec ruby examples/render_waterfall.rb /path/to/variable_font.ttf
+```
+
+## API Overview
+
+### Core Objects
+
+| Class | Description |
+|-------|-------------|
+| `HarfBuzz::Blob` | Binary data container for font files |
+| `HarfBuzz::Face` | Font face (typeface + index) |
+| `HarfBuzz::Font` | Font instance with metrics and scale |
+| `HarfBuzz::Buffer` | Text buffer for shaping input/output |
+
+### Shaping
+
+| Class | Description |
+|-------|-------------|
+| `HarfBuzz::Feature` | OpenType feature toggle |
+| `HarfBuzz::Variation` | Variable font axis setting |
+| `HarfBuzz::ShapePlan` | Reusable shaping plan |
+| `HarfBuzz::ShapingResult` | Shaped text result with glyph info |
+| `HarfBuzz::GlyphInfo` | Glyph ID and cluster info |
+| `HarfBuzz::GlyphPosition` | Glyph advance and offset |
+
+### Drawing & Color
+
+| Class | Description |
+|-------|-------------|
+| `HarfBuzz::DrawFuncs` | Glyph outline extraction callbacks |
+| `HarfBuzz::PaintFuncs` | Color font paint callbacks |
+
+### OpenType
+
+| Class | Description |
+|-------|-------------|
+| `HarfBuzz::OT::Layout` | GSUB/GPOS script, language, and feature queries |
+| `HarfBuzz::OT::Var` | Variable font axis and instance queries |
+| `HarfBuzz::OT::Metrics` | Font metrics (x-height, cap-height, etc.) |
+| `HarfBuzz::OT::Name` | Name table access |
+| `HarfBuzz::OT::Color` | Color palette and COLR queries |
+| `HarfBuzz::OT::Math` | Math table queries |
+| `HarfBuzz::OT::Meta` | Metadata queries |
+
+### Subsetting
+
+| Class | Description |
+|-------|-------------|
+| `HarfBuzz::Subset` | Font subsetting API |
+| `HarfBuzz::Set` | Integer set for codepoints/glyphs |
+| `HarfBuzz::Map` | Integer-to-integer mapping |
+
+## Development
+
+```bash
+git clone https://github.com/ydah/harfbuzz.git
+cd harfbuzz
+bundle install
+bundle exec rake spec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ydah/harfbuzz.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## References
+
+- [HarfBuzz Documentation](https://harfbuzz.github.io/)
+- [HarfBuzz GitHub](https://github.com/harfbuzz/harfbuzz)
+- [OpenType Specification](https://learn.microsoft.com/en-us/typography/opentype/spec/)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/benchmark/shaping_bench.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# benchmark/shaping_bench.rb — HarfBuzz Ruby FFI shaping benchmarks
+#
+# Usage:
+#   bundle exec ruby benchmark/shaping_bench.rb [path/to/font.ttf]
+#
+# Requires benchmark-ips gem: gem install benchmark-ips
+
+require "benchmark/ips"
+require "harfbuzz"
+
+font_path = ARGV[0] ||
+  if File.exist?("/System/Library/Fonts/Helvetica.ttc")
+    "/System/Library/Fonts/Helvetica.ttc"
+  elsif File.exist?("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf")
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
+  else
+    raise "No test font found. Pass font path as argument: ruby benchmark/shaping_bench.rb /path/to/font.ttf"
+  end
+
+puts "HarfBuzz version: #{HarfBuzz.version_string}"
+puts "Font: #{font_path}"
+puts
+
+blob = HarfBuzz::Blob.from_file!(font_path)
+face = HarfBuzz::Face.new(blob, 0)
+font = HarfBuzz::Font.new(face)
+font.make_immutable!
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+
+  x.report("shape Latin 10 chars") do
+    buf = HarfBuzz::Buffer.new
+    buf.add_utf8("Hello Word")
+    buf.guess_segment_properties
+    HarfBuzz.shape(font, buf)
+  end
+
+  x.report("shape Latin 100 chars") do
+    buf = HarfBuzz::Buffer.new
+    buf.add_utf8("a" * 100)
+    buf.guess_segment_properties
+    HarfBuzz.shape(font, buf)
+  end
+
+  x.report("shape with buffer reuse") do |times|
+    buf = HarfBuzz::Buffer.new
+    times.times do
+      buf.clear
+      buf.add_utf8("Hello Word")
+      buf.guess_segment_properties
+      HarfBuzz.shape(font, buf)
+    end
+  end
+
+  x.report("create + destroy buffer") do
+    HarfBuzz::Buffer.new
+  end
+
+  x.report("glyph outline extraction") do
+    draw = HarfBuzz::DrawFuncs.new
+    draw.on_move_to { |_x, _y, _| }
+    draw.on_line_to { |_x, _y, _| }
+    draw.on_cubic_to { |*_args| }
+    draw.on_close_path { |_| }
+    draw.make_immutable!
+    font.draw_glyph(36, draw)
+  end
+
+  x.report("shape_text one-liner") do
+    HarfBuzz.shape_text("Hello", font_path: font_path)
+  end
+
+  x.compare!
+end

data/examples/basic_shaping.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# examples/basic_shaping.rb — Basic text shaping with HarfBuzz
+#
+# Usage: ruby examples/basic_shaping.rb [path/to/font.ttf]
+
+require "harfbuzz"
+
+font_path = ARGV[0] ||
+  if File.exist?("/System/Library/Fonts/Helvetica.ttc")
+    "/System/Library/Fonts/Helvetica.ttc"
+  elsif File.exist?("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf")
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
+  else
+    raise "No font found. Pass font path as argument."
+  end
+
+puts "=== Basic Shaping ==="
+puts "HarfBuzz #{HarfBuzz.version_string}"
+puts
+
+# --- One-liner API ---
+puts "--- shape_text (one-liner) ---"
+result = HarfBuzz.shape_text("Hello, World!", font_path: font_path)
+puts "Glyphs: #{result.length}"
+result.each do |info, pos|
+  puts "  glyph=#{info.glyph_id} cluster=#{info.cluster} x_advance=#{pos.x_advance}"
+end
+puts "Total X advance: #{result.total_advance.first}"
+puts
+
+# --- Manual API ---
+puts "--- Manual Buffer + Font API ---"
+blob   = HarfBuzz::Blob.from_file!(font_path)
+face   = HarfBuzz::Face.new(blob, 0)
+font   = HarfBuzz::Font.new(face)
+buffer = HarfBuzz::Buffer.new
+
+buffer.add_utf8("Ruby")
+buffer.guess_segment_properties
+HarfBuzz.shape(font, buffer)
+
+puts "Shaped '#{buffer.serialize}'"
+puts "Glyph count: #{buffer.length}"
+buffer.glyph_infos.zip(buffer.glyph_positions).each do |info, pos|
+  puts "  glyph_id=#{info.glyph_id} x_advance=#{pos.x_advance} y_advance=#{pos.y_advance}"
+end
+puts
+
+# --- Buffer reuse pattern ---
+puts "--- Buffer reuse ---"
+texts = ["Hello", "World", "Ruby", "HarfBuzz"]
+texts.each do |text|
+  buffer.reset
+  buffer.add_utf8(text)
+  buffer.guess_segment_properties
+  HarfBuzz.shape(font, buffer)
+  total_advance = buffer.glyph_positions.sum(&:x_advance)
+  puts "  '#{text}': #{buffer.length} glyphs, total_advance=#{total_advance}"
+end
+puts
+
+# --- RTL shaping ---
+puts "--- RTL (Arabic) ---"
+arabic_result = HarfBuzz.shape_text("مرحبا", font_path: font_path, direction: :rtl)
+puts "Arabic glyphs: #{arabic_result.length}"
+puts "Direction detected: #{HarfBuzz::Buffer.new.tap { |b| b.add_utf8("مرحبا"); b.guess_segment_properties }.direction}"

data/examples/glyph_outlines.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# examples/glyph_outlines.rb — Extract glyph outlines using DrawFuncs
+#
+# Usage: ruby examples/glyph_outlines.rb [path/to/font.ttf]
+
+require "harfbuzz"
+
+font_path = ARGV[0] ||
+  if File.exist?("/System/Library/Fonts/Helvetica.ttc")
+    "/System/Library/Fonts/Helvetica.ttc"
+  elsif File.exist?("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf")
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
+  else
+    raise "No font found. Pass font path as argument."
+  end
+
+puts "=== Glyph Outline Extraction ==="
+puts
+
+blob = HarfBuzz::Blob.from_file!(font_path)
+face = HarfBuzz::Face.new(blob, 0)
+font = HarfBuzz::Font.new(face)
+
+# --- Set up DrawFuncs ---
+draw = HarfBuzz::DrawFuncs.new
+
+commands = []
+
+draw.on_move_to do |x, y, _draw_state|
+  commands << "M #{x.round(2)},#{y.round(2)}"
+end
+
+draw.on_line_to do |x, y, _draw_state|
+  commands << "L #{x.round(2)},#{y.round(2)}"
+end
+
+draw.on_quadratic_to do |cx, cy, x, y, _draw_state|
+  commands << "Q #{cx.round(2)},#{cy.round(2)} #{x.round(2)},#{y.round(2)}"
+end
+
+draw.on_cubic_to do |c1x, c1y, c2x, c2y, x, y, _draw_state|
+  commands << "C #{c1x.round(2)},#{c1y.round(2)} #{c2x.round(2)},#{c2y.round(2)} #{x.round(2)},#{y.round(2)}"
+end
+
+draw.on_close_path do |_draw_state|
+  commands << "Z"
+end
+
+draw.make_immutable!
+
+# --- Shape text and get glyph IDs ---
+buffer = HarfBuzz::Buffer.new
+buffer.add_utf8("AB")
+buffer.guess_segment_properties
+HarfBuzz.shape(font, buffer)
+
+# --- Extract outline for each glyph ---
+buffer.glyph_infos.each do |info|
+  commands.clear
+  font.draw_glyph(info.glyph_id, draw)
+  puts "Glyph #{info.glyph_id} (cluster #{info.cluster}):"
+  if commands.empty?
+    puts "  (no outline — space or missing)"
+  else
+    puts "  SVG path: #{commands.join(" ")}"
+    puts "  Commands: #{commands.length}"
+  end
+  puts
+end
+
+# --- Glyph extents ---
+puts "--- Glyph Extents ---"
+buffer.glyph_infos.each do |info|
+  extents = font.glyph_extents(info.glyph_id)
+  if extents
+    puts "Glyph #{info.glyph_id}: x_bearing=#{extents[:x_bearing]} y_bearing=#{extents[:y_bearing]} width=#{extents[:width]} height=#{extents[:height]}"
+  end
+end

data/examples/opentype_features.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# examples/opentype_features.rb — OpenType feature queries and shaping with features
+#
+# Usage: ruby examples/opentype_features.rb [path/to/font.ttf]
+
+require "harfbuzz"
+
+font_path = ARGV[0] ||
+  if File.exist?("/System/Library/Fonts/Helvetica.ttc")
+    "/System/Library/Fonts/Helvetica.ttc"
+  elsif File.exist?("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf")
+    "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"
+  else
+    raise "No font found. Pass font path as argument."
+  end
+
+puts "=== OpenType Features ==="
+puts
+
+blob = HarfBuzz::Blob.from_file!(font_path)
+face = HarfBuzz::Face.new(blob, 0)
+font = HarfBuzz::Font.new(face)
+
+# --- List GSUB scripts ---
+puts "--- GSUB Scripts ---"
+begin
+  scripts = HarfBuzz::OT::Layout.script_tags(face, :gsub)
+  puts "Scripts: #{scripts.map { |t| HarfBuzz.tag_to_s(t) }.inspect}"
+rescue => e
+  puts "  (#{e.message})"
+end
+puts
+
+# --- List GSUB features for default script ---
+puts "--- GSUB Features (first script/language) ---"
+begin
+  features = HarfBuzz::OT::Layout.feature_tags(face, :gsub, 0, 0)
+  puts "Features: #{features.map { |t| HarfBuzz.tag_to_s(t) }.first(10).inspect}"
+rescue => e
+  puts "  (#{e.message})"
+end
+puts
+
+# --- Shaping with explicit features ---
+puts "--- Shaping with Features ---"
+font2 = HarfBuzz::Font.new(face)
+
+buf_with_liga = HarfBuzz::Buffer.new
+buf_with_liga.add_utf8("fi")
+buf_with_liga.guess_segment_properties
+HarfBuzz.shape(font2, buf_with_liga, [HarfBuzz::Feature.from_string("liga")])
+puts "With liga: #{buf_with_liga.length} glyph(s)"
+
+buf_no_liga = HarfBuzz::Buffer.new
+buf_no_liga.add_utf8("fi")
+buf_no_liga.guess_segment_properties
+HarfBuzz.shape(font2, buf_no_liga, [HarfBuzz::Feature.from_string("-liga")])
+puts "Without liga: #{buf_no_liga.length} glyph(s)"
+puts
+
+# --- Feature from hash ---
+puts "--- Feature from Hash ---"
+features = HarfBuzz::Feature.from_hash(liga: true, kern: false)
+puts "Features: #{features.map(&:to_s).inspect}"
+puts
+
+# --- Glyph class query ---
+puts "--- Glyph Classes ---"
+begin
+  has_classes = HarfBuzz::OT::Layout.has_glyph_classes?(face)
+  puts "Has glyph classes: #{has_classes}"
+  if has_classes
+    klass = HarfBuzz::OT::Layout.glyph_class(face, 65) # 'A'
+    puts "  Glyph class of glyph 65: #{klass}"
+  end
+rescue => e
+  puts "  (#{e.message})"
+end
+puts
+
+# --- OT Metrics ---
+puts "--- OT Metrics ---"
+begin
+  x_height = HarfBuzz::OT::Metrics.x_height(font)
+  puts "x-height: #{x_height}"
+  cap_height = HarfBuzz::OT::Metrics.cap_height(font)
+  puts "cap-height: #{cap_height}"
+rescue => e
+  puts "  (#{e.message})"
+end