fontisan 0.4.22 → 0.4.24

data/lib/fontisan/tables/cblc.rb

@@ -1,291 +1,170 @@
 # frozen_string_literal: true
 
-require "stringio"
-
 module Fontisan
   module Tables
-    # CBLC (Color Bitmap Location) table parser
-    #
-    # The CBLC table contains location information for bitmap glyphs at various
-    # sizes (strikes). It works together with the CBDT table which contains the
-    # actual bitmap data.
+    # CBLC (Color Bitmap Location) table.
     #
-    # CBLC Table Structure:
-    # ```
-    # CBLC Table = Header (8 bytes)
-    #            + BitmapSize Records (48 bytes each)
-    # ```
+    # CBLC indexes glyph IDs into CBDT byte offsets across one or more
+    # bitmap strikes (each strike = a ppem + bit depth combination). For
+    # each strike, a list of IndexSubTable records describes how to locate
+    # the bitmap of each glyph in a contiguous glyph range.
     #
-    # Header (8 bytes):
-    # - version (uint32): Table version (0x00020000 or 0x00030000)
-    # - numSizes (uint32): Number of BitmapSize records
+    # Layout:
+    #   uint32 version                (0x00020000 or 0x00030000)
+    #   uint32 num_sizes              (number of BitmapSize records)
+    #   CblcBitmapSize[num_sizes]     (48 bytes each)
+    #   IndexSubTableArray entries    (8 bytes each, per BitmapSize)
+    #   IndexSubTable records         (variable, format-specific)
     #
-    # Each BitmapSize record (48 bytes) contains:
-    # - indexSubTableArrayOffset (uint32): Offset to index subtable array
-    # - indexTablesSize (uint32): Size of index subtables
-    # - numberOfIndexSubTables (uint32): Number of index subtables
-    # - colorRef (uint32): Not used, set to 0
-    # - hori (SbitLineMetrics, 12 bytes): Horizontal line metrics
-    # - vert (SbitLineMetrics, 12 bytes): Vertical line metrics
-    # - startGlyphIndex (uint16): First glyph ID in strike
-    # - endGlyphIndex (uint16): Last glyph ID in strike
-    # - ppemX (uint8): Horizontal pixels per em
-    # - ppemY (uint8): Vertical pixels per em
-    # - bitDepth (uint8): Bit depth (1, 2, 4, 8, 32)
-    # - flags (int8): Flags
+    # This model parses the header + BitmapSize records via BinData, then
+    # lazily walks the IndexSubTableArray / IndexSubTable structures on
+    # demand so callers can iterate [(gid, strike) → CBDT location] pairs.
     #
-    # Reference: OpenType CBLC specification
-    # https://docs.microsoft.com/en-us/typography/opentype/spec/cblc
+    # Reference: OpenType CBLC specification.
+    # https://learn.microsoft.com/en-us/typography/opentype/spec/cblc
     #
-    # @example Reading a CBLC table
-    #   data = font.table_data['CBLC']
-    #   cblc = Fontisan::Tables::Cblc.read(data)
-    #   strikes = cblc.strikes
-    #   puts "Font has #{strikes.length} bitmap strikes"
+    # @example Enumerate every glyph's CBDT bitmap location
+    #   cblc = Fontisan::Tables::Cblc.read(font.table_data["CBLC"])
+    #   cblc.each_glyph_location do |loc|
+    #     puts "gid=#{loc.glyph_id} cbdt_offset=#{loc.cbdt_offset}"
+    #   end
     class Cblc < Binary::BaseRecord
-      # OpenType table tag for CBLC
       TAG = "CBLC"
 
-      # Supported CBLC versions
+      # CBLC v2.0 — original release
       VERSION_2_0 = 0x00020000
+      # CBLC v3.0 — adds PNG image format support
       VERSION_3_0 = 0x00030000
 
-      # SbitLineMetrics structure (12 bytes)
-      #
-      # Contains metrics for horizontal or vertical layout
-      class SbitLineMetrics < Binary::BaseRecord
-        endian :big
-        int8 :ascender
-        int8 :descender
-        uint8 :width_max
-        int8 :caret_slope_numerator
-        int8 :caret_slope_denominator
-        int8 :caret_offset
-        int8 :min_origin_sb
-        int8 :min_advance_sb
-        int8 :max_before_bl
-        int8 :min_after_bl
-        int8 :pad1
-        int8 :pad2
-      end
+      uint32 :version
+      uint32 :num_sizes
+      array :bitmap_sizes,
+            type: Fontisan::Tables::CblcBitmapSize,
+            initial_length: :num_sizes
 
-      # BitmapSize record structure (48 bytes)
+      # Iterate every (glyph_id, strike) → CblcGlyphBitmapLocation pair
+      # across all strikes. Each strike's IndexSubTables are walked in
+      # turn so the caller sees every glyph's CBDT location exactly once
+      # per strike.
       #
-      # Describes a bitmap strike at a specific ppem size
-      class BitmapSize < Binary::BaseRecord
-        endian :big
-        uint32 :index_subtable_array_offset
-        uint32 :index_tables_size
-        uint32 :number_of_index_subtables
-        uint32 :color_ref
-
-        # Read the SbitLineMetrics structures manually
-        def self.read(io)
-          data = io.is_a?(String) ? io : io.read
-          size = new
-
-          io = StringIO.new(data)
-          size.instance_variable_set(:@index_subtable_array_offset,
-                                     io.read(4).unpack1("N"))
-          size.instance_variable_set(:@index_tables_size,
-                                     io.read(4).unpack1("N"))
-          size.instance_variable_set(:@number_of_index_subtables,
-                                     io.read(4).unpack1("N"))
-          size.instance_variable_set(:@color_ref, io.read(4).unpack1("N"))
-
-          # Parse hori and vert metrics (12 bytes each)
-          hori_data = io.read(12)
-          vert_data = io.read(12)
-          size.instance_variable_set(:@hori, SbitLineMetrics.read(hori_data))
-          size.instance_variable_set(:@vert, SbitLineMetrics.read(vert_data))
-
-          # Parse remaining fields
-          size.instance_variable_set(:@start_glyph_index,
-                                     io.read(2).unpack1("n"))
-          size.instance_variable_set(:@end_glyph_index, io.read(2).unpack1("n"))
-          size.instance_variable_set(:@ppem_x, io.read(1).unpack1("C"))
-          size.instance_variable_set(:@ppem_y, io.read(1).unpack1("C"))
-          size.instance_variable_set(:@bit_depth, io.read(1).unpack1("C"))
-          size.instance_variable_set(:@flags, io.read(1).unpack1("c"))
-
-          size
-        end
-
-        attr_reader :index_subtable_array_offset, :index_tables_size,
-                    :number_of_index_subtables, :color_ref, :hori, :vert,
-                    :start_glyph_index, :end_glyph_index, :ppem_x, :ppem_y,
-                    :bit_depth, :flags
-
-        # Get ppem size (assumes square pixels)
-        #
-        # @return [Integer] Pixels per em
-        def ppem
-          ppem_x
-        end
-
-        # Get glyph range for this strike
-        #
-        # @return [Range] Range of glyph IDs
-        def glyph_range
-          start_glyph_index..end_glyph_index
-        end
+      # @yield [CblcGlyphBitmapLocation]
+      # @return [Enumerator] if no block given
+      def each_glyph_location(&block)
+        return enum_for(:each_glyph_location) unless block
 
-        # Check if this strike includes a specific glyph ID
-        #
-        # @param glyph_id [Integer] Glyph ID to check
-        # @return [Boolean] True if glyph is in range
-        def includes_glyph?(glyph_id)
-          glyph_range.include?(glyph_id)
+        index_sub_tables.each do |sub|
+          sub.locations.each(&block)
         end
       end
 
-      # @return [Integer] CBLC version
-      attr_reader :version
-
-      # @return [Integer] Number of bitmap size records
-      attr_reader :num_sizes
-
-      # @return [Array<BitmapSize>] Parsed bitmap size records
-      attr_reader :bitmap_sizes
-
-      # @return [String] Raw binary data for the entire CBLC table
-      attr_reader :raw_data
-
-      # Override read to parse CBLC structure
-      #
-      # @param io [IO, String] Binary data to read
-      # @return [Cblc] Parsed CBLC table
-      def self.read(io)
-        cblc = new
-        return cblc if io.nil?
-
-        data = io.is_a?(String) ? io : io.read
-        cblc.parse!(data)
-        cblc
-      end
-
-      # Parse the CBLC table structure
+      # All IndexSubTable records across every strike.
       #
-      # @param data [String] Binary data for the CBLC table
-      # @raise [CorruptedTableError] If CBLC structure is invalid
-      def parse!(data)
-        @raw_data = data
-        io = StringIO.new(data)
-
-        # Parse CBLC header (8 bytes)
-        parse_header(io)
-        validate_header!
-
-        # Parse bitmap size records
-        parse_bitmap_sizes(io)
-      rescue StandardError => e
-        raise CorruptedTableError, "Failed to parse CBLC table: #{e.message}"
+      # @return [Array<CblcIndexSubTable>]
+      def index_sub_tables
+        @index_sub_tables ||= bitmap_sizes.flat_map { |s| sub_tables_for(s) }
       end
 
-      # Get bitmap strikes (sizes)
+      # Locate a glyph's CBDT bitmap at a specific ppem.
       #
-      # @return [Array<BitmapSize>] Array of bitmap strikes
-      def strikes
-        bitmap_sizes || []
-      end
+      # @param glyph_id [Integer] source glyph ID
+      # @param ppem [Integer] strike ppem
+      # @return [CblcGlyphBitmapLocation, nil]
+      def bitmap_offset_for_gid(glyph_id, ppem)
+        strike = bitmap_sizes.find do |s|
+          s.ppem == ppem && s.includes_glyph?(glyph_id)
+        end
+        return nil unless strike
 
-      # Get strikes for specific ppem size
-      #
-      # @param ppem [Integer] Pixels per em
-      # @return [Array<BitmapSize>] Strikes matching ppem
-      def strikes_for_ppem(ppem)
-        strikes.select { |size| size.ppem == ppem }
+        sub_tables_for(strike).each do |sub|
+          loc = sub.locations.find { |l| l.glyph_id == glyph_id }
+          return loc if loc
+        end
+        nil
       end
 
-      # Check if glyph has bitmap at ppem size
+      # Iterate every IndexSubTable in a single strike.
       #
-      # @param glyph_id [Integer] Glyph ID
-      # @param ppem [Integer] Pixels per em
-      # @return [Boolean] True if glyph has bitmap
-      def has_bitmap_for_glyph?(glyph_id, ppem)
-        strikes_for_ppem(ppem).any? do |strike|
-          strike.includes_glyph?(glyph_id)
+      # @param strike [CblcBitmapSize]
+      # @return [Array<CblcIndexSubTable>]
+      def sub_tables_for(strike)
+        return [] if strike.number_of_index_subtables.zero?
+
+        array_offset = strike.index_subtable_array_offset
+        entries = read_index_subtable_array(strike, array_offset)
+
+        entries.map do |entry|
+          absolute = array_offset + entry.additional_offset_to_index_subtable
+          CblcIndexSubTable.parse(
+            raw_data,
+            index_subtable_offset: absolute,
+            first_glyph_index: entry.first_glyph_index,
+            last_glyph_index: entry.last_glyph_index,
+          )
         end
       end
 
-      # Get all available ppem sizes
+      # All available ppem sizes across every strike.
       #
-      # @return [Array<Integer>] Sorted array of ppem sizes
+      # @return [Array<Integer>]
       def ppem_sizes
-        strikes.map(&:ppem).uniq.sort
+        bitmap_sizes.map(&:ppem).uniq.sort
       end
 
-      # Get all glyph IDs that have bitmaps across all strikes
+      # Number of bitmap strikes.
       #
-      # @return [Array<Integer>] Array of glyph IDs
-      def glyph_ids_with_bitmaps
-        strikes.flat_map { |strike| strike.glyph_range.to_a }.uniq.sort
+      # @return [Integer]
+      def num_strikes
+        num_sizes
       end
 
-      # Get strikes that include a specific glyph ID
+      # Strikes that cover a given glyph ID.
       #
-      # @param glyph_id [Integer] Glyph ID
-      # @return [Array<BitmapSize>] Strikes containing glyph
+      # @param glyph_id [Integer]
+      # @return [Array<CblcBitmapSize>]
       def strikes_for_glyph(glyph_id)
-        strikes.select { |strike| strike.includes_glyph?(glyph_id) }
+        bitmap_sizes.select { |s| s.includes_glyph?(glyph_id) }
       end
 
-      # Get the number of bitmap strikes
+      # Strikes that match a specific ppem.
       #
-      # @return [Integer] Number of strikes
-      def num_strikes
-        num_sizes || 0
+      # @param ppem [Integer]
+      # @return [Array<CblcBitmapSize>]
+      def strikes_for_ppem(ppem)
+        bitmap_sizes.select { |s| s.ppem == ppem }
+      end
+
+      # All glyph IDs that have any bitmap across every strike.
+      #
+      # @return [Array<Integer>]
+      def glyph_ids_with_bitmaps
+        bitmap_sizes.flat_map { |s| s.glyph_range.to_a }.uniq.sort
       end
 
-      # Validate the CBLC table structure
+      # Whether the CBLC header is one fontisan understands and at least
+      # the header fields parsed successfully.
       #
-      # @return [Boolean] True if valid
+      # @return [Boolean]
       def valid?
         return false if version.nil?
         return false unless [VERSION_2_0, VERSION_3_0].include?(version)
-        return false if num_sizes.nil? || num_sizes.negative?
-        return false unless bitmap_sizes
 
         true
       end
 
       private
 
-      # Parse CBLC header (8 bytes)
-      #
-      # @param io [StringIO] Input stream
-      def parse_header(io)
-        @version = io.read(4).unpack1("N")
-        @num_sizes = io.read(4).unpack1("N")
-      end
-
-      # Validate header values
-      #
-      # @raise [CorruptedTableError] If validation fails
-      def validate_header!
-        unless [VERSION_2_0, VERSION_3_0].include?(version)
-          raise CorruptedTableError,
-                "Unsupported CBLC version: 0x#{version.to_s(16).upcase} " \
-                "(only versions 2.0 and 3.0 supported)"
-        end
-
-        if num_sizes.negative?
-          raise CorruptedTableError,
-                "Invalid numSizes: #{num_sizes}"
-        end
-      end
-
-      # Parse bitmap size records
+      # Read the IndexSubTableArray entries for one strike.
       #
-      # @param io [StringIO] Input stream
-      def parse_bitmap_sizes(io)
-        @bitmap_sizes = []
-        return if num_sizes.zero?
-
-        # Each BitmapSize record is 48 bytes
-        num_sizes.times do
-          size_data = io.read(48)
-          @bitmap_sizes << BitmapSize.read(size_data)
+      # @param strike [CblcBitmapSize]
+      # @param array_offset [Integer] absolute offset within CBLC bytes
+      # @return [Array<CblcIndexSubTableArrayEntry>]
+      def read_index_subtable_array(strike, array_offset)
+        count = strike.number_of_index_subtables
+        bytes = raw_data[array_offset, count * 8]
+        return [] unless bytes
+
+        Array.new(count) do |i|
+          CblcIndexSubTableArrayEntry.read(bytes[i * 8, 8])
         end
       end
     end

data/lib/fontisan/tables/cblc_big_glyph_metrics.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    # 8-byte bigGlyphMetrics record embedded in CBLC IndexSubTable formats
+    # 2 and 5 (constant-metrics strikes). Layout is smallGlyphMetrics (5
+    # bytes) plus four additional signed advance fields.
+    #
+    #   uint8 height
+    #   uint8 width
+    #   int8  bearing_x
+    #   int8  bearing_y
+    #   int8  advance
+    #   int8  reserved
+    #   int8  advance_lsb
+    #   int8  advance_rsb
+    class CblcBigGlyphMetrics < Binary::BaseRecord
+      uint8 :height
+      uint8 :width
+      int8 :bearing_x
+      int8 :bearing_y
+      int8 :advance
+      int8 :reserved
+      int8 :advance_lsb
+      int8 :advance_rsb
+    end
+  end
+end

data/lib/fontisan/tables/cblc_bitmap_size.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Tables
+    # BitmapSize record embedded in a CBLC table (48 bytes).
+    #
+    # Each BitmapSize describes one bitmap strike: a glyph range rendered
+    # at a specific ppem with a specific bit depth. It points (via
+    # `index_subtable_array_offset`) at a sequence of IndexSubTableArray
+    # records that further describe how to find the bitmap data for each
+    # glyph in CBDT.
+    #
+    # Layout (48 bytes):
+    #   uint32 index_subtable_array_offset
+    #   uint32 index_tables_size
+    #   uint32 number_of_index_subtables
+    #   uint32 color_ref
+    #   CblcSbitLineMetrics hori (12 bytes)
+    #   CblcSbitLineMetrics vert (12 bytes)
+    #   uint16 start_glyph_index
+    #   uint16 end_glyph_index
+    #   uint8  ppem_x
+    #   uint8  ppem_y
+    #   uint8  bit_depth
+    #   int8   flags
+    #
+    # Reference: OpenType CBLC spec, "BitmapSize" record.
+    class CblcBitmapSize < Binary::BaseRecord
+      uint32 :index_subtable_array_offset
+      uint32 :index_tables_size
+      uint32 :number_of_index_subtables
+      uint32 :color_ref
+      CblcSbitLineMetrics :hori, type: Fontisan::Tables::CblcSbitLineMetrics
+      CblcSbitLineMetrics :vert, type: Fontisan::Tables::CblcSbitLineMetrics
+      uint16 :start_glyph_index
+      uint16 :end_glyph_index
+      uint8 :ppem_x
+      uint8 :ppem_y
+      uint8 :bit_depth
+      int8 :flags
+
+      # Pixels per em, assuming square pixels (the common case).
+      #
+      # @return [Integer] ppem value
+      def ppem
+        ppem_x
+      end
+
+      # Glyph ID range covered by this strike.
+      #
+      # @return [Range<Integer>] inclusive glyph ID range
+      def glyph_range
+        start_glyph_index..end_glyph_index
+      end
+
+      # Whether the strike covers a specific glyph.
+      #
+      # @param glyph_id [Integer] source glyph ID
+      # @return [Boolean]
+      def includes_glyph?(glyph_id)
+        glyph_range.include?(glyph_id)
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cblc_glyph_bitmap_location.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    # Immutable value object locating one glyph's bitmap inside a CBDT table.
+    #
+    # A CblcIndexSubTable produces one of these per glyph in its range.
+    # The subsetting pipeline reads them to know which CBDT byte range to
+    # retain, then computes fresh offsets for the subset output.
+    #
+    # @!attribute glyph_id
+    #   @return [Integer] source glyph ID
+    # @!attribute image_format
+    #   @return [Integer] CBDT image format (e.g. 17, 18, 19)
+    # @!attribute cbdt_offset
+    #   @return [Integer] absolute byte offset within the source CBDT
+    # @!attribute byte_length
+    #   @return [Integer] length of the bitmap block in CBDT
+    CblcGlyphBitmapLocation = Struct.new(:glyph_id, :image_format,
+                                         :cbdt_offset, :byte_length,
+                                         keyword_init: true) do
+      def initialize(*)
+        super
+        freeze
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cblc_index_subtable.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    # Parsed IndexSubTable from a CBLC table.
+    #
+    # The IndexSubTable is the format-specific directory describing how to
+    # locate each glyph's bitmap inside CBDT. Five formats are defined by
+    # the OpenType spec:
+    #
+    #   1 — variable metrics, variable size (uint32 offset array)
+    #   2 — constant metrics, constant size (single imageSize for the range)
+    #   3 — variable metrics, variable size, 4-byte-aligned (uint16 offsets × 4)
+    #   4 — variable metrics, variable size, bit-packed offsets (rare)
+    #   5 — constant metrics, constant size, with explicit uint32 offsetArray
+    #
+    # Each parsed IndexSubTable exposes one [CblcGlyphBitmapLocation] per
+    # glyph in its range, plus the raw bytes so a subsetter can preserve
+    # unchanged subtables verbatim if needed.
+    #
+    # Format-specific parsing is delegated to
+    # [CblcIndexSubTableFormatParser]; this class only owns the data model.
+    #
+    # Reference: OpenType CBLC spec, IndexSubTable formats 1–5.
+    class CblcIndexSubTable
+      # @return [Integer] indexFormat field (1, 2, 3, or 5)
+      attr_reader :index_format
+
+      # @return [Integer] imageFormat field (e.g. 17 = small metrics + PNG)
+      attr_reader :image_format
+
+      # @return [Integer] absolute imageDataOffset from start of CBDT
+      attr_reader :image_data_offset
+
+      # @return [Integer] first glyph ID covered by this subtable
+      attr_reader :first_glyph_index
+
+      # @return [Integer] last glyph ID covered by this subtable
+      attr_reader :last_glyph_index
+
+      # @return [Array<CblcGlyphBitmapLocation>] one per glyph in range
+      attr_reader :locations
+
+      # @return [String] raw bytes of this IndexSubTable in the source CBLC
+      attr_reader :raw_bytes
+
+      def initialize(index_format:, image_format:, image_data_offset:,
+                     first_glyph_index:, last_glyph_index:, locations:,
+                     raw_bytes:)
+        @index_format = index_format
+        @image_format = image_format
+        @image_data_offset = image_data_offset
+        @first_glyph_index = first_glyph_index
+        @last_glyph_index = last_glyph_index
+        @locations = locations
+        @raw_bytes = raw_bytes
+      end
+
+      # Parse an IndexSubTable from a CBLC binary blob.
+      #
+      # @param cblc_bytes [String] the full CBLC table bytes
+      # @param index_subtable_offset [Integer] absolute byte offset within
+      #   `cblc_bytes` where this IndexSubTable begins
+      # @param first_glyph_index [Integer] first glyph ID covered
+      # @param last_glyph_index [Integer] last glyph ID covered
+      # @return [CblcIndexSubTable]
+      def self.parse(cblc_bytes, index_subtable_offset:, first_glyph_index:,
+                     last_glyph_index:)
+        header = CblcIndexSubTableHeader.read(
+          cblc_bytes[index_subtable_offset, 8],
+        )
+
+        new(
+          index_format: header.index_format,
+          image_format: header.image_format,
+          image_data_offset: header.image_data_offset,
+          first_glyph_index: first_glyph_index,
+          last_glyph_index: last_glyph_index,
+          locations: CblcIndexSubTableFormatParser.locations(
+            header: header,
+            bytes: cblc_bytes,
+            base: index_subtable_offset,
+            first: first_glyph_index,
+            last: last_glyph_index,
+          ),
+          raw_bytes: CblcIndexSubTableFormatParser.raw_bytes(
+            header: header,
+            bytes: cblc_bytes,
+            base: index_subtable_offset,
+            first: first_glyph_index,
+            last: last_glyph_index,
+          ),
+        )
+      end
+
+      # Number of glyphs covered by this subtable.
+      #
+      # @return [Integer]
+      def glyph_count
+        last_glyph_index - first_glyph_index + 1
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cblc_index_subtable_array_entry.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    # Entry in a CBLC IndexSubTableArray (8 bytes).
+    #
+    # The IndexSubTableArray sits at `BitmapSize#index_subtable_array_offset`
+    # (relative to the start of CBLC) and contains `number_of_index_subtables`
+    # of these entries. Each entry points (via `additional_offset_to_index_subtable`,
+    # relative to the IndexSubTableArray's own location) at an IndexSubTable
+    # record describing how to find the bitmaps for a glyph range.
+    #
+    # Reference: OpenType CBLC spec, IndexSubTableArray record.
+    class CblcIndexSubTableArrayEntry < Binary::BaseRecord
+      uint16 :first_glyph_index
+      uint16 :last_glyph_index
+      uint32 :additional_offset_to_index_subtable
+    end
+  end
+end