fontisan 0.1.0 → 0.2.0

data/lib/fontisan/optimizers/subroutine_generator.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Optimizers
+    # Main orchestrator for CFF subroutine generation pipeline.
+    # Coordinates PatternAnalyzer, SubroutineOptimizer, SubroutineBuilder,
+    # and CharstringRewriter to generate optimized subroutines for fonts.
+    #
+    # The generator processes CharStrings from a CFF font table by:
+    # 1. Analyzing patterns across all glyphs
+    # 2. Selecting optimal patterns (avoiding conflicts, within limits)
+    # 3. Ordering patterns by frequency for efficient encoding
+    # 4. Building actual subroutine CharStrings
+    # 5. Rewriting original CharStrings with subroutine calls
+    #
+    # @example Basic usage
+    #   generator = SubroutineGenerator.new(min_pattern_length: 10)
+    #   result = generator.generate(font)
+    #   puts "Generated #{result[:selected_count]} subroutines"
+    #   puts "Total savings: #{result[:savings]} bytes"
+    #
+    # @see docs/SUBROUTINE_ARCHITECTURE.md
+    class SubroutineGenerator
+      # Default minimum pattern length in bytes
+      DEFAULT_MIN_PATTERN_LENGTH = 10
+
+      # Default maximum number of subroutines (CFF limit)
+      DEFAULT_MAX_SUBROUTINES = 65_535
+
+      # Initialize generator with options
+      # @param options [Hash] configuration options
+      # @option options [Integer] :min_pattern_length (10) minimum pattern size
+      # @option options [Integer] :max_subroutines (65535) max subroutine count
+      # @option options [Boolean] :optimize_ordering (true) enable frequency
+      #   ordering
+      def initialize(options = {})
+        @min_pattern_length = options[:min_pattern_length] ||
+          DEFAULT_MIN_PATTERN_LENGTH
+        @max_subroutines = options[:max_subroutines] || DEFAULT_MAX_SUBROUTINES
+        @optimize_ordering = options[:optimize_ordering] != false
+      end
+
+      # Generate subroutines for a font
+      #
+      # Main entry point for the subroutine generation pipeline. Processes
+      # a font's CFF table to create optimized subroutines and rewrite
+      # CharStrings.
+      #
+      # @param font [Fontisan::OpenTypeFont] font to optimize
+      # @return [Hash] result containing:
+      #   - :local_subrs [Array<String>] subroutine CharStrings
+      #   - :charstrings [Hash<Integer, String>] rewritten CharStrings
+      #   - :bias [Integer] CFF bias value for subroutines
+      #   - :savings [Integer] total bytes saved
+      #   - :pattern_count [Integer] total patterns found
+      #   - :selected_count [Integer] patterns selected as subroutines
+      # @raise [ArgumentError] if font has no CFF table
+      def generate(font)
+        # 1. Extract CharStrings from CFF table
+        charstrings = extract_charstrings(font)
+
+        # Handle empty font gracefully
+        if charstrings.empty?
+          return {
+            local_subrs: [],
+            charstrings: {},
+            bias: 0,
+            savings: 0,
+            pattern_count: 0,
+            selected_count: 0,
+          }
+        end
+
+        # 2. Analyze patterns
+        analyzer = PatternAnalyzer.new(
+          min_length: @min_pattern_length,
+          stack_aware: true
+        )
+        patterns = analyzer.analyze(charstrings)
+
+        # 3. Optimize selection
+        optimizer = SubroutineOptimizer.new(patterns,
+                                            max_subrs: @max_subroutines)
+        selected_patterns = optimizer.optimize_selection
+
+        # 4. Optimize ordering (if enabled)
+        if @optimize_ordering
+          selected_patterns = optimizer.optimize_ordering(selected_patterns)
+        end
+
+        # 5. Build subroutines
+        builder = SubroutineBuilder.new(selected_patterns, type: :local)
+        subroutines = builder.build
+
+        # 6. Build subroutine map
+        subroutine_map = build_subroutine_map(selected_patterns)
+
+        # 7. Rewrite CharStrings
+        rewriter = CharstringRewriter.new(subroutine_map, builder)
+        rewritten_charstrings = rewrite_charstrings(
+          charstrings,
+          selected_patterns,
+          rewriter,
+        )
+
+        # 8. Return complete result
+        {
+          local_subrs: subroutines,
+          charstrings: rewritten_charstrings,
+          bias: builder.bias,
+          savings: calculate_total_savings(selected_patterns),
+          pattern_count: patterns.length,
+          selected_count: selected_patterns.length,
+        }
+      end
+
+      private
+
+      # Extract CharStrings from CFF table
+      #
+      # Retrieves raw CharString byte sequences for each glyph from the
+      # font's CFF table. The CharStrings INDEX is accessed through the
+      # CFF table structure.
+      #
+      # @param font [Fontisan::OpenTypeFont] font to extract from
+      # @return [Hash<Integer, String>] glyph_id => charstring_bytes
+      # @raise [ArgumentError] if font has no CFF table
+      def extract_charstrings(font)
+        cff = font.table("CFF ")
+        raise ArgumentError, "Font must have CFF table" unless cff
+
+        charstrings = {}
+
+        # Get CharStrings INDEX for first font (index 0)
+        charstrings_index = cff.charstrings_index(0)
+        unless charstrings_index
+          raise ArgumentError, "Font CFF table has no CharStrings"
+        end
+
+        # Extract raw CharString bytes for each glyph
+        # Index.each yields raw bytes, we add index manually
+        index = 0
+        charstrings_index.each do |cs_data|
+          charstrings[index] = cs_data
+          index += 1
+        end
+
+        charstrings
+      end
+
+      # Build map from pattern bytes to subroutine ID
+      #
+      # Creates a lookup table for the rewriter to quickly find which
+      # subroutine ID corresponds to each pattern's byte sequence.
+      #
+      # @param patterns [Array<Pattern>] selected patterns
+      # @return [Hash<String, Integer>] pattern_bytes => subroutine_id
+      def build_subroutine_map(patterns)
+        map = {}
+        patterns.each_with_index do |pattern, index|
+          map[pattern.bytes] = index
+        end
+        map
+      end
+
+      # Rewrite all CharStrings with subroutine calls
+      #
+      # Processes each glyph's CharString, replacing pattern occurrences
+      # with calls to their corresponding subroutines. Glyphs without
+      # applicable patterns are kept unchanged.
+      #
+      # @param charstrings [Hash<Integer, String>] original CharStrings
+      # @param patterns [Array<Pattern>] patterns to use
+      # @param rewriter [CharstringRewriter] rewriter instance
+      # @return [Hash<Integer, String>] rewritten CharStrings
+      def rewrite_charstrings(charstrings, patterns, rewriter)
+        rewritten = {}
+
+        charstrings.each do |glyph_id, charstring|
+          # Find patterns for this glyph
+          glyph_patterns = patterns.select { |p| p.glyphs.include?(glyph_id) }
+
+          rewritten[glyph_id] = if glyph_patterns.empty?
+                                  # No patterns, keep original
+                                  charstring
+                                else
+                                  # Rewrite with subroutine calls
+                                  rewriter.rewrite(charstring, glyph_patterns)
+                                end
+        end
+
+        rewritten
+      end
+
+      # Calculate total byte savings
+      #
+      # Sums up the savings from all selected patterns to determine
+      # total file size reduction achieved by subroutinization.
+      #
+      # @param patterns [Array<Pattern>] selected patterns
+      # @return [Integer] total bytes saved
+      def calculate_total_savings(patterns)
+        patterns.sum(&:savings)
+      end
+    end
+  end
+end

data/lib/fontisan/optimizers/subroutine_optimizer.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Optimizers
+    # Optimizes subroutine selection and ordering for maximum file size reduction.
+    # Uses a greedy algorithm to select the most beneficial patterns while avoiding
+    # conflicts, then orders them by frequency for efficient encoding.
+    #
+    # @example Basic usage
+    #   analyzer = PatternAnalyzer.new
+    #   patterns = analyzer.analyze(charstrings)
+    #   optimizer = SubroutineOptimizer.new(patterns, max_subrs: 65535)
+    #   selected_patterns = optimizer.optimize_selection
+    #   ordered_patterns = optimizer.optimize_ordering(selected_patterns)
+    #
+    # @see docs/SUBROUTINE_ARCHITECTURE.md
+    class SubroutineOptimizer
+      # Initialize optimizer with patterns
+      # @param patterns [Array<Pattern>] patterns from analyzer
+      # @param max_subrs [Integer] maximum number of subroutines (default: 65535)
+      def initialize(patterns, max_subrs: 65535)
+        @patterns = patterns
+        @max_subrs = max_subrs
+      end
+
+      # Select optimal subset of patterns to subroutinize
+      # Uses greedy algorithm: select by highest savings first, checking for
+      # conflicts with already selected patterns.
+      #
+      # @return [Array<Pattern>] selected patterns
+      def optimize_selection
+        selected = []
+        remaining = @patterns.sort_by { |p| -p.savings }
+
+        remaining.each do |pattern|
+          break if selected.length >= @max_subrs
+          next if conflicts_with_selected?(pattern, selected)
+
+          selected << pattern
+        end
+
+        selected
+      end
+
+      # Optimize subroutine ordering by frequency
+      # Higher frequency patterns get lower IDs for more efficient encoding
+      # in CFF format.
+      #
+      # @param subroutines [Array<Pattern>] subroutines to order
+      # @return [Array<Pattern>] ordered subroutines
+      def optimize_ordering(subroutines)
+        # Higher frequency = lower ID (shorter encoding)
+        subroutines.sort_by { |subr| -subr.frequency }
+      end
+
+      # Check if nesting would be beneficial
+      # TODO: Phase 2.1 - check if subroutines contain common patterns
+      #
+      # @param subroutines [Array<Pattern>] subroutines to analyze
+      # @return [Array<Pattern>] subroutines (unchanged for now)
+      def optimize_nesting(subroutines)
+        subroutines
+      end
+
+      private
+
+      # Check if pattern conflicts with any already selected patterns
+      # A conflict occurs when patterns overlap in the same glyph at
+      # overlapping positions.
+      #
+      # @param pattern [Pattern] pattern to check
+      # @param selected [Array<Pattern>] already selected patterns
+      # @return [Boolean] true if conflicts, false otherwise
+      def conflicts_with_selected?(pattern, selected)
+        selected.any? do |sel|
+          # Check if they share any glyphs
+          common_glyphs = pattern.glyphs & sel.glyphs
+          next false if common_glyphs.empty?
+
+          # Check if positions overlap in any common glyph
+          common_glyphs.any? { |gid| positions_overlap?(pattern, sel, gid) }
+        end
+      end
+
+      # Check if two patterns overlap at positions in a specific glyph
+      # Ranges overlap if they intersect at any point.
+      #
+      # @param p1 [Pattern] first pattern
+      # @param p2 [Pattern] second pattern
+      # @param glyph_id [Integer] glyph to check
+      # @return [Boolean] true if positions overlap, false otherwise
+      def positions_overlap?(p1, p2, glyph_id)
+        pos1 = p1.positions[glyph_id] || []
+        pos2 = p2.positions[glyph_id] || []
+
+        pos1.any? do |start1|
+          end1 = start1 + p1.length
+          pos2.any? do |start2|
+            end2 = start2 + p2.length
+            # Check if ranges overlap: start1 < end2 && start2 < end1
+            start1 < end2 && start2 < end1
+          end
+        end
+      end
+    end
+  end
+end