alhena 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 35e4670f6299d744074cb8bc0c64eba91b2f0691d07f1034b9a5ae7423c9dffa
+  data.tar.gz: 0df90b79072d3f967af91362b80b4cd7ba3c78dcf72a8e3e61d7227c1933ec91
+SHA512:
+  metadata.gz: 4fd434b589dc0feb1c2e71ab0553b3b8059e11613ffa6cbeae33550456c10a2547e811b61fd94a6310e5f53248459967ff2ecc634fc9eda389e2876d62554bd3
+  data.tar.gz: 2b80e1d2e093842035364cecc9ad4a5be2389dcdfbd4589ebc776c99f95be3149451fd9977c2455bba5c5da824d4601cc0d1059ff68357487ba7a28eb66bb991

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-09-11
+
+- 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,178 @@
+<div align="center">
+  <h1>Alhena</h1>
+  <p><strong>Pure Ruby TrueType/OpenType/TTC font rasterization with antialiased glyph bitmaps</strong></p>
+  <p>
+    <a href="https://rubygems.org/gems/alhena"><img src="https://img.shields.io/gem/v/alhena.svg?colorB=319e8c" alt="Gem Version"></a>
+    <a href="https://rubygems.org/gems/alhena"><img src="https://img.shields.io/gem/dt/alhena.svg" alt="Downloads"></a>
+    <a href="https://github.com/noxdea/alhena/actions/workflows/main.yml"><img src="https://github.com/noxdea/alhena/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+    <img src="https://img.shields.io/badge/ruby-%3E%3D%203.1-ruby.svg" alt="Ruby Version">
+    <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+  </p>
+</div>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#supported-formats">Supported Formats</a> ·
+  <a href="#development">Development</a>
+</p>
+
+---
+
+Alhena reads TrueType, OpenType, and TTC fonts, extracts their outlines, and rasterizes antialiased grayscale, LCD, and color glyph bitmaps. It requires Ruby 3.1+ and has no runtime gem dependencies or native extensions.
+
+## Features
+
+- TrueType, OpenType CFF1/CFF2, and TTC font parsing
+- Analytic grayscale and LCD rasterization with subpixel positioning
+- Variable font axes, outlines, and metrics
+- COLR/CPAL, sbix, and CBDT/CBLC color glyphs
+- Entry- and byte-bounded LRU glyph cache
+- Lazy, bounds-checked table parsing
+- RBS type signatures
+
+## Installation
+
+Add Alhena to your Gemfile:
+
+```ruby
+gem "alhena"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install it directly:
+
+```sh
+gem install alhena
+```
+
+## Quick Start
+
+```ruby
+require "alhena"
+
+font = Alhena::Font.open("/path/to/font.ttf")
+glyph = font.glyph_id("A")
+bitmap = font.rasterize(glyph, size: 24)
+
+puts font.family
+puts bitmap.to_ascii
+```
+
+`bitmap.coverage` is an immutable binary String. Grayscale bitmaps contain one coverage byte per pixel; LCD bitmaps contain three. `width`, `height`, `left`, and `top` describe the bitmap and its bearing. Advances are separate:
+
+```ruby
+advance = font.advance(glyph, size: 24)
+```
+
+## Usage
+
+### Fonts and metrics
+
+`Font.open(path, index: 0)` reads a font file. `Font.new(bytes, index: 0)` accepts font bytes directly. Tables are parsed on demand.
+
+Metadata methods include `family`, `names`, `units_per_em`, `ascent`, `descent`, `line_gap`, `glyph_count`, `os2`, and `post`. `advance` and `bearing` accept `vertical: true`. `glyph_id` accepts a character or Unicode scalar and an optional `variation_selector:`; unmapped characters return glyph 0.
+
+### Outlines and rasterization
+
+```ruby
+outline = font.outline(glyph) # font coordinates, Y up
+outline.each { |operation, *coordinates| p [operation, coordinates] }
+
+path = Alhena::Outline.new
+path.move_to(0, 0).quad_to(50, 100, 100, 0).close
+bitmap = Alhena::Rasterizer.new(width: 100, height: 100).fill(path)
+```
+
+`Outline` supports lines, quadratic and cubic curves, transforms, bounds, appending, and cubic-to-quadratic conversion. `Rasterizer#fill` uses pixel coordinates with Y down and implicitly closes open subpaths.
+
+`Font#rasterize` and `Rasterizer#fill` accept `gamma:`, `darkening:`, and `lcd: :rgb` or `:bgr`. Use grayscale when the display subpixel order is unknown.
+
+### Glyph cache
+
+```ruby
+cache = Alhena::Cache.new(capacity: 4096, max_bytes: 16 * 1024 * 1024)
+cache.prewarm(font, "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ", size: 24)
+bitmap = cache.rasterize(font, glyph, size: 24, subpixel_x: 0.25)
+```
+
+The cache quantizes horizontal positions to quarter pixels and evicts least-recently-used entries. Cache and rasterizer instances are intended for one owner; protect shared instances or use one per thread.
+
+### Variable fonts
+
+```ruby
+font.axes
+bold = font.variation(wght: 700, wdth: 90)
+```
+
+You can also pass axes to `Font.open(path, axes: {wght: 700})`. Unspecified axes use their defaults, and out-of-range values are clamped.
+
+### Color glyphs
+
+```ruby
+color = font.color_bitmap(glyph, size: 48, palette: 0)
+rgba = color&.rgba
+```
+
+`ColorBitmap#rgba` stores straight sRGB RGBA8 pixels, and `to_bitmap` extracts alpha coverage. `Font#rasterize` automatically returns alpha coverage for supported color glyphs. `embedded_bitmap` exposes original sbix/CBDT image data and strike metrics.
+
+## Supported Formats
+
+- sfnt TrueType, OpenType CFF1/CFF2, and TTC collections
+- Unicode `cmap` formats 0, 4, 6, 12, 13, and 14
+- Simple and composite `glyf` outlines with short or long `loca`
+- Type 2 charstrings, CID CFF, variation stores, and CFF2 blends
+- `fvar`, `gvar`, `avar` v1, HVAR, and VVAR variable font data
+- COLR/CPAL v0, sbix PNG, and CBDT/CBLC PNG, grayscale, BGRA, and composite bitmaps
+
+### Limits
+
+Alhena does not provide TrueType hinting, shaping, GSUB/GPOS, kerning, system font discovery, COLR v1 paint graphs, avar v2, JPEG/TIFF decoding, or MVAR global metric variation. Use `embedded_bitmap` to retrieve unsupported sbix image formats for external decoding.
+
+Unknown formats raise `Alhena::UnsupportedFont`; malformed bounds and structures raise `Alhena::InvalidFont`. Bitmap allocations are limited to 16,777,216 samples.
+
+## Performance
+
+Measurements below are medians of five batches on Ruby 4.0.0 with YJIT on arm64-darwin24. Run `ruby --yjit bench/bench.rb` to reproduce them.
+
+| Operation | Measured | Budget |
+|---|---:|---:|
+| Open Noto Sans (569,208 bytes) | 64.73 µs | 30,000 µs |
+| A at 14px, uncached | 40.11 µs | 500 µs |
+| A at 14px, cache hit | 0.48 µs | 5 µs |
+| ASCII 95 glyph prewarm | 4.79 ms | 60 ms |
+| 鬱 at 48px, uncached | 0.47 ms | 3 ms |
+
+Cache glyphs in interactive applications so each glyph is normally rasterized once per size and position. These measurements are local evidence, not universal guarantees.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rake test:oracle
+bundle exec rake test:fuzz
+bundle exec rake bench:assert
+```
+
+Oracle tests compare Alhena with FreeType, ttfunk, and committed PNG references. FreeType is development-only; install `libfreetype6` on Linux or `freetype` with Homebrew on macOS, or set `FREETYPE_LIBRARY`. Optional oracle dependencies are skipped when unavailable.
+
+Render the bundled examples with:
+
+```sh
+bundle exec ruby examples/render.rb test/fonts/NotoSans-Regular.ttf "Hello, Ruby!" 48 text.png
+bundle exec ruby examples/color.rb test/fonts/NotoColorEmoji.ttf "😀" 64 color.png
+```
+
+See the [changelog](CHANGELOG.md) for release history. Bug reports and pull requests are welcome on [GitHub](https://github.com/noxdea/alhena).
+
+## License
+
+Alhena is available under the [MIT License](LICENSE.txt). Test font licenses and upstream sources are recorded in [test/fonts/README.md](test/fonts/README.md).

data/examples/color.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "alhena"
+require "chunky_png"
+
+font = Alhena::Font.open(ARGV.fetch(0))
+glyph = font.glyph_id(ARGV.fetch(1, "😀"))
+bitmap = font.color_bitmap(glyph, size: Integer(ARGV.fetch(2, "64")))
+abort "The glyph has no supported color image" unless bitmap
+image = ChunkyPNG::Image.new(bitmap.width, bitmap.height, bitmap.rgba.unpack("N*"))
+image.save(ARGV.fetch(3, "color.png"))

data/examples/render.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+require "alhena"
+require "chunky_png"
+
+font = Alhena::Font.open(ARGV.fetch(0))
+text, size = ARGV.fetch(1, "Hello, Ruby!"), Integer(ARGV.fetch(2, "48"))
+glyphs = text.codepoints.map { |code| font.glyph_id(code) }
+width = glyphs.sum { |glyph| font.advance(glyph, size: size) }.ceil + 16
+height = ((font.ascent - font.descent) * size.to_f / font.units_per_em).ceil + 16
+baseline = (font.ascent * size.to_f / font.units_per_em).ceil + 8
+image = ChunkyPNG::Image.new(width, height, ChunkyPNG::Color::WHITE)
+x = 8.0
+glyphs.each do |glyph|
+  bitmap = font.rasterize(glyph, size: size, subpixel_x: x % 1)
+  bitmap.coverage.each_byte.with_index do |value, i|
+    col, row = x.floor + bitmap.left + i % bitmap.width, baseline - bitmap.top + i / bitmap.width
+    image[col, row] = ChunkyPNG::Color.grayscale(255 - value) if col >= 0 && col < width && row >= 0 && row < height
+  end
+  x += font.advance(glyph, size: size)
+end
+image.save(ARGV.fetch(3, "text.png"))

data/lib/alhena/binary.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Alhena
+  # Bounded big-endian reads shared by sfnt, glyf and CFF.
+  class Binary
+    attr_reader :data
+    attr_accessor :position
+
+    def initialize(data)
+      @data, @position = data, 0
+    end
+
+    def size = @data.bytesize
+
+    def bytes(offset, length)
+      validate_bounds(offset, length)
+      @data.byteslice(offset, length)
+    end
+
+    def validate_bounds(offset, length)
+      raise InvalidFont, "font data out of bounds at #{offset} (#{length} bytes)" unless offset.is_a?(Integer) && length.is_a?(Integer) && offset >= 0 && length >= 0 && offset <= size - length
+    end
+    alias check validate_bounds
+
+    def u8(offset = nil) = number(offset, 1, "C")
+    def i8(offset = nil) = number(offset, 1, "c")
+    def u16(offset = nil) = number(offset, 2, "n")
+    def i16(offset = nil) = number(offset, 2, "s>")
+    def u32(offset = nil) = number(offset, 4, "N")
+    def i32(offset = nil) = number(offset, 4, "l>")
+    def fixed(offset = nil) = i32(offset) / 65_536.0
+
+    def u24(offset = nil)
+      offset ||= @position
+      validate_bounds(offset, 3)
+      @position = offset + 3
+      (@data.getbyte(offset) << 16) | (@data.getbyte(offset + 1) << 8) | @data.getbyte(offset + 2)
+    end
+
+    private
+
+    def number(offset, length, format)
+      offset ||= @position
+      validate_bounds(offset, length)
+      @position = offset + length
+      @data.unpack1(format, offset: offset)
+    end
+  end
+end

data/lib/alhena/bitmap.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Alhena
+  # Immutable, tightly packed R8 or RGB8 coverage. Y increases downwards.
+  class Bitmap
+    attr_reader :width, :height, :left, :top, :coverage, :channels
+
+    def initialize(width:, height:, coverage:, left: 0, top: 0, channels: 1)
+      unless [width, height].all? { |n| n.is_a?(Integer) && n >= 0 } && [1, 3].include?(channels) && coverage.bytesize == width * height * channels
+        raise ArgumentError, "invalid bitmap dimensions or coverage length"
+      end
+      @width, @height, @left, @top, @channels = width, height, left, top, channels
+      @coverage = coverage.b.freeze
+      freeze
+    end
+
+    def to_ascii(ramp: " .:-=+*#%@")
+      raise ArgumentError, "ramp is empty" if ramp.empty?
+      (0...height).map do |y|
+        (0...width).map do |x|
+          value = (0...channels).sum { |c| coverage.getbyte((y * width + x) * channels + c) } / channels
+          ramp[(value * (ramp.length - 1) / 255.0).round]
+        end.join
+      end.join("\n")
+    end
+  end
+end

data/lib/alhena/cache.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Alhena
+  # Per-instance LRU, bounded by entry count and optionally coverage bytes.
+  class Cache
+    attr_reader :capacity, :bytesize
+
+    def initialize(capacity: 4096, max_bytes: nil)
+      raise ArgumentError, "capacity must be positive" unless capacity.is_a?(Integer) && capacity > 0
+      raise ArgumentError, "max_bytes must be positive" if max_bytes && !(max_bytes.is_a?(Integer) && max_bytes > 0)
+      @capacity, @max_bytes, @bytesize, @entries = capacity, max_bytes, 0, {}
+    end
+
+    def size = @entries.size
+
+    # @return [Bitmap] immutable coverage, reused on an LRU cache hit
+    def rasterize(font, glyph, size:, subpixel_x: 0, **options)
+      raise ArgumentError, "invalid subpixel position" unless subpixel_x.is_a?(Numeric) && subpixel_x.finite?
+      bucket = (subpixel_x * 4).round
+      key = [font, glyph, size, bucket, options]
+      if (hit = @entries.delete(key))
+        return @entries[key] = hit
+      end
+      bitmap = font.rasterize(glyph, size: size, subpixel_x: bucket / 4.0, **options)
+      return bitmap if @max_bytes && bitmap.coverage.bytesize > @max_bytes
+      @entries[key] = bitmap
+      @bytesize += bitmap.coverage.bytesize
+      while @entries.size > @capacity || (@max_bytes && @bytesize > @max_bytes)
+        @bytesize -= @entries.shift.last.coverage.bytesize
+      end
+      bitmap
+    end
+
+    def prewarm(font, text, size = nil, **options)
+      size ||= options.delete(:size)
+      text.each_codepoint { |code| rasterize(font, font.glyph_id(code), size: size, **options) }
+      self
+    end
+
+    def clear
+      @entries.clear
+      @bytesize = 0
+      self
+    end
+  end
+end