Class: Fontisan::SfntFont Abstract

Inherits:
BinData::Record
  • Object
show all
Defined in:
lib/fontisan/sfnt_font.rb

Overview

This class is abstract.

Subclasses must implement format-specific validation

Base class for SFNT font formats (TrueType and OpenType)

This class contains all shared SFNT structure and behavior. TrueType and OpenType fonts inherit from this class and add format-specific functionality.

Examples:

Reading a font (format detected automatically)

font = Fontisan::FontLoader.load("font.ttf")  # Returns TrueTypeFont
font = Fontisan::FontLoader.load("font.otf")  # Returns OpenTypeFont

Reading and analyzing a font

ttf = Fontisan::TrueTypeFont.from_file("font.ttf")
puts ttf.header.num_tables  # => 14
name_table = ttf.table("name")
puts name_table.english_name(Tables::Name::FAMILY)

Loading with metadata mode

ttf = Fontisan::TrueTypeFont.from_file("font.ttf", mode: :metadata)
puts ttf.loading_mode  # => :metadata
ttf.table_available?("GSUB")  # => false

Writing a font

ttf.to_file("output.ttf")

Direct Known Subclasses

OpenTypeFont, TrueTypeFont

Constant Summary collapse

TABLE_CLASS_MAP =

Map table tag to parser class (cached as constant for performance)

Returns:

  • (Hash<String, Class>) —

    Mapping of table tags to parser classes

{
  Constants::HEAD_TAG => Tables::Head,
  Constants::HHEA_TAG => Tables::Hhea,
  Constants::HMTX_TAG => Tables::Hmtx,
  Constants::MAXP_TAG => Tables::Maxp,
  Constants::NAME_TAG => Tables::Name,
  Constants::OS2_TAG => Tables::Os2,
  Constants::POST_TAG => Tables::Post,
  Constants::CMAP_TAG => Tables::Cmap,
  Constants::FVAR_TAG => Tables::Fvar,
  Constants::GSUB_TAG => Tables::Gsub,
  Constants::GPOS_TAG => Tables::Gpos,
  Constants::GLYF_TAG => Tables::Glyf,
  Constants::LOCA_TAG => Tables::Loca,
  "SVG " => Tables::Svg,
  "COLR" => Tables::Colr,
  "CPAL" => Tables::Cpal,
  "CBDT" => Tables::Cbdt,
  "CBLC" => Tables::Cblc,
  "sbix" => Tables::Sbix,
}.freeze
SFNT_TABLE_CLASS_MAP =

Map table tag to SfntTable wrapper class (cached as constant for performance)

Returns:

  • (Hash<String, Class>) —

    Mapping of table tags to SfntTable wrapper classes

{
  Constants::HEAD_TAG => Tables::HeadTable,
  Constants::NAME_TAG => Tables::NameTable,
  Constants::OS2_TAG => Tables::Os2Table,
  Constants::CMAP_TAG => Tables::CmapTable,
  Constants::GLYF_TAG => Tables::GlyfTable,
  Constants::HHEA_TAG => Tables::HheaTable,
  Constants::MAXP_TAG => Tables::MaxpTable,
  Constants::POST_TAG => Tables::PostTable,
  Constants::HMTX_TAG => Tables::HmtxTable,
  Constants::LOCA_TAG => Tables::LocaTable,
}.freeze
PADDING_BYTES =

Padding bytes for table alignment (frozen to avoid reallocation)

("\x00" * 4).freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#io_source ⇒ Object

IO source for lazy loading



86
87
88
 
# File 'lib/fontisan/sfnt_font.rb', line 86

def io_source
  @io_source
end

#lazy_load_enabled ⇒ Object

Whether lazy loading is enabled



89
90
91
 
# File 'lib/fontisan/sfnt_font.rb', line 89

def lazy_load_enabled
  @lazy_load_enabled
end

#loading_mode ⇒ Object

Loading mode for this font (:metadata or :full)



83
84
85
 
# File 'lib/fontisan/sfnt_font.rb', line 83

def loading_mode
  @loading_mode
end

#parsed_tables ⇒ Object

Parsed table instances cache



74
75
76
 
# File 'lib/fontisan/sfnt_font.rb', line 74

def parsed_tables
  @parsed_tables
end

#sfnt_tables ⇒ Object

OOP SfntTable instances (tag => SfntTable)



77
78
79
 
# File 'lib/fontisan/sfnt_font.rb', line 77

def sfnt_tables
  @sfnt_tables
end

#table_data ⇒ Object

Table data is stored separately since it's at variable offsets. The setter normalizes all keys to UTF-8 so Hash lookups don't silently miss due to encoding mismatch — BinData-derived tag strings are ASCII-8BIT, literals callers pass are usually UTF-8, and String#eql? is encoding-sensitive.



67
68
69
 
# File 'lib/fontisan/sfnt_font.rb', line 67

def table_data
  @table_data
end

#table_entry_cache ⇒ Object

Table entry lookup cache (tag => TableDirectory)



80
81
82
 
# File 'lib/fontisan/sfnt_font.rb', line 80

def table_entry_cache
  @table_entry_cache
end

Class Method Details

.finalize(io) ⇒ Proc

Finalizer proc for closing IO

Parameters:

  • io (IO) —

    The IO object to close

Returns:

  • (Proc) —

    The finalizer proc



585
586
587
 
# File 'lib/fontisan/sfnt_font.rb', line 585

def self.finalize(io)
  proc { io&.close }
end

.from_collection(io, offset, mode: LoadingModes::FULL) ⇒ SfntFont

Read SFNT Font from collection at specific offset

Parameters:

  • io (IO) —

    Open file handle

  • offset (Integer) —

    Byte offset to the font

  • mode (Symbol) (defaults to: LoadingModes::FULL) —

    Loading mode (:metadata or :full, default: :full)

Returns:



202
203
204
205
206
207
208
209
210
211
 
# File 'lib/fontisan/sfnt_font.rb', line 202

def self.from_collection(io, offset, mode: LoadingModes::FULL)
  LoadingModes.validate_mode!(mode)

  io.seek(offset)
  font = read(io)
  font.initialize_storage
  font.loading_mode = mode
  font.read_table_data(io)
  font
end

.from_file(path, mode: LoadingModes::FULL, lazy: false) ⇒ SfntFont

Read SFNT Font from a file

Parameters:

  • path (String) —

    Path to the font file

  • mode (Symbol) (defaults to: LoadingModes::FULL) —

    Loading mode (:metadata or :full, default: :full)

  • lazy (Boolean) (defaults to: false) —

    If true, load tables on demand (default: false)

Returns:

Raises:

  • (ArgumentError) —

    if path is nil or empty, or if mode is invalid

  • (Errno::ENOENT) —

    if file does not exist

  • (RuntimeError) —

    if file format is invalid



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/fontisan/sfnt_font.rb', line 144

def self.from_file(path, mode: LoadingModes::FULL, lazy: false)
  if path.nil? || path.to_s.empty?
    raise ArgumentError, "path cannot be nil or empty"
  end
  raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)

  LoadingModes.validate_mode!(mode)

  font = new
  font.initialize_storage
  font.loading_mode = mode
  font.lazy_load_enabled = lazy

  lazy ? load_lazy(path, font) : load_eager(path, font)
end

Instance Method Details

#all_sfnt_tables ⇒ Hash<String, SfntTable>

Get all SfntTable instances

Returns:

  • (Hash<String, SfntTable>) —

    Hash mapping tag => SfntTable instance



471
472
473
 
# File 'lib/fontisan/sfnt_font.rb', line 471

def all_sfnt_tables
  table_names.to_h { |tag| [tag, sfnt_table(tag)] }
end

#close ⇒ void

This method returns an undefined value.

Close the IO source (for lazy loading)



569
570
571
572
 
# File 'lib/fontisan/sfnt_font.rb', line 569

def close
  @io_source&.close
  @io_source = nil
end

#collection? ⇒ Boolean

Whether this object represents a font collection rather than a single font. Each font class is the authority on this question.

Returns:

  • (Boolean) 


376
 
# File 'lib/fontisan/sfnt_font.rb', line 376

def collection? = false

#family_name ⇒ String?

Get font family name

Returns:

  • (String, nil) —

    Family name or nil if not found



521
522
523
524
 
# File 'lib/fontisan/sfnt_font.rb', line 521

def family_name
  name_table = table(Constants::NAME_TAG)
  name_table&.english_name(Tables::Name::FAMILY)
end

#find_table_entry(tag) ⇒ TableDirectory?

Find a table entry by tag (cached for performance)

Parameters:

  • tag (String) —

    The table tag to find

Returns:



415
416
417
418
419
420
421
 
# File 'lib/fontisan/sfnt_font.rb', line 415

def find_table_entry(tag)
  return @table_entry_cache[tag] if @table_entry_cache.key?(tag)

  entry = tables.find { |entry| entry.tag == tag }
  @table_entry_cache[tag] = entry
  entry
end

#full_name ⇒ String?

Get full font name

Returns:

  • (String, nil) —

    Full name or nil if not found



537
538
539
540
 
# File 'lib/fontisan/sfnt_font.rb', line 537

def full_name
  name_table = table(Constants::NAME_TAG)
  name_table&.english_name(Tables::Name::FULL_NAME)
end

#has_table?(tag) ⇒ Boolean

Check if font has a specific table (optimized with cache)

Parameters:

  • tag (String) —

    The table tag to check for

Returns:

  • (Boolean) —

    true if table exists, false otherwise



368
369
370
 
# File 'lib/fontisan/sfnt_font.rb', line 368

def has_table?(tag)
  !find_table_entry(tag).nil?
end

#head_table ⇒ TableDirectory?

Get the head table entry

Returns:



426
427
428
 
# File 'lib/fontisan/sfnt_font.rb', line 426

def head_table
  find_table_entry(Constants::HEAD_TAG)
end

#initialize_storage ⇒ void

This method returns an undefined value.

Initialize storage hashes



216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/fontisan/sfnt_font.rb', line 216

def initialize_storage
  @table_data = {}
  @parsed_tables = {}
  @sfnt_tables = {}
  @table_entry_cache = {}
  @tag_encoding_cache = {} # Cache for normalized tag encodings
  @table_names = nil # Cache for table names array
  @loading_mode = LoadingModes::FULL
  @lazy_load_enabled = false
  @io_source = nil
end

#outline_type ⇒ Symbol

Outline representation used by the font. Derived from the table set.

Returns:

  • (Symbol) —

    :truetype (glyf/gvar) or :cff (CFF/CFF2)



394
395
396
397
398
399
 
# File 'lib/fontisan/sfnt_font.rb', line 394

def outline_type
  return :truetype if has_table?("glyf") || has_table?("gvar")
  return :cff if has_table?("CFF ") || has_table?("CFF2")

  :unknown
end

#post_script_name ⇒ String?

Get PostScript name

Returns:

  • (String, nil) —

    PostScript name or nil if not found



545
546
547
548
 
# File 'lib/fontisan/sfnt_font.rb', line 545

def post_script_name
  name_table = table(Constants::NAME_TAG)
  name_table&.english_name(Tables::Name::POSTSCRIPT_NAME)
end

#preferred_family_name ⇒ String?

Get preferred family name

Returns:

  • (String, nil) —

    Preferred family name or nil if not found



553
554
555
556
 
# File 'lib/fontisan/sfnt_font.rb', line 553

def preferred_family_name
  name_table = table(Constants::NAME_TAG)
  name_table&.english_name(Tables::Name::PREFERRED_FAMILY)
end

#preferred_subfamily_name ⇒ String?

Get preferred subfamily name

Returns:

  • (String, nil) —

    Preferred subfamily name or nil if not found



561
562
563
564
 
# File 'lib/fontisan/sfnt_font.rb', line 561

def preferred_subfamily_name
  name_table = table(Constants::NAME_TAG)
  name_table&.english_name(Tables::Name::PREFERRED_SUBFAMILY)
end

#read_metadata_tables_batched(io) ⇒ void

This method returns an undefined value.

Read metadata tables using page-aware batching

Groups adjacent tables within page boundaries and reads them together to maximize filesystem prefetching and minimize random seeks.

Parameters:

  • io (IO) —

    Open file handle



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'lib/fontisan/sfnt_font.rb', line 266

def read_metadata_tables_batched(io)
  # Typical filesystem page size (4KB is common, but 8KB gives better prefetch window)
  page_threshold = 8192

  # Get metadata tables sorted by offset for sequential access
  metadata_entries = tables.select { |entry| LoadingModes::METADATA_TABLES_SET.include?(entry.tag) }
  metadata_entries.sort_by!(&:offset)

  return if metadata_entries.empty?

  # Group adjacent tables within page threshold for batched reading
  i = 0
  while i < metadata_entries.size
    batch_start = metadata_entries[i]
    batch_end = batch_start
    batch_entries = [batch_start]

    # Extend batch while next table is within page threshold
    j = i + 1
    while j < metadata_entries.size
      next_entry = metadata_entries[j]
      gap = next_entry.offset - (batch_end.offset + batch_end.table_length)

      # If gap is small (within page threshold), include in batch
      if gap <= page_threshold
        batch_end = next_entry
        batch_entries << next_entry
        j += 1
      else
        break
      end
    end

    # Read batch
    if batch_entries.size == 1
      # Single table, read normally
      io.seek(batch_start.offset)
      tag_key = normalize_tag(batch_start.tag)
      @table_data[tag_key] = io.read(batch_start.table_length)
    else
      # Multiple tables, read contiguous segment
      batch_offset = batch_start.offset
      batch_length = (batch_end.offset + batch_end.table_length) - batch_start.offset

      io.seek(batch_offset)
      batch_data = io.read(batch_length)

      # Extract individual tables from batch
      batch_entries.each do |entry|
        relative_offset = entry.offset - batch_offset
        tag_key = normalize_tag(entry.tag)
        @table_data[tag_key] =
          batch_data[relative_offset, entry.table_length]
      end
    end

    i = j
  end
end

#read_table_data(io) ⇒ void

This method returns an undefined value.

Read table data for all tables in the font

In metadata mode, only reads metadata tables. In full mode, reads all tables. In lazy load mode, doesn't read data upfront.

Parameters:

  • io (IO) —

    IO object to read from



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/fontisan/sfnt_font.rb', line 235

def read_table_data(io)
  @table_data = {}

  if @lazy_load_enabled
    # Don't read data, just keep IO reference
    @io_source = io
    return
  end

  if @loading_mode == LoadingModes::METADATA
    # Only read metadata tables for performance
    # Use page-aware batched reading to maximize filesystem prefetching
    read_metadata_tables_batched(io)
  else
    # Read all tables
    tables.each do |entry|
      io.seek(entry.offset)
      # Normalize tag encoding for hash key consistency
      tag_key = normalize_tag(entry.tag)
      @table_data[tag_key] = io.read(entry.table_length)
    end
  end
end

#setup_finalizer ⇒ void

This method returns an undefined value.

Setup finalizer for cleanup



577
578
579
 
# File 'lib/fontisan/sfnt_font.rb', line 577

def setup_finalizer
  ObjectSpace.define_finalizer(self, self.class.finalize(@io_source))
end

#sfnt_table(tag) ⇒ SfntTable?

Get OOP SfntTable instance for a table

Returns a SfntTable (or subclass) instance that encapsulates the table's metadata, lazy loading, parsing, and validation. This provides a more object-oriented interface than the separate TableDirectory/@table_data/@parsed_tables approach.

Examples:

Using SfntTable for validation

head = font.sfnt_table("head")
head.validate!  # Performs head-specific validation
head.units_per_em  # => 2048 (convenience method)

Parameters:

  • tag (String) —

    The table tag to retrieve

Returns:

  • (SfntTable, nil) —

    SfntTable instance (or subclass like HeadTable), or nil if not found



456
457
458
459
460
461
462
463
464
465
466
 
# File 'lib/fontisan/sfnt_font.rb', line 456

def sfnt_table(tag)
  # Return cached instance if available (fast path)
  cached = @sfnt_tables[tag]
  return cached if cached

  # Only check has_table? if not cached (avoids redundant lookup)
  return nil unless has_table?(tag)

  # Create and cache (find_table_entry is already cached internally)
  @sfnt_tables[tag] = create_sfnt_table(tag)
end

#subfamily_name ⇒ String?

Get font subfamily name (e.g., Regular, Bold, Italic)

Returns:

  • (String, nil) —

    Subfamily name or nil if not found



529
530
531
532
 
# File 'lib/fontisan/sfnt_font.rb', line 529

def subfamily_name
  name_table = table(Constants::NAME_TAG)
  name_table&.english_name(Tables::Name::SUBFAMILY)
end

#table(tag) ⇒ Tables::*?

Get parsed table instance

This method parses the raw table data into a structured table object and caches the result for subsequent calls. Enforces mode restrictions.

Parameters:

  • tag (String) —

    The table tag to retrieve

Returns:

  • (Tables::*, nil) —

    Parsed table object or nil if not found

Raises:

  • (ArgumentError) —

    if table is not available in current loading mode



483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
 
# File 'lib/fontisan/sfnt_font.rb', line 483

def table(tag)
  tag = normalize_tag(tag)

  # Check mode restrictions
  unless table_available?(tag)
    if has_table?(tag)
      raise ArgumentError,
            "Table '#{tag}' is not available in #{@loading_mode} mode. " \
            "Available tables: #{LoadingModes.tables_for(@loading_mode).inspect}"
    else
      return nil
    end
  end

  # Return cached if available (fast path)
  return @parsed_tables[tag] if @parsed_tables.key?(tag)

  # Lazy load table data if enabled
  load_table_data(tag) if @lazy_load_enabled && !@table_data.key?(tag)

  # Parse and cache
  @parsed_tables[tag] ||= parse_table(tag)
end

#table_available?(tag) ⇒ Boolean

Check if a table is available in the current loading mode

Parameters:

  • tag (String) —

    The table tag to check

Returns:

  • (Boolean) —

    true if table is available in current mode



405
406
407
408
409
 
# File 'lib/fontisan/sfnt_font.rb', line 405

def table_available?(tag)
  return false unless has_table?(tag)

  LoadingModes.table_allowed?(@loading_mode, tag)
end

#table_names ⇒ Array<String>

Get list of all table tags (cached for performance)

Returns plain UTF-8 Ruby Strings, not BinData::String instances — callers can rely on eql?/==/Hash lookup working against literal strings. BinData::String is encoding-sensitive and breaks Hash key comparison silently.

Returns:

  • (Array<String>) —

    Array of table tag strings (UTF-8)



438
439
440
 
# File 'lib/fontisan/sfnt_font.rb', line 438

def table_names
  @table_names ||= tables.map { |entry| normalize_tag(entry.tag) }
end

#to_file(path) ⇒ Integer

Write SFNT Font to a file

Writes the complete font structure to disk, including proper checksum calculation and table alignment.

Parameters:

  • path (String) —

    Path where the font file will be written

Returns:

  • (Integer) —

    Number of bytes written

Raises:

  • (IOError) —

    if writing fails



334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/fontisan/sfnt_font.rb', line 334

def to_file(path)
  File.open(path, "w+b") do |io|
    # Write header and tables (directory)
    write_structure(io)

    # Write table data with updated offsets
    write_table_data_with_offsets(io)

    # Update checksum adjustment in head table BEFORE closing file
    # This avoids Windows file locking issues when Tempfiles are used
    head = head_table
    update_checksum_adjustment_in_io(io, head.offset) if head

    io.pos
  end

  File.size(path)
end

#units_per_em ⇒ Integer?

Get units per em from head table

Returns:

  • (Integer, nil) —

    Units per em value



510
511
512
513
 
# File 'lib/fontisan/sfnt_font.rb', line 510

def units_per_em
  head = table(Constants::HEAD_TAG)
  head&.units_per_em
end

#update_checksum_adjustment_in_file(path, head_offset) ⇒ void

This method returns an undefined value.

Update checksum adjustment in head table by file path

Opens the file, calculates the checksum, and updates the adjustment.

Parameters:

  • path (String) —

    Path to the font file

  • head_offset (Integer) —

    Offset to the head table



612
613
614
615
616
 
# File 'lib/fontisan/sfnt_font.rb', line 612

def update_checksum_adjustment_in_file(path, head_offset)
  File.open(path, "r+b") do |io|
    update_checksum_adjustment_in_io(io, head_offset)
  end
end

#update_checksum_adjustment_in_io(io, head_offset) ⇒ void

This method returns an undefined value.

Update checksum adjustment in head table using IO

Calculates the checksum of the entire file and writes the adjustment value to the head table's checksumAdjustment field.

Parameters:

  • io (IO) —

    IO object to read from and write to

  • head_offset (Integer) —

    Offset to the head table



597
598
599
600
601
602
603
 
# File 'lib/fontisan/sfnt_font.rb', line 597

def update_checksum_adjustment_in_io(io, head_offset)
  io.rewind
  checksum = Utilities::ChecksumCalculator.calculate_checksum_from_io(io)
  adjustment = Utilities::ChecksumCalculator.calculate_adjustment(checksum)
  io.seek(head_offset + 8)
  io.write([adjustment].pack("N"))
end

#valid? ⇒ Boolean

Validate format correctness

Returns:

  • (Boolean) —

    true if the font format is valid, false otherwise



356
357
358
359
360
361
362
 
# File 'lib/fontisan/sfnt_font.rb', line 356

def valid?
  return false unless header
  return false unless tables.length == header.num_tables
  return false unless head_table

  true
end

#variation_type ⇒ Symbol

Variation profile of the font, derived from its table set. Used by the conversion pipeline to choose between preserving variation tables and generating a static instance.

Returns:

  • (Symbol) —

    :static, :gvar (TrueType variable), or :cff2 (CFF2 variable)



383
384
385
386
387
388
389
 
# File 'lib/fontisan/sfnt_font.rb', line 383

def variation_type
  return :static unless has_table?("fvar")
  return :gvar if has_table?("gvar")
  return :cff2 if has_table?("CFF2")

  :static
end