fontisan 0.1.0 → 0.2.0

data/lib/fontisan/tables/hvar.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative "../binary/base_record"
+require_relative "variation_common"
+
+module Fontisan
+  module Tables
+    # Parser for the 'HVAR' (Horizontal Metrics Variations) table
+    #
+    # The HVAR table provides variation data for horizontal metrics including:
+    # - Advance width variations
+    # - Left side bearing (LSB) variations
+    #
+    # This table uses the ItemVariationStore structure to efficiently store
+    # delta values for different regions in the design space.
+    #
+    # Reference: OpenType specification, HVAR table
+    #
+    # @example Reading an HVAR table
+    #   data = font.table_data("HVAR")
+    #   hvar = Fontisan::Tables::Hvar.read(data)
+    #   advance_deltas = hvar.advance_width_deltas(glyph_id, coordinates)
+    class Hvar < Binary::BaseRecord
+      uint16 :major_version
+      uint16 :minor_version
+      uint32 :item_variation_store_offset
+      uint32 :advance_width_mapping_offset
+      uint32 :lsb_mapping_offset
+      uint32 :rsb_mapping_offset
+
+      # Get version as a float
+      #
+      # @return [Float] Version number (e.g., 1.0)
+      def version
+        major_version + (minor_version / 10.0)
+      end
+
+      # Parse the item variation store
+      #
+      # @return [VariationCommon::ItemVariationStore, nil] Variation store
+      def item_variation_store
+        return @item_variation_store if defined?(@item_variation_store)
+        return @item_variation_store = nil if item_variation_store_offset.zero?
+
+        data = raw_data
+        offset = item_variation_store_offset
+
+        return @item_variation_store = nil if offset >= data.bytesize
+
+        store_data = data.byteslice(offset..-1)
+        @item_variation_store = VariationCommon::ItemVariationStore.read(store_data)
+      rescue StandardError => e
+        warn "Failed to parse HVAR item variation store: #{e.message}"
+        @item_variation_store = nil
+      end
+
+      # Parse advance width mapping
+      #
+      # @return [VariationCommon::DeltaSetIndexMap, nil] Advance width map
+      def advance_width_mapping
+        return @advance_width_mapping if defined?(@advance_width_mapping)
+        return @advance_width_mapping = nil if advance_width_mapping_offset.zero?
+
+        data = raw_data
+        offset = advance_width_mapping_offset
+
+        return @advance_width_mapping = nil if offset >= data.bytesize
+
+        map_data = data.byteslice(offset..-1)
+        @advance_width_mapping = VariationCommon::DeltaSetIndexMap.read(map_data)
+      rescue StandardError => e
+        warn "Failed to parse HVAR advance width mapping: #{e.message}"
+        @advance_width_mapping = nil
+      end
+
+      # Parse LSB (left side bearing) mapping
+      #
+      # @return [VariationCommon::DeltaSetIndexMap, nil] LSB map
+      def lsb_mapping
+        return @lsb_mapping if defined?(@lsb_mapping)
+        return @lsb_mapping = nil if lsb_mapping_offset.zero?
+
+        data = raw_data
+        offset = lsb_mapping_offset
+
+        return @lsb_mapping = nil if offset >= data.bytesize
+
+        map_data = data.byteslice(offset..-1)
+        @lsb_mapping = VariationCommon::DeltaSetIndexMap.read(map_data)
+      rescue StandardError => e
+        warn "Failed to parse HVAR LSB mapping: #{e.message}"
+        @lsb_mapping = nil
+      end
+
+      # Parse RSB (right side bearing) mapping
+      #
+      # @return [VariationCommon::DeltaSetIndexMap, nil] RSB map
+      def rsb_mapping
+        return @rsb_mapping if defined?(@rsb_mapping)
+        return @rsb_mapping = nil if rsb_mapping_offset.zero?
+
+        data = raw_data
+        offset = rsb_mapping_offset
+
+        return @rsb_mapping = nil if offset >= data.bytesize
+
+        map_data = data.byteslice(offset..-1)
+        @rsb_mapping = VariationCommon::DeltaSetIndexMap.read(map_data)
+      rescue StandardError => e
+        warn "Failed to parse HVAR RSB mapping: #{e.message}"
+        @rsb_mapping = nil
+      end
+
+      # Get advance width delta set for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @return [Array<Integer>, nil] Delta values or nil
+      def advance_width_delta_set(glyph_id)
+        return nil unless item_variation_store
+
+        # If no mapping, use glyph_id directly
+        if advance_width_mapping.nil?
+          return item_variation_store.delta_set(0, glyph_id)
+        end
+
+        # Use mapping to get delta set indices
+        map_data = advance_width_mapping.map_data
+        return nil if glyph_id >= map_data.length
+
+        delta_index = map_data[glyph_id]
+        outer_index = (delta_index >> 16) & 0xFFFF
+        inner_index = delta_index & 0xFFFF
+
+        item_variation_store.delta_set(outer_index, inner_index)
+      end
+
+      # Get LSB delta set for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @return [Array<Integer>, nil] Delta values or nil
+      def lsb_delta_set(glyph_id)
+        return nil unless item_variation_store
+
+        # If no mapping, use glyph_id directly
+        if lsb_mapping.nil?
+          return item_variation_store.delta_set(0, glyph_id)
+        end
+
+        # Use mapping to get delta set indices
+        map_data = lsb_mapping.map_data
+        return nil if glyph_id >= map_data.length
+
+        delta_index = map_data[glyph_id]
+        outer_index = (delta_index >> 16) & 0xFFFF
+        inner_index = delta_index & 0xFFFF
+
+        item_variation_store.delta_set(outer_index, inner_index)
+      end
+
+      # Get RSB delta set for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @return [Array<Integer>, nil] Delta values or nil
+      def rsb_delta_set(glyph_id)
+        return nil unless item_variation_store
+
+        # If no mapping, use glyph_id directly
+        if rsb_mapping.nil?
+          return item_variation_store.delta_set(0, glyph_id)
+        end
+
+        # Use mapping to get delta set indices
+        map_data = rsb_mapping.map_data
+        return nil if glyph_id >= map_data.length
+
+        delta_index = map_data[glyph_id]
+        outer_index = (delta_index >> 16) & 0xFFFF
+        inner_index = delta_index & 0xFFFF
+
+        item_variation_store.delta_set(outer_index, inner_index)
+      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/loca.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require_relative "../binary/base_record"
+
+module Fontisan
+  module Tables
+    # Parser for the 'loca' (Index to Location) table
+    #
+    # The loca table provides offsets to glyph data in the glyf table.
+    # Each glyph has an entry in this table indicating where its data
+    # begins in the glyf table. An additional entry marks the end of the
+    # last glyph's data.
+    #
+    # The table has two formats:
+    # - Short format (0): uint16 offsets divided by 2 (actual offset = value × 2)
+    # - Long format (1): uint32 offsets used as-is
+    #
+    # The format is determined by head.indexToLocFormat:
+    # - 0 = short format (uint16, multiply by 2)
+    # - 1 = long format (uint32, use as-is)
+    #
+    # The table always contains (numGlyphs + 1) offsets, where the last
+    # offset marks the end of the last glyph's data in the glyf table.
+    #
+    # The table is context-dependent and requires:
+    # - indexToLocFormat from head table (format selection)
+    # - numGlyphs from maxp table (number of offsets to read)
+    #
+    # Reference: OpenType specification, loca table
+    # https://docs.microsoft.com/en-us/typography/opentype/spec/loca
+    #
+    # @example Parsing loca with context
+    #   # Get required tables first
+    #   head = font.table('head')
+    #   maxp = font.table('maxp')
+    #
+    #   # Parse loca with context
+    #   data = font.read_table_data('loca')
+    #   loca = Fontisan::Tables::Loca.read(data)
+    #   loca.parse_with_context(head.index_to_loc_format, maxp.num_glyphs)
+    #
+    #   # Get offset for a glyph
+    #   offset = loca.offset_for(42)
+    #   size = loca.size_of(42)
+    #   is_empty = loca.empty?(42)
+    class Loca < Binary::BaseRecord
+      # Short format constant (from head.indexToLocFormat)
+      FORMAT_SHORT = 0
+
+      # Long format constant (from head.indexToLocFormat)
+      FORMAT_LONG = 1
+
+      # Store the raw data for deferred parsing
+      attr_accessor :raw_data
+
+      # Parsed offsets array
+      # @return [Array<Integer>] Array of glyph offsets in glyf table
+      attr_reader :offsets
+
+      # Format of the loca table (0 = short, 1 = long)
+      # @return [Integer] Format indicator
+      attr_reader :format
+
+      # 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 [Loca] 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 indexToLocFormat from head and numGlyphs from maxp.
+      #
+      # @param index_to_loc_format [Integer] Format (0 = short, 1 = long) from head table
+      # @param num_glyphs [Integer] Total number of glyphs from maxp table
+      # @raise [ArgumentError] If context parameters are invalid
+      # @raise [Fontisan::CorruptedTableError] If table data is insufficient
+      def parse_with_context(index_to_loc_format, num_glyphs)
+        validate_context_params(index_to_loc_format, num_glyphs)
+
+        @format = index_to_loc_format
+        @num_glyphs = num_glyphs
+
+        io = StringIO.new(raw_data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Number of offsets is numGlyphs + 1 (extra offset marks end of last glyph)
+        offset_count = num_glyphs + 1
+
+        @offsets = if short_format?
+                     parse_short_offsets(io, offset_count)
+                   else
+                     parse_long_offsets(io, offset_count)
+                   end
+
+        validate_parsed_data!(io, offset_count)
+      end
+
+      # Get the offset for a specific glyph ID in the glyf table
+      #
+      # @param glyph_id [Integer] Glyph ID (0-based)
+      # @return [Integer, nil] Byte offset in glyf table, or nil if invalid ID
+      # @raise [RuntimeError] If table has not been parsed with context
+      #
+      # @example Getting glyph offset
+      #   offset = loca.offset_for(0)  # .notdef glyph offset
+      def offset_for(glyph_id)
+        raise "Table not parsed. Call parse_with_context first." unless @offsets
+
+        return nil if glyph_id >= num_glyphs || glyph_id.negative?
+
+        offsets[glyph_id]
+      end
+
+      # Calculate the size of glyph data for a specific glyph ID
+      #
+      # The size is calculated as the difference between consecutive offsets:
+      # size = offsets[glyph_id + 1] - offsets[glyph_id]
+      #
+      # A size of 0 indicates an empty glyph (no outline data).
+      #
+      # @param glyph_id [Integer] Glyph ID (0-based)
+      # @return [Integer, nil] Size in bytes, or nil if invalid ID
+      # @raise [RuntimeError] If table has not been parsed with context
+      #
+      # @example Calculating glyph size
+      #   size = loca.size_of(42)  # Size of glyph 42 in bytes
+      def size_of(glyph_id)
+        raise "Table not parsed. Call parse_with_context first." unless @offsets
+
+        return nil if glyph_id >= num_glyphs || glyph_id.negative?
+
+        offsets[glyph_id + 1] - offsets[glyph_id]
+      end
+
+      # Check if a glyph has no outline data
+      #
+      # A glyph is empty when its size is 0, which occurs when consecutive
+      # offsets are equal. Empty glyphs are used for space characters and
+      # other non-visible glyphs.
+      #
+      # @param glyph_id [Integer] Glyph ID (0-based)
+      # @return [Boolean, nil] True if empty, false if has data, nil if invalid ID
+      # @raise [RuntimeError] If table has not been parsed with context
+      #
+      # @example Checking if glyph is empty
+      #   is_empty = loca.empty?(32)  # Check if space character is empty
+      def empty?(glyph_id)
+        size = size_of(glyph_id)
+        size&.zero?
+      end
+
+      # Check if the table has been parsed with context
+      #
+      # @return [Boolean] True if parsed, false otherwise
+      def parsed?
+        !@offsets.nil?
+      end
+
+      # Check if using short format (format 0)
+      #
+      # @return [Boolean] True if short format, false otherwise
+      def short_format?
+        format == FORMAT_SHORT
+      end
+
+      # Check if using long format (format 1)
+      #
+      # @return [Boolean] True if long format, false otherwise
+      def long_format?
+        format == FORMAT_LONG
+      end
+
+      # Get the expected size for this table
+      #
+      # @return [Integer, nil] Expected size in bytes, or nil if not parsed
+      def expected_size
+        return nil unless parsed?
+
+        offset_count = num_glyphs + 1
+        if short_format?
+          offset_count * 2  # uint16
+        else
+          offset_count * 4  # uint32
+        end
+      end
+
+      private
+
+      # Validate context parameters
+      #
+      # @param format [Integer] Format indicator
+      # @param num_glyphs [Integer] Total glyphs
+      # @raise [ArgumentError] If parameters are invalid
+      def validate_context_params(format, num_glyphs)
+        if format.nil? || (format != FORMAT_SHORT && format != FORMAT_LONG)
+          raise ArgumentError,
+                "indexToLocFormat must be 0 (short) or 1 (long), " \
+                "got: #{format.inspect}"
+        end
+
+        if num_glyphs.nil? || num_glyphs < 1
+          raise ArgumentError,
+                "numGlyphs must be >= 1, got: #{num_glyphs.inspect}"
+        end
+      end
+
+      # Parse short format offsets (uint16, multiply by 2)
+      #
+      # @param io [StringIO] Input stream
+      # @param count [Integer] Number of offsets to parse
+      # @return [Array<Integer>] Array of offsets
+      # @raise [Fontisan::CorruptedTableError] If insufficient data
+      def parse_short_offsets(io, count)
+        offsets = []
+        count.times do |i|
+          value = read_uint16(io)
+
+          if value.nil?
+            raise Fontisan::CorruptedTableError,
+                  "Insufficient data for short offset at index #{i}"
+          end
+
+          # Short offsets are divided by 2, so multiply to get actual offset
+          offsets << (value * 2)
+        end
+        offsets
+      end
+
+      # Parse long format offsets (uint32, use as-is)
+      #
+      # @param io [StringIO] Input stream
+      # @param count [Integer] Number of offsets to parse
+      # @return [Array<Integer>] Array of offsets
+      # @raise [Fontisan::CorruptedTableError] If insufficient data
+      def parse_long_offsets(io, count)
+        offsets = []
+        count.times do |i|
+          value = read_uint32(io)
+
+          if value.nil?
+            raise Fontisan::CorruptedTableError,
+                  "Insufficient data for long offset at index #{i}"
+          end
+
+          offsets << value
+        end
+        offsets
+      end
+
+      # Validate that all expected data was parsed
+      #
+      # @param io [StringIO] Input stream
+      # @param offset_count [Integer] Expected number of offsets
+      # @raise [Fontisan::CorruptedTableError] If data validation fails
+      def validate_parsed_data!(io, offset_count)
+        # Check that we parsed the expected number of offsets
+        if offsets.length != offset_count
+          raise Fontisan::CorruptedTableError,
+                "Expected #{offset_count} offsets, got #{offsets.length}"
+        end
+
+        # Check that offsets are monotonically increasing
+        offsets.each_cons(2).with_index do |(prev, curr), i|
+          if curr < prev
+            raise Fontisan::CorruptedTableError,
+                  "Offsets are not monotonically increasing: " \
+                  "offset[#{i}]=#{prev}, offset[#{i + 1}]=#{curr}"
+          end
+        end
+
+        # Check for unexpected remaining data
+        remaining = io.read
+        if remaining && !remaining.empty? && remaining.length > 3
+          # Some fonts may have padding, only warn if significant
+          warn "Warning: loca 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 unsigned 32-bit integer
+      #
+      # @param io [StringIO] Input stream
+      # @return [Integer, nil] Value or nil if insufficient data
+      def read_uint32(io)
+        data = io.read(4)
+        return nil if data.nil? || data.length < 4
+
+        data.unpack1("N") # Big-endian unsigned 32-bit
+      end
+    end
+  end
+end

data/lib/fontisan/tables/maxp.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require_relative "../binary/base_record"
+
+module Fontisan
+  module Tables
+    # BinData structure for the 'maxp' (Maximum Profile) table
+    #
+    # The maxp table contains memory and complexity limits for the font.
+    # It provides the number of glyphs and various maximum values needed
+    # for font rendering and processing.
+    #
+    # The table has two versions:
+    # - Version 0.5 (0x00005000): CFF fonts - only version and numGlyphs
+    # - Version 1.0 (0x00010000): TrueType fonts - includes additional fields
+    #
+    # Version 1.0 fields provide information about:
+    # - Glyph outline complexity (points, contours)
+    # - Composite glyph structure
+    # - TrueType instruction limitations
+    #
+    # Reference: OpenType specification, maxp table
+    # https://docs.microsoft.com/en-us/typography/opentype/spec/maxp
+    #
+    # @example Reading a maxp table
+    #   data = File.binread("font.ttf", size, maxp_offset)
+    #   maxp = Fontisan::Tables::Maxp.read(data)
+    #   puts maxp.num_glyphs       # => 512
+    #   puts maxp.version          # => 1.0 or 0.5
+    #   puts maxp.truetype?        # => true or false
+    class Maxp < Binary::BaseRecord
+      # Version 0.5 constant (CFF fonts)
+      VERSION_0_5 = 0x00005000
+
+      # Version 1.0 constant (TrueType fonts)
+      VERSION_1_0 = 0x00010000
+
+      # Minimum table size for version 0.5 (4 + 2 = 6 bytes)
+      TABLE_SIZE_V0_5 = 6
+
+      # Full table size for version 1.0 (4 + 2 + 13×2 = 32 bytes)
+      TABLE_SIZE_V1_0 = 32
+
+      # Version as 16.16 fixed-point (stored as int32)
+      # 0x00010000 for version 1.0 (TrueType)
+      # 0x00005000 for version 0.5 (CFF)
+      int32 :version_raw
+
+      # Total number of glyphs in the font
+      # Must be >= 1 (at minimum, .notdef must be present)
+      uint16 :num_glyphs
+
+      # The following fields are only present in version 1.0 (TrueType fonts)
+
+      # Maximum points in a non-composite glyph
+      uint16 :max_points, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum contours in a non-composite glyph
+      uint16 :max_contours, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum points in a composite glyph
+      uint16 :max_composite_points, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum contours in a composite glyph
+      uint16 :max_composite_contours, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum zones (1 or 2, depending on instructions)
+      # 1 = no twilight zone, 2 = twilight zone present
+      uint16 :max_zones, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum points used in twilight zone (Z0)
+      uint16 :max_twilight_points, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum storage area locations
+      uint16 :max_storage, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum function definitions
+      uint16 :max_function_defs, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum instruction definitions
+      uint16 :max_instruction_defs, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum stack depth
+      uint16 :max_stack_elements, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum byte count for glyph instructions
+      uint16 :max_size_of_instructions, onlyif: -> {
+        version_raw == VERSION_1_0
+      }
+
+      # Maximum component elements in a composite glyph
+      uint16 :max_component_elements, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Maximum levels of recursion in composite glyphs
+      # 0 if font has no composite glyphs
+      uint16 :max_component_depth, onlyif: -> { version_raw == VERSION_1_0 }
+
+      # Convert version from fixed-point to float
+      #
+      # Version 0.5 (0x00005000) is a special case, not standard 16.16 fixed-point
+      #
+      # @return [Float] Version number (1.0 or 0.5)
+      def version
+        case version_raw
+        when VERSION_0_5
+          0.5
+        when VERSION_1_0
+          1.0
+        else
+          fixed_to_float(version_raw)
+        end
+      end
+
+      # Check if this is version 1.0 (TrueType)
+      #
+      # @return [Boolean] True if version 1.0, false otherwise
+      def version_1_0?
+        version_raw == VERSION_1_0
+      end
+
+      # Check if this is version 0.5 (CFF)
+      #
+      # @return [Boolean] True if version 0.5, false otherwise
+      def version_0_5?
+        version_raw == VERSION_0_5
+      end
+
+      # Check if this is a TrueType font (alias for version_1_0?)
+      #
+      # @return [Boolean] True if TrueType font, false otherwise
+      def truetype?
+        version_1_0?
+      end
+
+      # Check if this is a CFF font (alias for version_0_5?)
+      #
+      # @return [Boolean] True if CFF font, false otherwise
+      def cff?
+        version_0_5?
+      end
+
+      # Check if the table is valid
+      #
+      # @return [Boolean] True if valid, false otherwise
+      def valid?
+        # Version must be either 0.5 or 1.0
+        return false unless version_0_5? || version_1_0?
+
+        # Number of glyphs must be at least 1
+        return false unless num_glyphs >= 1
+
+        # For version 1.0, maxZones must be 1 or 2
+        if version_1_0? && max_zones && !(max_zones >= 1 && max_zones <= 2)
+          return false
+        end
+
+        true
+      end
+
+      # Validate the table and raise error if invalid
+      #
+      # @raise [Fontisan::CorruptedTableError] If table is invalid
+      def validate_structure!
+        unless version_0_5? || version_1_0?
+          raise Fontisan::CorruptedTableError,
+                "Invalid maxp version: expected 0x00005000 (0.5) or " \
+                "0x00010000 (1.0), got 0x#{version_raw.to_s(16).upcase}"
+        end
+
+        unless num_glyphs >= 1
+          raise Fontisan::CorruptedTableError,
+                "Invalid number of glyphs: must be >= 1, got #{num_glyphs}"
+        end
+
+        if version_1_0? && max_zones && (max_zones < 1 || max_zones > 2)
+          raise Fontisan::CorruptedTableError,
+                "Invalid maxZones: must be 1 or 2, got #{max_zones}"
+        end
+      end
+
+      # Alias for compatibility
+      alias validate! validate_structure!
+
+      # Get the expected table size based on version
+      #
+      # @return [Integer] Expected size in bytes
+      def expected_size
+        version_1_0? ? TABLE_SIZE_V1_0 : TABLE_SIZE_V0_5
+      end
+    end
+  end
+end