harfbuzz-ruby 1.0.0

data/examples/render_svg.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# examples/render_svg.rb — Render shaped text to an SVG file and open it
+#
+# Usage: ruby examples/render_svg.rb [text] [path/to/font.ttf]
+#
+# Generates an SVG file from shaped text using glyph outlines and opens
+# it in the default browser.
+
+require "harfbuzz"
+
+text = ARGV[0] || "Hello, HarfBuzz!"
+font_path = ARGV[1] ||
+  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
+
+blob = HarfBuzz::Blob.from_file!(font_path)
+face = HarfBuzz::Face.new(blob, 0)
+font = HarfBuzz::Font.new(face)
+upem = face.upem
+
+# Set up draw funcs for outline extraction
+draw = HarfBuzz::DrawFuncs.new
+draw_commands = []
+
+draw.on_move_to      { |x, y| draw_commands << "M#{x.round(2)},#{(-y).round(2)}" }
+draw.on_line_to      { |x, y| draw_commands << "L#{x.round(2)},#{(-y).round(2)}" }
+draw.on_quadratic_to { |cx, cy, x, y|
+  draw_commands << "Q#{cx.round(2)},#{(-cy).round(2)},#{x.round(2)},#{(-y).round(2)}"
+}
+draw.on_cubic_to { |c1x, c1y, c2x, c2y, x, y|
+  draw_commands << "C#{c1x.round(2)},#{(-c1y).round(2)},#{c2x.round(2)},#{(-c2y).round(2)},#{x.round(2)},#{(-y).round(2)}"
+}
+draw.on_close_path { draw_commands << "Z" }
+draw.make_immutable!
+
+# Shape the text
+buffer = HarfBuzz::Buffer.new
+buffer.add_utf8(text)
+buffer.guess_segment_properties
+HarfBuzz.shape(font, buffer)
+
+infos = buffer.glyph_infos
+positions = buffer.glyph_positions
+
+# Build SVG path elements for each glyph
+svg_paths = []
+cursor_x = 0
+cursor_y = 0
+
+infos.zip(positions).each do |info, pos|
+  draw_commands.clear
+  font.draw_glyph(info.glyph_id, draw)
+
+  unless draw_commands.empty?
+    ox = cursor_x + pos.x_offset
+    oy = cursor_y + pos.y_offset
+    svg_paths << %(<path transform="translate(#{ox},#{(-oy)})" d="#{draw_commands.join}" />)
+  end
+
+  cursor_x += pos.x_advance
+  cursor_y += pos.y_advance
+end
+
+# Get font metrics for viewBox
+extents = font.extents_for_direction(:ltr)
+ascender = extents[:ascender]
+descender = extents[:descender]
+height = ascender - descender
+total_advance = positions.sum(&:x_advance)
+
+margin = (upem * 0.1).round
+vb_x = -margin
+vb_y = -(ascender + margin)
+vb_w = total_advance + margin * 2
+vb_h = height + margin * 2
+
+svg = <<~SVG
+  <?xml version="1.0" encoding="UTF-8"?>
+  <svg xmlns="http://www.w3.org/2000/svg"
+       viewBox="#{vb_x} #{vb_y} #{vb_w} #{vb_h}"
+       width="#{(vb_w.to_f / upem * 64).round}" height="#{(vb_h.to_f / upem * 64).round}">
+    <rect x="#{vb_x}" y="#{vb_y}" width="#{vb_w}" height="#{vb_h}" fill="white" />
+    <line x1="#{vb_x}" y1="0" x2="#{vb_x + vb_w}" y2="0" stroke="#ccc" stroke-width="#{upem * 0.005}" />
+    <g fill="black">
+      #{svg_paths.join("\n    ")}
+    </g>
+  </svg>
+SVG
+
+output_path = File.expand_path("render_output.svg", __dir__)
+File.write(output_path, svg)
+puts "SVG written to #{output_path}"
+puts "  Text: #{text}"
+puts "  Font: #{font_path}"
+puts "  Glyphs: #{infos.length}"
+puts "  Total advance: #{total_advance} (#{upem} upem)"
+
+# Open in default browser
+case RUBY_PLATFORM
+when /darwin/
+  system("open", output_path)
+when /linux/
+  system("xdg-open", output_path)
+when /mingw|mswin/
+  system("start", output_path)
+end

data/examples/render_waterfall.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+# examples/render_waterfall.rb — Render a variable font waterfall to HTML
+#
+# Usage: ruby examples/render_waterfall.rb /path/to/variable_font.ttf [text]
+#
+# Generates an HTML file with SVG renderings of text at different
+# variable font axis values and opens it in the default browser.
+#
+# Download a variable font from https://fonts.google.com/variablefonts
+# e.g. Roboto Flex, Inter, or Noto Sans
+
+require "harfbuzz"
+
+font_path = ARGV[0]
+unless font_path && File.exist?(font_path)
+  puts "Usage: ruby examples/render_waterfall.rb /path/to/variable_font.ttf [text]"
+  puts
+  puts "Download a variable font from https://fonts.google.com/variablefonts"
+  exit 1
+end
+
+text = ARGV[1] || "AaBbCcDdEeFf"
+
+blob = HarfBuzz::Blob.from_file!(font_path)
+face = HarfBuzz::Face.new(blob, 0)
+upem = face.upem
+
+unless HarfBuzz::OT::Var.has_data?(face)
+  puts "Error: #{font_path} is not a variable font."
+  exit 1
+end
+
+axes = HarfBuzz::OT::Var.axis_infos(face)
+wght_axis = axes.find { |a| HarfBuzz.tag_to_s(a[:tag]).strip == "wght" }
+unless wght_axis
+  puts "Error: Font has no 'wght' axis."
+  exit 1
+end
+
+# Generate weight steps
+min_w = wght_axis[:min_value]
+max_w = wght_axis[:max_value]
+steps = 7
+weights = (0...steps).map { |i| (min_w + (max_w - min_w) * i / (steps - 1)).round }
+
+# Set up draw funcs
+draw = HarfBuzz::DrawFuncs.new
+draw_commands = []
+
+draw.on_move_to      { |x, y| draw_commands << "M#{x.round(2)},#{(-y).round(2)}" }
+draw.on_line_to      { |x, y| draw_commands << "L#{x.round(2)},#{(-y).round(2)}" }
+draw.on_quadratic_to { |cx, cy, x, y|
+  draw_commands << "Q#{cx.round(2)},#{(-cy).round(2)},#{x.round(2)},#{(-y).round(2)}"
+}
+draw.on_cubic_to { |c1x, c1y, c2x, c2y, x, y|
+  draw_commands << "C#{c1x.round(2)},#{(-c1y).round(2)},#{c2x.round(2)},#{(-c2y).round(2)},#{x.round(2)},#{(-y).round(2)}"
+}
+draw.on_close_path { draw_commands << "Z" }
+draw.make_immutable!
+
+def shape_to_svg(font, face, text, draw, draw_commands)
+  upem = face.upem
+  buffer = HarfBuzz::Buffer.new
+  buffer.add_utf8(text)
+  buffer.guess_segment_properties
+  HarfBuzz.shape(font, buffer)
+
+  infos = buffer.glyph_infos
+  positions = buffer.glyph_positions
+
+  svg_paths = []
+  cursor_x = 0
+
+  infos.zip(positions).each do |info, pos|
+    draw_commands.clear
+    font.draw_glyph(info.glyph_id, draw)
+
+    unless draw_commands.empty?
+      ox = cursor_x + pos.x_offset
+      oy = pos.y_offset
+      svg_paths << %(<path transform="translate(#{ox},#{(-oy)})" d="#{draw_commands.join}" />)
+    end
+
+    cursor_x += pos.x_advance
+  end
+
+  extents = font.extents_for_direction(:ltr)
+  ascender = extents[:ascender]
+  descender = extents[:descender]
+  height = ascender - descender
+  total_advance = positions.sum(&:x_advance)
+
+  margin = (upem * 0.08).round
+  vb_x = -margin
+  vb_y = -(ascender + margin)
+  vb_w = total_advance + margin * 2
+  vb_h = height + margin * 2
+
+  pixel_height = 48
+  pixel_width = (vb_w.to_f / vb_h * pixel_height).round
+
+  <<~SVG
+    <svg xmlns="http://www.w3.org/2000/svg"
+         viewBox="#{vb_x} #{vb_y} #{vb_w} #{vb_h}"
+         width="#{pixel_width}" height="#{pixel_height}">
+      <g fill="black">#{svg_paths.join}</g>
+    </svg>
+  SVG
+end
+
+# Render each weight
+rows = weights.map do |w|
+  font = HarfBuzz::Font.new(face)
+  variation = HarfBuzz::Variation.from_string("wght=#{w}")
+  font.variations = [variation]
+
+  svg = shape_to_svg(font, face, text, draw, draw_commands)
+  { weight: w, svg: svg }
+end
+
+# Build HTML
+tag_name = HarfBuzz.tag_to_s(wght_axis[:tag]).strip
+html = <<~HTML
+  <!DOCTYPE html>
+  <html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>HarfBuzz Variable Font Waterfall</title>
+    <style>
+      body {
+        font-family: system-ui, sans-serif;
+        max-width: 900px;
+        margin: 40px auto;
+        padding: 0 20px;
+        background: #fafafa;
+        color: #333;
+      }
+      h1 { font-size: 1.4em; margin-bottom: 0.3em; }
+      p.meta { color: #888; font-size: 0.9em; margin-top: 0; }
+      table { border-collapse: collapse; width: 100%; margin-top: 20px; }
+      th, td { text-align: left; padding: 10px 16px; border-bottom: 1px solid #eee; }
+      th { color: #999; font-weight: normal; font-size: 0.85em; text-transform: uppercase; }
+      td.weight { font-variant-numeric: tabular-nums; font-size: 0.95em; width: 80px; }
+      td.render svg { display: block; }
+    </style>
+  </head>
+  <body>
+    <h1>Variable Font Waterfall</h1>
+    <p class="meta">
+      Font: #{File.basename(font_path)}<br>
+      Axis: #{tag_name} (#{min_w.round}–#{max_w.round})<br>
+      Text: "#{text}"
+    </p>
+    <table>
+      <tr><th>#{tag_name}</th><th>Rendered</th></tr>
+      #{rows.map { |r| "<tr><td class=\"weight\">#{r[:weight]}</td><td class=\"render\">#{r[:svg]}</td></tr>" }.join("\n      ")}
+    </table>
+  </body>
+  </html>
+HTML
+
+output_path = File.expand_path("waterfall_output.html", __dir__)
+File.write(output_path, html)
+puts "HTML written to #{output_path}"
+puts "  Font: #{font_path}"
+puts "  Axis: #{tag_name} (#{min_w.round}–#{max_w.round}), #{steps} steps"
+puts "  Text: #{text}"
+
+case RUBY_PLATFORM
+when /darwin/
+  system("open", output_path)
+when /linux/
+  system("xdg-open", output_path)
+when /mingw|mswin/
+  system("start", output_path)
+end

data/examples/variable_fonts.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# examples/variable_fonts.rb — Variable font axis queries and shaping
+#
+# Usage: ruby examples/variable_fonts.rb /path/to/variable_font.ttf
+#
+# A variable font is required. Download one from Google Fonts, e.g.:
+#   https://fonts.google.com/specimen/Roboto+Flex
+
+require "harfbuzz"
+
+font_path = ARGV[0]
+unless font_path && File.exist?(font_path)
+  puts "Usage: ruby examples/variable_fonts.rb /path/to/variable_font.ttf"
+  puts
+  puts "Download a variable font from https://fonts.google.com/variablefonts"
+  exit 1
+end
+
+puts "=== Variable Fonts ==="
+puts "Font: #{font_path}"
+puts
+
+blob = HarfBuzz::Blob.from_file!(font_path)
+face = HarfBuzz::Face.new(blob, 0)
+font = HarfBuzz::Font.new(face)
+
+# --- Check if font has variation data ---
+puts "--- Variation Axes ---"
+if HarfBuzz::OT::Var.has_data?(face)
+  axes = HarfBuzz::OT::Var.axis_infos(face)
+  puts "#{axes.length} axes found:"
+  axes.each do |axis|
+    tag_str = HarfBuzz.tag_to_s(axis[:tag])
+    puts "  #{tag_str}: min=#{axis[:min_value]} default=#{axis[:default_value]} max=#{axis[:max_value]}"
+  end
+else
+  puts "This font has no variation data."
+  exit 0
+end
+puts
+
+# --- Named instances ---
+puts "--- Named Instances ---"
+count = HarfBuzz::OT::Var.named_instance_count(face)
+puts "#{count} named instances"
+count.times do |i|
+  coords = HarfBuzz::OT::Var.named_instance_design_coords(face, i)
+  puts "  Instance #{i}: #{coords.inspect}"
+end
+puts
+
+# --- Apply variation to font ---
+puts "--- Applying Variations ---"
+axes = HarfBuzz::OT::Var.axis_infos(face)
+if axes.any?
+  wght_axis = axes.find { |a| HarfBuzz.tag_to_s(a[:tag]).strip == "wght" }
+  if wght_axis
+    puts "Setting weight to max (#{wght_axis[:max_value]})"
+    variation = HarfBuzz::Variation.from_string("wght=#{wght_axis[:max_value]}")
+    font.variations = [variation]
+  end
+end
+
+# Shape with varied font
+buffer = HarfBuzz::Buffer.new
+buffer.add_utf8("Hello")
+buffer.guess_segment_properties
+HarfBuzz.shape(font, buffer)
+puts "Shaped with variation: #{buffer.length} glyphs"
+buffer.glyph_positions.each do |pos|
+  puts "  x_advance=#{pos.x_advance}"
+end

data/lib/harfbuzz/aat/layout.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  module AAT
+    # Apple Advanced Typography Layout queries
+    module Layout
+      module_function
+
+      # @param face [Face] Font face
+      # @return [Boolean] true if the face has AAT morx substitution
+      def has_substitution?(face)
+        C.from_hb_bool(C.hb_aat_layout_has_substitution(face.ptr))
+      end
+
+      # @param face [Face] Font face
+      # @return [Boolean] true if the face has AAT kerning/kerx positioning
+      def has_positioning?(face)
+        C.from_hb_bool(C.hb_aat_layout_has_positioning(face.ptr))
+      end
+
+      # @param face [Face] Font face
+      # @return [Boolean] true if the face has AAT trak tracking
+      def has_tracking?(face)
+        C.from_hb_bool(C.hb_aat_layout_has_tracking(face.ptr))
+      end
+
+      # Returns feature types available in the AAT 'feat' table
+      # @param face [Face] Font face
+      # @return [Array<Integer>] Feature type values
+      def feature_types(face)
+        count_ptr = FFI::MemoryPointer.new(:uint)
+        count_ptr.write_uint(0)
+        C.hb_aat_layout_get_feature_types(face.ptr, 0, count_ptr, nil)
+        count = count_ptr.read_uint
+        return [] if count.zero?
+
+        types_ptr = FFI::MemoryPointer.new(:uint, count)
+        count_ptr.write_uint(count)
+        C.hb_aat_layout_get_feature_types(face.ptr, 0, count_ptr, types_ptr)
+        types_ptr.read_array_of_uint(count_ptr.read_uint)
+      end
+
+      # Returns the name ID for a feature type
+      # @param face [Face] Font face
+      # @param type [Integer] Feature type
+      # @return [Integer, nil] Name ID or nil
+      def feature_type_name_id(face, type)
+        name_id_ptr = FFI::MemoryPointer.new(:uint)
+        ok = C.hb_aat_layout_feature_type_get_name_id(face.ptr, type, name_id_ptr)
+        ok.zero? ? nil : name_id_ptr.read_uint
+      end
+
+      # Returns the selector infos for a feature type
+      # @param face [Face] Font face
+      # @param type [Integer] Feature type
+      # @return [Array<C::HbAatLayoutFeatureSelectorInfoT>] Selector info array
+      def selector_infos(face, type)
+        count_ptr = FFI::MemoryPointer.new(:uint)
+        count_ptr.write_uint(0)
+        C.hb_aat_layout_feature_type_get_selector_infos(face.ptr, type, 0, count_ptr, nil, nil)
+        count = count_ptr.read_uint
+        return [] if count.zero?
+
+        infos_ptr = FFI::MemoryPointer.new(C::HbAatLayoutFeatureSelectorInfoT, count)
+        count_ptr.write_uint(count)
+        C.hb_aat_layout_feature_type_get_selector_infos(
+          face.ptr, type, 0, count_ptr, infos_ptr, nil
+        )
+        actual = count_ptr.read_uint
+        actual.times.map do |i|
+          C::HbAatLayoutFeatureSelectorInfoT.new(
+            infos_ptr + i * C::HbAatLayoutFeatureSelectorInfoT.size
+          )
+        end
+      end
+    end
+  end
+end

data/lib/harfbuzz/blob.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module HarfBuzz
+  # Wraps hb_blob_t — binary data container
+  class Blob
+    attr_reader :ptr
+
+    # Creates a Blob from binary data
+    # @param data [String] Binary data
+    # @param mode [Symbol] Memory mode (:duplicate, :readonly, :writable,
+    #   :readonly_may_make_writable)
+    # @return [Blob]
+    def initialize(data, mode: :duplicate)
+      mem = FFI::MemoryPointer.from_string(data)
+      @ptr = C.hb_blob_create(mem, data.bytesize, mode, nil, nil)
+      raise AllocationError, "Failed to create blob" if @ptr.null?
+
+      # Keep mem alive until the blob is destroyed
+      @mem = mem
+      register_finalizer
+    end
+
+    # Creates a Blob from a file path. Returns an empty blob if file is missing.
+    # @param path [String] File path
+    # @return [Blob]
+    def self.from_file(path)
+      ptr = C.hb_blob_create_from_file(path)
+      wrap_owned(ptr)
+    end
+
+    # Creates a Blob from a file path. Raises if the file cannot be read.
+    # @param path [String] File path
+    # @return [Blob]
+    # @raise [AllocationError] If file cannot be read
+    def self.from_file!(path)
+      ptr = C.hb_blob_create_from_file_or_fail(path)
+      raise AllocationError, "Failed to create blob from file: #{path}" if ptr.null?
+
+      wrap_owned(ptr)
+    end
+
+    # Returns the empty (singleton) blob
+    # @return [Blob]
+    def self.empty
+      wrap_borrowed(C.hb_blob_get_empty)
+    end
+
+    # Creates a sub-blob of this blob
+    # @param offset [Integer] Byte offset into the blob
+    # @param length [Integer] Length in bytes
+    # @return [Blob]
+    def sub_blob(offset, length)
+      ptr = C.hb_blob_create_sub_blob(@ptr, offset, length)
+      self.class.wrap_owned(ptr)
+    end
+
+    # Returns a writable copy of this blob, or nil if it fails
+    # @return [Blob, nil]
+    def writable_copy
+      ptr = C.hb_blob_copy_writable_or_fail(@ptr)
+      return nil if ptr.null?
+
+      self.class.wrap_owned(ptr)
+    end
+
+    # @return [Integer] Blob length in bytes
+    def length
+      C.hb_blob_get_length(@ptr)
+    end
+
+    alias size length
+
+    # @return [String] Blob data as a Ruby String (read-only)
+    def data
+      length_ptr = FFI::MemoryPointer.new(:uint)
+      data_ptr = C.hb_blob_get_data(@ptr, length_ptr)
+      return "".b if data_ptr.null?
+
+      data_ptr.read_bytes(length_ptr.read_uint)
+    end
+
+    # @return [String, nil] Blob data as a writable Ruby String, or nil if blob is immutable
+    def data_writable
+      length_ptr = FFI::MemoryPointer.new(:uint)
+      data_ptr = C.hb_blob_get_data_writable(@ptr, length_ptr)
+      return nil if data_ptr.null?
+
+      data_ptr.read_bytes(length_ptr.read_uint)
+    end
+
+    # @return [Boolean] true if the blob is immutable
+    def immutable?
+      C.from_hb_bool(C.hb_blob_is_immutable(@ptr))
+    end
+
+    # Makes the blob immutable
+    # @return [self]
+    def make_immutable!
+      C.hb_blob_make_immutable(@ptr)
+      self
+    end
+
+    def inspect
+      "#<HarfBuzz::Blob length=#{length} immutable=#{immutable?}>"
+    end
+
+    # Wraps an owned pointer (will be destroyed via finalizer)
+    def self.wrap_owned(ptr)
+      obj = allocate
+      obj.instance_variable_set(:@ptr, ptr)
+      obj.send(:register_finalizer)
+      obj
+    end
+
+    # Wraps a borrowed pointer (no finalizer — caller owns the lifetime)
+    def self.wrap_borrowed(ptr)
+      obj = allocate
+      obj.instance_variable_set(:@ptr, ptr)
+      obj.instance_variable_set(:@borrowed, true)
+      obj
+    end
+
+    private
+
+    def register_finalizer
+      return if instance_variable_defined?(:@borrowed) && @borrowed
+
+      HarfBuzz::Blob.define_finalizer(self, @ptr)
+    end
+
+    def self.define_finalizer(obj, ptr)
+      destroy = C.method(:hb_blob_destroy)
+      ObjectSpace.define_finalizer(obj, proc { destroy.call(ptr) })
+    end
+  end
+end