fontisan 0.1.0 → 0.2.1

data/lib/fontisan/woff2/header.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "bindata"
+
+module Fontisan
+  module Woff2
+    # WOFF2 Header structure
+    #
+    # [`Woff2::Header`](lib/fontisan/woff2/header.rb) represents the main
+    # header of a WOFF2 file according to W3C WOFF2 specification.
+    #
+    # The header is more compact than WOFF, using 48 bytes.
+    #
+    # Structure (all big-endian):
+    # - uint32: signature (0x774F4632 'wOF2')
+    # - uint32: flavor (0x00010000 for TTF, 0x4F54544F for CFF)
+    # - uint32: file_length (total WOFF2 file size)
+    # - uint16: numTables (number of font tables)
+    # - uint16: reserved (must be 0)
+    # - uint32: totalSfntSize (uncompressed font size)
+    # - uint32: totalCompressedSize (size of compressed data block)
+    # - uint16: majorVersion (major version of WOFF file)
+    # - uint16: minorVersion (minor version of WOFF file)
+    # - uint32: metaOffset (offset to metadata, 0 if none)
+    # - uint32: metaLength (compressed metadata length)
+    # - uint32: metaOrigLength (uncompressed metadata length)
+    # - uint32: privOffset (offset to private data, 0 if none)
+    # - uint32: privLength (length of private data)
+    #
+    # Reference: https://www.w3.org/TR/WOFF2/#woff20Header
+    #
+    # @example Create a header
+    #   header = Woff2::Header.new
+    #   header.signature = 0x774F4632
+    #   header.flavor = 0x00010000
+    #   header.num_tables = 10
+    class Woff2Header < BinData::Record
+      endian :big
+
+      uint32 :signature         # 'wOF2' magic number
+      uint32 :flavor            # Font format (TTF or CFF)
+      uint32 :file_length       # Total WOFF2 file size
+      uint16 :num_tables        # Number of font tables
+      uint16 :reserved          # Reserved, must be 0
+      uint32 :total_sfnt_size   # Uncompressed font size
+      uint32 :total_compressed_size # Compressed data block size
+      uint16 :major_version     # Major version number
+      uint16 :minor_version     # Minor version number
+      uint32 :meta_offset       # Metadata block offset (0 if none)
+      uint32 :meta_length       # Compressed metadata length
+      uint32 :meta_orig_length  # Uncompressed metadata length
+      uint32 :priv_offset       # Private data offset (0 if none)
+      uint32 :priv_length       # Private data length
+
+      # WOFF2 signature constant
+      SIGNATURE = 0x774F4632 # 'wOF2'
+
+      # Check if signature is valid
+      #
+      # @return [Boolean] True if signature is valid
+      def valid_signature?
+        signature == SIGNATURE
+      end
+
+      # Check if font is TrueType flavored
+      #
+      # @return [Boolean] True if TrueType
+      def truetype?
+        [0x00010000, 0x74727565].include?(flavor) # 'true'
+      end
+
+      # Check if font is CFF flavored
+      #
+      # @return [Boolean] True if CFF/OpenType
+      def cff?
+        flavor == 0x4F54544F # 'OTTO'
+      end
+
+      # Check if metadata is present
+      #
+      # @return [Boolean] True if metadata exists
+      def has_metadata?
+        meta_offset.positive? && meta_length.positive?
+      end
+
+      # Check if private data is present
+      #
+      # @return [Boolean] True if private data exists
+      def has_private_data?
+        priv_offset.positive? && priv_length.positive?
+      end
+
+      # Get header size in bytes
+      #
+      # @return [Integer] Header size (always 48 bytes)
+      def self.header_size
+        48
+      end
+    end
+  end
+end

data/lib/fontisan/woff2/hmtx_transformer.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Woff2
+    # Reconstructs hmtx table from WOFF2 transformed format
+    #
+    # WOFF2 hmtx transformation optimizes horizontal metrics by:
+    # - Using variable-length encoding for advance widths
+    # - Optionally deriving LSB from glyf bounding boxes
+    # - Omitting redundant trailing advance widths
+    #
+    # See: https://www.w3.org/TR/WOFF2/#hmtx_table_format
+    #
+    # @example Reconstructing hmtx table
+    #   hmtx_data = HmtxTransformer.reconstruct(
+    #     transformed_data,
+    #     num_glyphs,
+    #     number_of_h_metrics
+    #   )
+    class HmtxTransformer
+      # Flags for hmtx transformation
+      HMTX_FLAG_EXPLICIT_ADVANCE_WIDTHS = 0x01
+      HMTX_FLAG_EXPLICIT_LSB_VALUES = 0x02
+      HMTX_FLAG_SYMMETRIC = 0x04
+
+      # Reconstruct hmtx table from transformed data
+      #
+      # @param transformed_data [String] The transformed hmtx table data
+      # @param num_glyphs [Integer] Number of glyphs
+      # @param num_h_metrics [Integer] From hhea.numberOfHMetrics
+      # @param glyf_lsbs [Array<Integer>, nil] LSB values from glyf bboxes (optional)
+      # @return [String] Standard hmtx table data
+      # @raise [InvalidFontError] If data is corrupted or invalid
+      def self.reconstruct(transformed_data, num_glyphs, num_h_metrics, glyf_lsbs = nil)
+        io = StringIO.new(transformed_data)
+
+        # Read transformation flags
+        flags = read_uint8(io)
+
+        # Read advance widths
+        advance_widths = []
+
+        if (flags & HMTX_FLAG_EXPLICIT_ADVANCE_WIDTHS).zero?
+          # Proportional encoding - read deltas
+          # First advance width is explicit
+          first_advance = read_255_uint16(io)
+          advance_widths << first_advance
+
+          # Remaining are deltas from previous
+          (num_h_metrics - 1).times do
+            delta = read_int16(io)
+            advance_widths << (advance_widths.last + delta)
+          end
+        else
+          # Explicit advance widths in transformed format
+          num_h_metrics.times do
+            advance_widths << read_255_uint16(io)
+          end
+        end
+
+        # Read LSB values
+        lsbs = []
+
+        if (flags & HMTX_FLAG_EXPLICIT_LSB_VALUES) != 0
+          # Explicit LSB values
+          num_glyphs.times do
+            lsbs << read_int16(io)
+          end
+        elsif glyf_lsbs
+          # Use LSB values from glyf bounding boxes
+          lsbs = glyf_lsbs
+        else
+          # Need to read LSB values for long metrics
+          num_h_metrics.times do
+            lsbs << read_int16(io)
+          end
+
+          # Remaining LSBs for glyphs that share the last advance width
+          (num_glyphs - num_h_metrics).times do
+            lsbs << read_int16(io)
+          end
+        end
+
+        # Build standard hmtx table
+        build_hmtx_table(advance_widths, lsbs, num_h_metrics, num_glyphs)
+      end
+
+      # Read variable-length 255UInt16 integer
+      #
+      # Format from WOFF2 spec:
+      # - value < 253: one byte
+      # - value == 253: 253 + next uint16
+      # - value == 254: 253 * 2 + next uint16
+      # - value == 255: 253 * 3 + next uint16
+      #
+      # @param io [StringIO] Input stream
+      # @return [Integer] Decoded value
+      def self.read_255_uint16(io)
+        code = read_uint8(io)
+
+        case code
+        when 255
+          759 + read_uint16(io)  # 253 * 3 + value
+        when 254
+          506 + read_uint16(io)  # 253 * 2 + value
+        when 253
+          253 + read_uint16(io)
+        else
+          code
+        end
+      end
+
+      # Build standard hmtx table format
+      #
+      # Standard hmtx format:
+      # - longHorMetric[numberOfHMetrics] (advanceWidth, lsb pairs)
+      # - int16[numGlyphs - numberOfHMetrics] (additional LSBs)
+      #
+      # @param advance_widths [Array<Integer>] Advance widths
+      # @param lsbs [Array<Integer>] Left side bearings
+      # @param num_h_metrics [Integer] Number of entries with full hMetrics
+      # @param num_glyphs [Integer] Total number of glyphs
+      # @return [String] Standard hmtx table data
+      def self.build_hmtx_table(advance_widths, lsbs, num_h_metrics, num_glyphs)
+        data = +""
+
+        # Write longHorMetric array (advanceWidth + lsb pairs)
+        num_h_metrics.times do |i|
+          advance_width = advance_widths[i] || advance_widths.last
+          lsb = lsbs[i] || 0
+
+          data << [advance_width].pack("n")  # uint16 advanceWidth
+          data << [lsb].pack("n")            # int16 lsb
+        end
+
+        # Write remaining LSB values
+        # These glyphs all share the last advance width from the array
+        (num_h_metrics...num_glyphs).each do |i|
+          lsb = lsbs[i] || 0
+          data << [lsb].pack("n") # int16 lsb
+        end
+
+        data
+      end
+
+      # Helper methods for reading binary data
+
+      def self.read_uint8(io)
+        io.read(1)&.unpack1("C") || raise(EOFError, "Unexpected end of stream")
+      end
+
+      def self.read_uint16(io)
+        io.read(2)&.unpack1("n") || raise(EOFError, "Unexpected end of stream")
+      end
+
+      def self.read_int16(io)
+        value = read_uint16(io)
+        value > 0x7FFF ? value - 0x10000 : value
+      end
+    end
+  end
+end

data/lib/fontisan/woff2/table_transformer.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Woff2
+    # Table transformer for WOFF2 encoding
+    #
+    # [`Woff2::TableTransformer`](lib/fontisan/woff2/table_transformer.rb)
+    # handles table transformations that improve compression in WOFF2.
+    # The WOFF2 spec defines transformations for glyf/loca and hmtx tables.
+    #
+    # For Phase 2 Milestone 2.1:
+    # - Architecture is in place for transformations
+    # - Actual transformation implementations are marked as TODO
+    # - Tables are copied as-is without transformation
+    # - This allows valid WOFF2 generation while leaving room for optimization
+    #
+    # Future milestones will implement:
+    # - glyf/loca transformation (combined stream, delta encoding)
+    # - hmtx transformation (compact representation)
+    #
+    # Reference: https://www.w3.org/TR/WOFF2/#table_tranforms
+    #
+    # @example Transform tables for WOFF2
+    #   transformer = TableTransformer.new(font)
+    #   glyf_data = transformer.transform_table("glyf")
+    class TableTransformer
+      # @return [Object] Font object with table access
+      attr_reader :font
+
+      # Initialize transformer with font
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Source font
+      def initialize(font)
+        @font = font
+      end
+
+      # Transform a table for WOFF2 encoding
+      #
+      # For Milestone 2.1, this returns the original table data
+      # without transformation. The architecture supports future
+      # implementation of actual transformations.
+      #
+      # @param tag [String] Table tag
+      # @return [String, nil] Transformed (or original) table data
+      def transform_table(tag)
+        case tag
+        when "glyf"
+          transform_glyf
+        when "loca"
+          transform_loca
+        when "hmtx"
+          transform_hmtx
+        else
+          # No transformation, return original data
+          get_table_data(tag)
+        end
+      end
+
+      # Check if a table can be transformed
+      #
+      # @param tag [String] Table tag
+      # @return [Boolean] True if table supports transformation
+      def transformable?(tag)
+        %w[glyf loca hmtx].include?(tag)
+      end
+
+      # Determine transformation version for a table
+      #
+      # For Milestone 2.1, always returns TRANSFORM_NONE since
+      # we don't implement transformations yet.
+      #
+      # @param tag [String] Table tag
+      # @return [Integer] Transformation version (0 = none)
+      def transformation_version(_tag)
+        # For this milestone, no transformations are applied
+        Directory::TRANSFORM_NONE
+      end
+
+      private
+
+      # Transform glyf table
+      #
+      # The WOFF2 glyf transformation combines glyf and loca into a
+      # single stream with delta-encoded coordinates and flags.
+      #
+      # TODO: Implement full glyf transformation for better compression.
+      # For now, returns original table data.
+      #
+      # @return [String, nil] Transformed glyf data
+      def transform_glyf
+        # TODO: Implement glyf transformation
+        # This would involve:
+        # 1. Parse all glyphs from glyf table
+        # 2. Combine with loca offsets
+        # 3. Create transformed stream with:
+        #    - nContour values
+        #    - nPoints values
+        #    - Flag bytes (with run-length encoding)
+        #    - x-coordinates (delta-encoded)
+        #    - y-coordinates (delta-encoded)
+        #    - Instruction bytes
+        # 4. Use 255UInt16 encoding for variable-length integers
+        #
+        # Reference: https://www.w3.org/TR/WOFF2/#glyf_table_format
+
+        get_table_data("glyf")
+      end
+
+      # Transform loca table
+      #
+      # In WOFF2, loca is combined with glyf during transformation.
+      # When glyf is transformed, loca table is omitted from output.
+      #
+      # TODO: Implement loca transformation (combined with glyf).
+      # For now, returns original table data.
+      #
+      # @return [String, nil] Transformed loca data
+      def transform_loca
+        # TODO: Implement loca transformation
+        # When glyf transformation is implemented, loca will be:
+        # 1. Combined into the transformed glyf stream
+        # 2. Reconstructed during decompression
+        # 3. Not present as separate table in WOFF2
+
+        get_table_data("loca")
+      end
+
+      # Transform hmtx table
+      #
+      # The WOFF2 hmtx transformation stores advance widths more efficiently
+      # by exploiting redundancy (many glyphs have same advance width).
+      #
+      # TODO: Implement hmtx transformation for better compression.
+      # For now, returns original table data.
+      #
+      # @return [String, nil] Transformed hmtx data
+      def transform_hmtx
+        # TODO: Implement hmtx transformation
+        # This would involve:
+        # 1. Parse hmtx table
+        # 2. Extract common advance widths
+        # 3. Identify proportional vs monospace sections
+        # 4. Use flags to indicate structure
+        # 5. Store only unique advance widths
+        # 6. Store LSB array separately
+        #
+        # Reference: https://www.w3.org/TR/WOFF2/#hmtx_table_format
+
+        get_table_data("hmtx")
+      end
+
+      # Get raw table data from font
+      #
+      # @param tag [String] Table tag
+      # @return [String, nil] Table data or nil if not found
+      def get_table_data(tag)
+        return nil unless font.respond_to?(:table_data)
+
+        font.table_data(tag)
+      end
+    end
+  end
+end