fontisan 0.1.0 → 0.2.0

data/lib/fontisan/tables/gvar.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../binary/base_record"
+
+module Fontisan
+  module Tables
+    # Parser for the 'gvar' (Glyph Variations) table
+    #
+    # The gvar table provides variation data for glyph outlines in TrueType
+    # variable fonts. It contains delta values for each glyph's control points
+    # that are applied based on the current design space coordinates.
+    #
+    # Unlike HVAR/VVAR/MVAR which use ItemVariationStore, gvar uses a
+    # TupleVariationStore structure with packed delta values.
+    #
+    # Reference: OpenType specification, gvar table
+    #
+    # @example Reading a gvar table
+    #   data = font.table_data("gvar")
+    #   gvar = Fontisan::Tables::Gvar.read(data)
+    #   deltas = gvar.glyph_variations(glyph_id)
+    class Gvar < Binary::BaseRecord
+      uint16 :major_version
+      uint16 :minor_version
+      uint16 :axis_count
+      uint16 :shared_tuple_count
+      uint32 :shared_tuples_offset
+      uint16 :glyph_count
+      uint16 :flags
+      uint32 :glyph_variation_data_array_offset
+
+      # Flags
+      SHARED_POINT_NUMBERS = 0x8000
+      LONG_OFFSETS = 0x0001
+
+      # Tuple variation header
+      class TupleVariationHeader < Binary::BaseRecord
+        uint16 :variation_data_size
+        uint16 :tuple_index
+
+        # Tuple index flags
+        EMBEDDED_PEAK_TUPLE = 0x8000
+        INTERMEDIATE_REGION = 0x4000
+        PRIVATE_POINT_NUMBERS = 0x2000
+        TUPLE_INDEX_MASK = 0x0FFF
+
+        # Check if tuple has embedded peak coordinates
+        #
+        # @return [Boolean] True if embedded
+        def embedded_peak_tuple?
+          (tuple_index & EMBEDDED_PEAK_TUPLE) != 0
+        end
+
+        # Check if tuple has intermediate region
+        #
+        # @return [Boolean] True if intermediate region
+        def intermediate_region?
+          (tuple_index & INTERMEDIATE_REGION) != 0
+        end
+
+        # Check if tuple has private point numbers
+        #
+        # @return [Boolean] True if private points
+        def private_point_numbers?
+          (tuple_index & PRIVATE_POINT_NUMBERS) != 0
+        end
+
+        # Get shared tuple index
+        #
+        # @return [Integer] Tuple index
+        def shared_tuple_index
+          tuple_index & TUPLE_INDEX_MASK
+        end
+      end
+
+      # Get version as a float
+      #
+      # @return [Float] Version number (e.g., 1.0)
+      def version
+        major_version + (minor_version / 10.0)
+      end
+
+      # Check if using long offsets
+      #
+      # @return [Boolean] True if long offsets
+      def long_offsets?
+        (flags & LONG_OFFSETS) != 0
+      end
+
+      # Check if using shared point numbers
+      #
+      # @return [Boolean] True if shared points
+      def shared_point_numbers?
+        (flags & SHARED_POINT_NUMBERS) != 0
+      end
+
+      # Parse shared tuples
+      #
+      # @return [Array<Array<Integer>>] Shared peak tuples
+      def shared_tuples
+        return @shared_tuples if @shared_tuples
+        return @shared_tuples = [] if shared_tuple_count.zero?
+
+        data = raw_data
+        offset = shared_tuples_offset
+
+        return @shared_tuples = [] if offset >= data.bytesize
+
+        @shared_tuples = Array.new(shared_tuple_count) do |i|
+          tuple_offset = offset + (i * axis_count * 2)
+
+          Array.new(axis_count) do |j|
+            coord_offset = tuple_offset + (j * 2)
+            next nil if coord_offset + 2 > data.bytesize
+
+            # F2DOT14 format
+            value = data.byteslice(coord_offset, 2).unpack1("n")
+            signed = value > 0x7FFF ? value - 0x10000 : value
+            signed / 16384.0
+          end.compact
+        end.compact
+      end
+
+      # Parse glyph variation data offsets
+      #
+      # @return [Array<Integer>] Array of offsets
+      def glyph_variation_data_offsets
+        return @glyph_offsets if @glyph_offsets
+
+        data = raw_data
+        # Offsets start after the header (20 bytes)
+        offset = 20
+
+        offset_size = long_offsets? ? 4 : 2
+        offset_count = glyph_count + 1 # One extra for the end
+
+        @glyph_offsets = Array.new(offset_count) do |i|
+          offset_pos = offset + (i * offset_size)
+          next nil if offset_pos + offset_size > data.bytesize
+
+          raw_offset = if long_offsets?
+                         data.byteslice(offset_pos, 4).unpack1("N")
+                       else
+                         data.byteslice(offset_pos, 2).unpack1("n") * 2
+                       end
+
+          glyph_variation_data_array_offset + raw_offset
+        end.compact
+      end
+
+      # Get variation data for a specific glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @return [String, nil] Raw variation data or nil
+      def glyph_variation_data(glyph_id)
+        return nil if glyph_id >= glyph_count
+
+        offsets = glyph_variation_data_offsets
+        return nil if glyph_id >= offsets.length - 1
+
+        start_offset = offsets[glyph_id]
+        end_offset = offsets[glyph_id + 1]
+
+        return nil if start_offset == end_offset # No data
+
+        data = raw_data
+        return nil if end_offset > data.bytesize
+
+        data.byteslice(start_offset, end_offset - start_offset)
+      end
+
+      # Parse tuple variation headers for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @return [Array<Hash>, nil] Array of tuple info or nil
+      def glyph_tuple_variations(glyph_id)
+        var_data = glyph_variation_data(glyph_id)
+        return nil if var_data.nil? || var_data.empty?
+
+        io = StringIO.new(var_data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Read header
+        tuple_count_and_offset = io.read(4).unpack1("N")
+        tuple_count = tuple_count_and_offset >> 16
+        data_offset = tuple_count_and_offset & 0xFFFF
+
+        # Check for shared point numbers
+        has_shared_points = (tuple_count & 0x8000) != 0
+        tuple_count &= 0x0FFF
+
+        return [] if tuple_count.zero?
+
+        # Parse each tuple
+        tuples = []
+        tuple_count.times do
+          header_data = io.read(4)
+          break if header_data.nil? || header_data.bytesize < 4
+
+          header = TupleVariationHeader.read(header_data)
+
+          tuple_info = {
+            data_size: header.variation_data_size,
+            embedded_peak: header.embedded_peak_tuple?,
+            intermediate: header.intermediate_region?,
+            private_points: header.private_point_numbers?,
+            shared_index: header.shared_tuple_index,
+          }
+
+          # Read peak tuple if embedded
+          if header.embedded_peak_tuple?
+            peak = Array.new(axis_count) do
+              coord_data = io.read(2)
+              break nil if coord_data.nil?
+
+              value = coord_data.unpack1("n")
+              signed = value > 0x7FFF ? value - 0x10000 : value
+              signed / 16384.0
+            end
+            tuple_info[:peak] = peak.compact
+          end
+
+          # Read intermediate region if present
+          if header.intermediate_region?
+            start_tuple = Array.new(axis_count) do
+              coord_data = io.read(2)
+              break nil if coord_data.nil?
+
+              value = coord_data.unpack1("n")
+              signed = value > 0x7FFF ? value - 0x10000 : value
+              signed / 16384.0
+            end
+
+            end_tuple = Array.new(axis_count) do
+              coord_data = io.read(2)
+              break nil if coord_data.nil?
+
+              value = coord_data.unpack1("n")
+              signed = value > 0x7FFF ? value - 0x10000 : value
+              signed / 16384.0
+            end
+
+            tuple_info[:start] = start_tuple.compact
+            tuple_info[:end] = end_tuple.compact
+          end
+
+          tuples << tuple_info
+        end
+
+        {
+          tuple_count: tuple_count,
+          has_shared_points: has_shared_points,
+          data_offset: data_offset,
+          tuples: tuples,
+        }
+      rescue StandardError => e
+        warn "Failed to parse glyph tuple variations: #{e.message}"
+        nil
+      end
+
+      # Check if table is valid
+      #
+      # @return [Boolean] True if valid
+      def valid?
+        major_version == 1 && minor_version.zero?
+      end
+    end
+  end
+end

data/lib/fontisan/tables/hhea.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../binary/base_record"
+
+module Fontisan
+  module Tables
+    # BinData structure for the 'hhea' (Horizontal Header) table
+    #
+    # The hhea table contains horizontal layout metrics for the entire font.
+    # It defines font-wide horizontal metrics such as ascent, descent, line
+    # gap, and the number of horizontal metrics in the hmtx table.
+    #
+    # Reference: OpenType specification, hhea table
+    # https://docs.microsoft.com/en-us/typography/opentype/spec/hhea
+    #
+    # @example Reading an hhea table
+    #   data = File.binread("font.ttf", 36, hhea_offset)
+    #   hhea = Fontisan::Tables::Hhea.read(data)
+    #   puts hhea.ascent           # => 2048
+    #   puts hhea.descent          # => -512
+    #   puts hhea.version_number   # => 1.0
+    class Hhea < Binary::BaseRecord
+      # Table size in bytes (fixed size)
+      TABLE_SIZE = 36
+
+      # Version as 16.16 fixed-point (stored as int32)
+      # Typically 0x00010000 (1.0)
+      int32 :version_raw
+
+      # Typographic ascent (distance from baseline to highest ascender)
+      # Positive value in FUnits
+      int16 :ascent
+
+      # Typographic descent (distance from baseline to lowest descender)
+      # Negative value in FUnits
+      int16 :descent
+
+      # Typographic line gap (additional space between lines)
+      # Non-negative value in FUnits
+      int16 :line_gap
+
+      # Maximum advance width value in hmtx table
+      uint16 :advance_width_max
+
+      # Minimum left sidebearing value in hmtx table
+      int16 :min_left_side_bearing
+
+      # Minimum right sidebearing value in hmtx table
+      int16 :min_right_side_bearing
+
+      # Maximum extent: max(lsb + (xMax - xMin))
+      int16 :x_max_extent
+
+      # Used to calculate slope of the cursor (rise/run)
+      # For vertical text: rise = 1, run = 0
+      # For italic text: rise != run
+      int16 :caret_slope_rise
+
+      # Used to calculate slope of the cursor (rise/run)
+      # For vertical text: run = 0
+      int16 :caret_slope_run
+
+      # Amount by which slanted highlight should be shifted
+      int16 :caret_offset
+
+      # Reserved fields (must be zero)
+      # 4 x int16 = 8 bytes
+      skip length: 8
+
+      # Format of metric data (0 for current format)
+      int16 :metric_data_format
+
+      # Number of hMetric entries in hmtx table
+      # Must be >= 1
+      uint16 :number_of_h_metrics
+
+      # Convert version from fixed-point to float
+      #
+      # @return [Float] Version number (typically 1.0)
+      def version
+        fixed_to_float(version_raw)
+      end
+
+      # Check if the table is valid
+      #
+      # @return [Boolean] True if valid, false otherwise
+      def valid?
+        # Version should be 1.0 (0x00010000)
+        return false unless version_raw == 0x00010000
+
+        # Metric data format must be 0
+        return false unless metric_data_format.zero?
+
+        # Number of metrics must be at least 1
+        return false unless number_of_h_metrics >= 1
+
+        true
+      end
+
+      # Validate the table and raise error if invalid
+      #
+      # @raise [Fontisan::CorruptedTableError] If table is invalid
+      def validate!
+        unless version_raw == 0x00010000
+          message = "Invalid hhea version: expected 0x00010000 (1.0), " \
+                    "got 0x#{version_raw.to_i.to_s(16).upcase}"
+          raise Fontisan::CorruptedTableError, message
+        end
+
+        unless metric_data_format.zero?
+          message = "Invalid metric data format: expected 0, " \
+                    "got #{metric_data_format.to_i}"
+          raise Fontisan::CorruptedTableError, message
+        end
+
+        unless number_of_h_metrics >= 1
+          message = "Invalid number of h metrics: must be >= 1, " \
+                    "got #{number_of_h_metrics.to_i}"
+          raise Fontisan::CorruptedTableError, message
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/tables/hmtx.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+require_relative "../binary/base_record"
+
+module Fontisan
+  module Tables
+    # Parser for the 'hmtx' (Horizontal Metrics) table
+    #
+    # The hmtx table contains horizontal metrics for each glyph in the font.
+    # It provides advance width and left sidebearing values needed for proper
+    # glyph positioning and text layout.
+    #
+    # Structure:
+    # - hMetrics[numberOfHMetrics]: Array of LongHorMetric records
+    #   Each record contains:
+    #   - advanceWidth (uint16): Advance width in FUnits
+    #   - lsb (int16): Left side bearing in FUnits
+    # - leftSideBearings[numGlyphs - numberOfHMetrics]: Array of int16 values
+    #   Additional LSB values for glyphs beyond numberOfHMetrics
+    #
+    # The table is context-dependent and requires:
+    # - numberOfHMetrics from hhea table
+    # - numGlyphs from maxp table
+    #
+    # Reference: OpenType specification, hmtx table
+    # https://docs.microsoft.com/en-us/typography/opentype/spec/hmtx
+    #
+    # @example Parsing hmtx with context
+    #   # Get required tables first
+    #   hhea = font.table('hhea')
+    #   maxp = font.table('maxp')
+    #
+    #   # Parse hmtx with context
+    #   data = font.read_table_data('hmtx')
+    #   hmtx = Fontisan::Tables::Hmtx.read(data)
+    #   hmtx.parse_with_context(hhea.number_of_h_metrics, maxp.num_glyphs)
+    #
+    #   # Get metrics for a glyph
+    #   metric = hmtx.metric_for(42)
+    #   puts "Advance width: #{metric[:advance_width]}"
+    #   puts "LSB: #{metric[:lsb]}"
+    class Hmtx < Binary::BaseRecord
+      # LongHorMetric record structure
+      #
+      # @!attribute advance_width
+      #   @return [Integer] Advance width in FUnits
+      # @!attribute lsb
+      #   @return [Integer] Left side bearing in FUnits
+      class LongHorMetric < Binary::BaseRecord
+        uint16 :advance_width
+        int16 :lsb
+
+        # Convert to hash for convenience
+        #
+        # @return [Hash] Hash with :advance_width and :lsb keys
+        def to_h
+          { advance_width: advance_width, lsb: lsb }
+        end
+      end
+
+      # Store the raw data for deferred parsing
+      attr_accessor :raw_data
+
+      # Parsed horizontal metrics array
+      # @return [Array<Hash>] Array of metrics hashes
+      attr_reader :h_metrics
+
+      # Parsed left side bearings array
+      # @return [Array<Integer>] Array of LSB values
+      attr_reader :left_side_bearings
+
+      # Number of horizontal metrics from hhea table
+      # @return [Integer] Number of LongHorMetric records
+      attr_reader :number_of_h_metrics
+
+      # Total number of glyphs from maxp table
+      # @return [Integer] Total glyph count
+      attr_reader :num_glyphs
+
+      # Override read to capture raw data
+      #
+      # @param io [IO, String] Input data
+      # @return [Hmtx] Parsed table instance
+      def self.read(io)
+        instance = new
+
+        # Handle nil or empty data gracefully
+        instance.raw_data = if io.nil?
+                              "".b
+                            elsif io.is_a?(String)
+                              io
+                            else
+                              io.read || "".b
+                            end
+
+        instance
+      end
+
+      # Parse the table with font context
+      #
+      # This method must be called after reading the table data, providing
+      # the numberOfHMetrics from hhea and numGlyphs from maxp.
+      #
+      # @param number_of_h_metrics [Integer] Number of LongHorMetric records (from hhea)
+      # @param num_glyphs [Integer] Total number of glyphs (from maxp)
+      # @raise [ArgumentError] If context parameters are invalid
+      # @raise [Fontisan::CorruptedTableError] If table data is insufficient
+      def parse_with_context(number_of_h_metrics, num_glyphs)
+        validate_context_params(number_of_h_metrics, num_glyphs)
+
+        @number_of_h_metrics = number_of_h_metrics
+        @num_glyphs = num_glyphs
+
+        io = StringIO.new(raw_data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Parse hMetrics array
+        @h_metrics = parse_h_metrics(io, number_of_h_metrics)
+
+        # Parse additional left side bearings
+        lsb_count = num_glyphs - number_of_h_metrics
+        @left_side_bearings = parse_left_side_bearings(io, lsb_count)
+
+        validate_parsed_data!(io)
+      end
+
+      # Get horizontal metrics for a specific glyph ID
+      #
+      # For glyph IDs less than numberOfHMetrics, returns the corresponding
+      # hMetrics entry. For glyph IDs >= numberOfHMetrics, uses the last
+      # advance width from hMetrics with the indexed left side bearing.
+      #
+      # @param glyph_id [Integer] Glyph ID (0-based)
+      # @return [Hash, nil] Hash with :advance_width and :lsb keys, or nil if invalid
+      # @raise [RuntimeError] If table has not been parsed with context
+      #
+      # @example Getting metrics
+      #   metric = hmtx.metric_for(0)  # .notdef glyph
+      #   metric = hmtx.metric_for(65) # 'A' glyph (if mapped to 65)
+      def metric_for(glyph_id)
+        raise "Table not parsed. Call parse_with_context first." unless @h_metrics
+
+        return nil if glyph_id >= num_glyphs || glyph_id.negative?
+
+        if glyph_id < h_metrics.length
+          # Direct lookup in hMetrics array
+          h_metrics[glyph_id]
+        else
+          # Use last advance width with indexed LSB
+          lsb_index = glyph_id - h_metrics.length
+          {
+            advance_width: h_metrics.last[:advance_width],
+            lsb: left_side_bearings[lsb_index],
+          }
+        end
+      end
+
+      # Check if the table has been parsed with context
+      #
+      # @return [Boolean] True if parsed, false otherwise
+      def parsed?
+        !@h_metrics.nil?
+      end
+
+      # Get the expected minimum size for this table
+      #
+      # @return [Integer] Minimum size in bytes, or nil if not parsed
+      def expected_min_size
+        return nil unless parsed?
+
+        # numberOfHMetrics × 4 bytes (uint16 + int16)
+        # + (numGlyphs - numberOfHMetrics) × 2 bytes (int16)
+        (number_of_h_metrics * 4) + ((num_glyphs - number_of_h_metrics) * 2)
+      end
+
+      private
+
+      # Validate context parameters
+      #
+      # @param number_of_h_metrics [Integer] Number of hMetrics
+      # @param num_glyphs [Integer] Total glyphs
+      # @raise [ArgumentError] If parameters are invalid
+      def validate_context_params(number_of_h_metrics, num_glyphs)
+        if number_of_h_metrics.nil? || number_of_h_metrics < 1
+          raise ArgumentError,
+                "numberOfHMetrics must be >= 1, got: #{number_of_h_metrics.inspect}"
+        end
+
+        if num_glyphs.nil? || num_glyphs < 1
+          raise ArgumentError,
+                "numGlyphs must be >= 1, got: #{num_glyphs.inspect}"
+        end
+
+        if number_of_h_metrics > num_glyphs
+          raise ArgumentError,
+                "numberOfHMetrics (#{number_of_h_metrics}) cannot exceed " \
+                "numGlyphs (#{num_glyphs})"
+        end
+      end
+
+      # Parse horizontal metrics array
+      #
+      # @param io [StringIO] Input stream
+      # @param count [Integer] Number of metrics to parse
+      # @return [Array<Hash>] Array of metric hashes
+      # @raise [Fontisan::CorruptedTableError] If insufficient data
+      def parse_h_metrics(io, count)
+        metrics = []
+        count.times do |i|
+          advance_width = read_uint16(io)
+          lsb = read_int16(io)
+
+          if advance_width.nil? || lsb.nil?
+            raise Fontisan::CorruptedTableError,
+                  "Insufficient data for hMetric at index #{i}"
+          end
+
+          metrics << { advance_width: advance_width, lsb: lsb }
+        end
+        metrics
+      end
+
+      # Parse left side bearings array
+      #
+      # @param io [StringIO] Input stream
+      # @param count [Integer] Number of LSBs to parse
+      # @return [Array<Integer>] Array of LSB values
+      # @raise [Fontisan::CorruptedTableError] If insufficient data
+      def parse_left_side_bearings(io, count)
+        return [] if count.zero?
+
+        lsbs = []
+        count.times do |i|
+          lsb = read_int16(io)
+
+          if lsb.nil?
+            raise Fontisan::CorruptedTableError,
+                  "Insufficient data for LSB at index #{i}"
+          end
+
+          lsbs << lsb
+        end
+        lsbs
+      end
+
+      # Validate that all expected data was parsed
+      #
+      # @param io [StringIO] Input stream
+      # @raise [Fontisan::CorruptedTableError] If unexpected data remains
+      def validate_parsed_data!(io)
+        remaining = io.read
+        return if remaining.nil? || remaining.empty?
+
+        # Some fonts may have padding, which is acceptable
+        # Only warn if there's more than 3 bytes of extra data
+        if remaining.length > 3
+          warn "Warning: hmtx table has #{remaining.length} unexpected " \
+               "bytes after parsing"
+        end
+      end
+
+      # Read unsigned 16-bit integer
+      #
+      # @param io [StringIO] Input stream
+      # @return [Integer, nil] Value or nil if insufficient data
+      def read_uint16(io)
+        data = io.read(2)
+        return nil if data.nil? || data.length < 2
+
+        data.unpack1("n") # Big-endian unsigned 16-bit
+      end
+
+      # Read signed 16-bit integer
+      #
+      # @param io [StringIO] Input stream
+      # @return [Integer, nil] Value or nil if insufficient data
+      def read_int16(io)
+        data = io.read(2)
+        return nil if data.nil? || data.length < 2
+
+        # Unpack as unsigned, then convert to signed
+        value = data.unpack1("n")
+        value >= 0x8000 ? value - 0x10000 : value
+      end
+    end
+  end
+end