freetype-ruby 1.0.0

data/lib/freetype/face/rasterization.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module FreeType
+  module FaceRasterization
+    def char_index(character)
+      ensure_open!
+      Native.FT_Get_Char_Index(pointer, codepoint_for(character))
+    end
+
+    def glyph(character, mode: :gray, spread: 8, load_flags: Native::FT_LOAD_DEFAULT)
+      glyph_by_id(char_index(character), mode: mode, spread: spread, load_flags: load_flags)
+    end
+
+    def glyph_by_id(glyph_id, mode: :gray, spread: 8, load_flags: Native::FT_LOAD_DEFAULT)
+      ensure_open!
+      id = Integer(glyph_id)
+      raise RangeError, "glyph id #{id} is outside this face" unless id.between?(0, glyph_count - 1)
+
+      render_mode = self.class::RENDER_MODES.fetch(mode) do
+        raise ArgumentError, "unknown render mode #{mode.inspect}"
+      end
+      prepare_sdf!(spread) if mode == :sdf
+      flags = Integer(load_flags) & ~Native::FT_LOAD_RENDER
+      flags |= Native::FT_LOAD_TARGET_MONO if mode == :mono
+      Native.check!(Native.FT_Load_Glyph(pointer, id, flags), "FT_Load_Glyph")
+      slot_pointer = raw[:glyph]
+      Native.check!(Native.FT_Render_Glyph(slot_pointer, render_mode), "FT_Render_Glyph")
+      Glyph.new(id: id, slot: Native::GlyphSlotRec.new(slot_pointer))
+    end
+
+    def kerning(left_glyph_id, right_glyph_id)
+      ensure_open!
+      vector = Native::Vector.new
+      Native.check!(
+        Native.FT_Get_Kerning(
+          pointer, Integer(left_glyph_id), Integer(right_glyph_id),
+          Native::FT_KERNING_DEFAULT, vector.pointer
+        ),
+        "FT_Get_Kerning"
+      )
+      FixedPoint.from_26_6(vector[:x])
+    end
+
+    def line_advance(text)
+      previous = nil
+      String(text).each_codepoint.sum(0.0) do |codepoint|
+        id = char_index(codepoint)
+        adjustment = previous ? kerning(previous, id) : 0.0
+        previous = id
+        adjustment + glyph_by_id(id).advance
+      end
+    end
+
+    private
+
+    def prepare_sdf!(spread)
+      unless (library.version <=> [2, 11, 0]) >= 0
+        raise UnsupportedError, "SDF rendering requires FreeType 2.11 or newer (found #{library.version.join('.')})"
+      end
+      unless spread.is_a?(Integer) && spread.between?(2, 32)
+        raise ArgumentError, "spread must be an integer between 2 and 32"
+      end
+
+      value = FFI::MemoryPointer.new(:uint)
+      value.write_uint(spread)
+      Native.check!(Native.FT_Property_Set(library.pointer, "sdf", "spread", value), "FT_Property_Set")
+    end
+
+    def codepoint_for(character)
+      return character if character.is_a?(Integer) && character.between?(0, 0x10FFFF)
+
+      codepoints = String(character).codepoints
+      raise ArgumentError, "expected exactly one Unicode codepoint" unless codepoints.length == 1
+
+      codepoints.first
+    end
+  end
+end

data/lib/freetype/face.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative "face/rasterization"
+
+module FreeType
+  class Face
+    include FaceRasterization
+
+    RENDER_MODES = {
+      gray: Native::FT_RENDER_MODE_NORMAL,
+      normal: Native::FT_RENDER_MODE_NORMAL,
+      mono: Native::FT_RENDER_MODE_MONO,
+      sdf: Native::FT_RENDER_MODE_SDF
+    }.freeze
+
+    attr_reader :library, :pointer, :source_bytes
+
+    def initialize(library, source, face_index: 0)
+      @library = library
+      @state = { closed: false }
+      @pointer = create_face(source, face_index)
+      @state[:pointer] = @pointer
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@state))
+    rescue StandardError
+      @memory = nil
+      @source_bytes = nil
+      raise
+    end
+
+    def self.finalizer(state)
+      proc do
+        next if state[:closed] || !state[:pointer]
+
+        Native.FT_Done_Face(state[:pointer])
+        state[:closed] = true
+      end
+    end
+
+    def close
+      return if closed?
+
+      Native.check!(Native.FT_Done_Face(pointer), "FT_Done_Face")
+      @state[:closed] = true
+      library.__send__(:unregister, self)
+      @memory = nil
+      @source_bytes = nil
+      nil
+    end
+
+    def closed?
+      @state[:closed]
+    end
+
+    def raw
+      ensure_open!
+      Native::FaceRec.new(pointer)
+    end
+
+    def family_name
+      read_string(raw[:family_name])
+    end
+
+    def style_name
+      read_string(raw[:style_name])
+    end
+
+    def units_per_em
+      raw[:units_per_em]
+    end
+
+    def glyph_count
+      raw[:num_glyphs]
+    end
+
+    def scalable?
+      (raw[:face_flags] & Native::FT_FACE_FLAG_SCALABLE) != 0
+    end
+
+    def has_kerning?
+      (raw[:face_flags] & Native::FT_FACE_FLAG_KERNING) != 0
+    end
+
+    def set_pixel_size(height, width: 0)
+      ensure_open!
+      validate_positive_integer!(height, "height")
+      raise ArgumentError, "width must be a non-negative integer" unless width.is_a?(Integer) && width >= 0
+
+      Native.check!(Native.FT_Set_Pixel_Sizes(pointer, width, height), "FT_Set_Pixel_Sizes")
+      self
+    end
+
+    def set_char_size(pt:, dpi: 96, width: 0, horizontal_dpi: dpi)
+      ensure_open!
+      validate_positive_number!(pt, "pt")
+      validate_positive_integer!(dpi, "dpi")
+      raise ArgumentError, "width must be non-negative" unless width.is_a?(Numeric) && width >= 0
+      validate_positive_integer!(horizontal_dpi, "horizontal_dpi")
+
+      Native.check!(
+        Native.FT_Set_Char_Size(pointer, (width * 64).round, (pt * 64).round, horizontal_dpi, dpi),
+        "FT_Set_Char_Size"
+      )
+      self
+    end
+
+    def select_charmap(encoding = :unicode)
+      ensure_open!
+      native_encoding = encoding == :unicode ? Native::FT_ENCODING_UNICODE : Integer(encoding)
+      Native.check!(Native.FT_Select_Charmap(pointer, native_encoding), "FT_Select_Charmap")
+      self
+    end
+
+    def metrics
+      size_pointer = raw[:size]
+      raise StateError, "set a face size before reading metrics" if size_pointer.null?
+
+      native = Native::SizeRec.new(size_pointer)[:metrics]
+      Metrics.new(
+        ascender: FixedPoint.from_26_6(native[:ascender]),
+        descender: FixedPoint.from_26_6(native[:descender]),
+        line_height: FixedPoint.from_26_6(native[:height]),
+        max_advance: FixedPoint.from_26_6(native[:max_advance])
+      )
+    end
+
+    private
+
+    def native_state
+      @state
+    end
+
+    def create_face(source, face_index)
+      output = FFI::MemoryPointer.new(:pointer)
+      index = Integer(face_index)
+      if path_source?(source)
+        path = source.respond_to?(:to_path) ? source.to_path : source
+        Native.check!(Native.FT_New_Face(library.pointer, path.to_s, index, output), "FT_New_Face")
+      else
+        retain_memory_source(source)
+        Native.check!(
+          Native.FT_New_Memory_Face(library.pointer, @memory, @source_bytes.bytesize, index, output),
+          "FT_New_Memory_Face"
+        )
+      end
+      output.read_pointer
+    end
+
+    def path_source?(source)
+      return true if source.respond_to?(:to_path)
+      return false unless source.is_a?(String)
+      return false if source.encoding == Encoding::BINARY || source.include?("\0")
+      return true if File.file?(source)
+
+      source.match?(/\.(?:ttf|ttc|otf|otc|woff2?)\z/i) || source.include?(File::SEPARATOR)
+    end
+
+    def retain_memory_source(source)
+      @source_bytes = String(source).dup.force_encoding(Encoding::BINARY).freeze
+      raise ArgumentError, "font bytes cannot be empty" if @source_bytes.empty?
+
+      @memory = FFI::MemoryPointer.new(:uchar, @source_bytes.bytesize)
+      @memory.put_bytes(0, @source_bytes)
+    end
+
+    def read_string(native_pointer)
+      native_pointer.null? ? nil : native_pointer.read_string.force_encoding(Encoding::UTF_8)
+    end
+
+    def validate_positive_number!(value, name)
+      return if value.is_a?(Numeric) && value.positive?
+
+      raise ArgumentError, "#{name} must be positive"
+    end
+
+    def validate_positive_integer!(value, name)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive integer"
+    end
+
+    def ensure_open!
+      raise ClosedError, "face is closed" if closed?
+      raise ClosedError, "library is closed" if library.closed?
+    end
+  end
+end

data/lib/freetype/glyph.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module FreeType
+  class Glyph
+    attr_reader :id, :bitmap, :bearing_x, :bearing_y, :advance, :width, :height, :raw
+
+    def initialize(id:, slot:)
+      native_bitmap = slot[:bitmap]
+      @id = id
+      @width = native_bitmap[:width]
+      @height = native_bitmap[:rows]
+      @bearing_x = slot[:bitmap_left].to_f
+      @bearing_y = slot[:bitmap_top].to_f
+      @advance = FixedPoint.from_26_6(slot[:advance][:x])
+      @raw = slot
+      @bitmap = Image.build(width: width, height: height, data: BitmapConverter.copy(native_bitmap))
+      freeze
+    end
+  end
+end

data/lib/freetype/harfbuzz.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+begin
+  require "harfbuzz"
+rescue LoadError => error
+  raise LoadError, "freetype/harfbuzz requires the optional harfbuzz-ruby gem (#{error.message})"
+end
+
+require_relative "../freetype"
+require_relative "text_run"

data/lib/freetype/image.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+begin
+  require "texel"
+rescue LoadError
+  # Texel is an optional integration.
+end
+
+module FreeType
+  module Image
+    module_function
+
+    def build(width:, height:, data:)
+      bytes = String(data).dup.force_encoding(Encoding::BINARY).freeze
+      if defined?(Texel::Image) && width.positive? && height.positive?
+        return Texel::Image.new(
+          width: width, height: height, channels: 1, dtype: :u8,
+          color_space: :linear, data: bytes
+        )
+      end
+
+      { width: width, height: height, data: bytes }.freeze
+    end
+
+    def data(image)
+      image.respond_to?(:data) ? image.data : image.fetch(:data)
+    end
+  end
+end

data/lib/freetype/library.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "set"
+
+module FreeType
+  class Library
+    include Enumerable
+
+    attr_reader :pointer
+
+    def initialize
+      output = FFI::MemoryPointer.new(:pointer)
+      Native.check!(Native.FT_Init_FreeType(output), "FT_Init_FreeType")
+      @pointer = output.read_pointer
+      @faces = Set.new
+      @state = { pointer: @pointer, faces: [], closed: false }
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@state))
+    end
+
+    def self.open
+      library = new
+      return library unless block_given?
+
+      begin
+        yield library
+      ensure
+        library.close
+      end
+    end
+
+    def self.finalizer(state)
+      proc do
+        next if state[:closed]
+
+        state[:faces].each do |face_state|
+          next if face_state[:closed]
+
+          Native.FT_Done_Face(face_state[:pointer])
+          face_state[:closed] = true
+        end
+        Native.FT_Done_FreeType(state[:pointer])
+        state[:closed] = true
+      end
+    end
+
+    def face(source, face_index: 0)
+      ensure_open!
+      created = Face.new(self, source, face_index: face_index)
+      @faces.add(created)
+      @state[:faces] << created.__send__(:native_state)
+      return created unless block_given?
+
+      begin
+        yield created
+      ensure
+        created.close
+      end
+    end
+
+    def each(&block)
+      @faces.each(&block)
+    end
+
+    def version
+      ensure_open!
+      values = Array.new(3) { FFI::MemoryPointer.new(:int) }
+      Native.FT_Library_Version(pointer, *values)
+      values.map(&:read_int).freeze
+    end
+
+    def close
+      return if closed?
+
+      @faces.to_a.each(&:close)
+      Native.check!(Native.FT_Done_FreeType(pointer), "FT_Done_FreeType")
+      @state[:closed] = true
+      nil
+    end
+
+    def closed?
+      @state[:closed]
+    end
+
+    private
+
+    def unregister(face)
+      @faces.delete(face)
+      @state[:faces].delete(face.__send__(:native_state))
+    end
+
+    def ensure_open!
+      raise ClosedError, "library is closed" if closed?
+    end
+  end
+end

data/lib/freetype/metrics.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FreeType
+  Metrics = Data.define(:ascender, :descender, :line_height, :max_advance)
+
+  module FixedPoint
+    module_function
+
+    def from_26_6(value)
+      Integer(value) / 64.0
+    end
+
+    def from_16_16(value)
+      Integer(value) / 65_536.0
+    end
+  end
+end

data/lib/freetype/native/structs.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module FreeType
+  module Native
+    module Structs
+      module_function
+
+      def define(name, fields)
+        klass = Class.new(FFI::Struct)
+        klass.layout(*fields.flatten)
+        Native.const_set(name, klass)
+      end
+
+      def define_all
+        define(:Generic, data: :pointer, finalizer: :pointer)
+        define(:Vector, x: :long, y: :long)
+        define(:BBox, x_min: :long, y_min: :long, x_max: :long, y_max: :long)
+        define(:ListRec, head: :pointer, tail: :pointer)
+        define(:BitmapSize, height: :short, width: :short, size: :long, x_ppem: :long, y_ppem: :long)
+        define(:GlyphMetrics,
+          width: :long, height: :long,
+          hori_bearing_x: :long, hori_bearing_y: :long, hori_advance: :long,
+          vert_bearing_x: :long, vert_bearing_y: :long, vert_advance: :long)
+        define(:Bitmap,
+          rows: :uint, width: :uint, pitch: :int, buffer: :pointer,
+          num_grays: :ushort, pixel_mode: :uchar, palette_mode: :uchar, palette: :pointer)
+        define(:Outline,
+          n_contours: :ushort, n_points: :ushort, points: :pointer,
+          tags: :pointer, contours: :pointer, flags: :int)
+        define(:SizeMetrics,
+          x_ppem: :ushort, y_ppem: :ushort, x_scale: :long, y_scale: :long,
+          ascender: :long, descender: :long, height: :long, max_advance: :long)
+        define(:SizeRec,
+          face: :pointer, generic: Generic.by_value, metrics: SizeMetrics.by_value, internal: :pointer)
+        define(:FaceRec,
+          num_faces: :long, face_index: :long, face_flags: :long, style_flags: :long,
+          num_glyphs: :long, family_name: :pointer, style_name: :pointer,
+          num_fixed_sizes: :int, available_sizes: :pointer, num_charmaps: :int, charmaps: :pointer,
+          generic: Generic.by_value, bbox: BBox.by_value, units_per_em: :ushort,
+          ascender: :short, descender: :short, height: :short,
+          max_advance_width: :short, max_advance_height: :short,
+          underline_position: :short, underline_thickness: :short,
+          glyph: :pointer, size: :pointer, charmap: :pointer,
+          driver: :pointer, memory: :pointer, stream: :pointer,
+          sizes_list: ListRec.by_value, autohint: Generic.by_value,
+          extensions: :pointer, internal: :pointer)
+        define(:GlyphSlotRec,
+          library: :pointer, face: :pointer, next: :pointer, glyph_index: :uint,
+          generic: Generic.by_value, metrics: GlyphMetrics.by_value,
+          linear_hori_advance: :long, linear_vert_advance: :long, advance: Vector.by_value,
+          format: :uint, bitmap: Bitmap.by_value, bitmap_left: :int, bitmap_top: :int,
+          outline: Outline.by_value, num_subglyphs: :uint, subglyphs: :pointer,
+          control_data: :pointer, control_len: :long, lsb_delta: :long, rsb_delta: :long,
+          other: :pointer, internal: :pointer)
+      end
+    end
+
+    Structs.define_all
+
+    FT_Generic = Generic
+    FT_Vector = Vector
+    FT_BBox = BBox
+    FT_ListRec = ListRec
+    FT_Bitmap_Size = BitmapSize
+    FT_Glyph_Metrics = GlyphMetrics
+    FT_Bitmap = Bitmap
+    FT_Outline = Outline
+    FT_Size_Metrics = SizeMetrics
+    FT_SizeRec = SizeRec
+    FT_FaceRec = FaceRec
+    FT_GlyphSlotRec = GlyphSlotRec
+  end
+end

data/lib/freetype/native.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module FreeType
+  module Native
+    extend FFI::Library
+
+    library_override = ENV["FREETYPE_LIBRARY"]
+    library_override = nil if library_override&.empty?
+    candidates = [library_override, "freetype", "libfreetype.so.6", "libfreetype.6.dylib"].compact
+    ffi_lib candidates
+
+    FT_LOAD_DEFAULT = 0
+    FT_LOAD_NO_HINTING = 1 << 1
+    FT_LOAD_RENDER = 1 << 2
+    FT_LOAD_TARGET_LIGHT = 1 << 16
+    FT_LOAD_TARGET_MONO = 2 << 16
+
+    FT_RENDER_MODE_NORMAL = 0
+    FT_RENDER_MODE_LIGHT = 1
+    FT_RENDER_MODE_MONO = 2
+    FT_RENDER_MODE_SDF = 5
+
+    FT_PIXEL_MODE_NONE = 0
+    FT_PIXEL_MODE_MONO = 1
+    FT_PIXEL_MODE_GRAY = 2
+    FT_KERNING_DEFAULT = 0
+    FT_FACE_FLAG_SCALABLE = 1 << 0
+    FT_FACE_FLAG_KERNING = 1 << 6
+    FT_ENCODING_UNICODE = 0x756E6963
+
+    ERROR_NAMES = {
+      0x00 => :Ok, 0x01 => :Cannot_Open_Resource, 0x02 => :Unknown_File_Format,
+      0x03 => :Invalid_File_Format, 0x04 => :Invalid_Version, 0x05 => :Lower_Module_Version,
+      0x06 => :Invalid_Argument, 0x07 => :Unimplemented_Feature, 0x08 => :Invalid_Table,
+      0x09 => :Invalid_Offset, 0x0A => :Array_Too_Large, 0x0B => :Missing_Module,
+      0x0C => :Missing_Property, 0x10 => :Invalid_Glyph_Index, 0x11 => :Invalid_Character_Code,
+      0x12 => :Invalid_Glyph_Format, 0x13 => :Cannot_Render_Glyph, 0x14 => :Invalid_Outline,
+      0x15 => :Invalid_Composite, 0x16 => :Too_Many_Hints, 0x17 => :Invalid_Pixel_Size,
+      0x18 => :Invalid_SVG_Document, 0x20 => :Invalid_Handle, 0x21 => :Invalid_Library_Handle,
+      0x22 => :Invalid_Driver_Handle, 0x23 => :Invalid_Face_Handle, 0x24 => :Invalid_Size_Handle,
+      0x25 => :Invalid_Slot_Handle, 0x26 => :Invalid_CharMap_Handle, 0x27 => :Invalid_Cache_Handle,
+      0x28 => :Invalid_Stream_Handle, 0x30 => :Too_Many_Drivers, 0x31 => :Too_Many_Extensions,
+      0x40 => :Out_Of_Memory, 0x41 => :Unlisted_Object, 0x51 => :Cannot_Open_Stream,
+      0x52 => :Invalid_Stream_Seek, 0x53 => :Invalid_Stream_Skip, 0x54 => :Invalid_Stream_Read,
+      0x55 => :Invalid_Stream_Operation, 0x56 => :Invalid_Frame_Operation,
+      0x57 => :Nested_Frame_Access, 0x58 => :Invalid_Frame_Read, 0x60 => :Raster_Uninitialized,
+      0x61 => :Raster_Corrupted, 0x62 => :Raster_Overflow, 0x63 => :Raster_Negative_Height,
+      0x70 => :Too_Many_Caches, 0x80 => :Invalid_Opcode, 0x81 => :Too_Few_Arguments,
+      0x82 => :Stack_Overflow, 0x83 => :Code_Overflow, 0x84 => :Bad_Argument,
+      0x85 => :Divide_By_Zero, 0x86 => :Invalid_Reference, 0x87 => :Debug_OpCode,
+      0x88 => :ENDF_In_Exec_Stream, 0x89 => :Nested_DEFS, 0x8A => :Invalid_CodeRange,
+      0x8B => :Execution_Too_Long, 0x8C => :Too_Many_Function_Defs,
+      0x8D => :Too_Many_Instruction_Defs, 0x8E => :Table_Missing, 0x8F => :Horiz_Header_Missing,
+      0x90 => :Locations_Missing, 0x91 => :Name_Table_Missing, 0x92 => :CMap_Table_Missing,
+      0x93 => :Hmtx_Table_Missing, 0x94 => :Post_Table_Missing, 0x95 => :Invalid_Horiz_Metrics,
+      0x96 => :Invalid_CharMap_Format, 0x97 => :Invalid_PPem, 0x98 => :Invalid_Vert_Metrics,
+      0x99 => :Could_Not_Find_Context, 0x9A => :Invalid_Post_Table_Format,
+      0x9B => :Invalid_Post_Table, 0x9C => :DEF_In_Glyf_Bytecode, 0x9D => :Missing_Bitmap,
+      0x9E => :Missing_SVG_Hooks, 0xA0 => :Syntax_Error, 0xA1 => :Stack_Underflow,
+      0xA2 => :Ignore, 0xA3 => :No_Unicode_Glyph_Name, 0xA4 => :Glyph_Too_Big,
+      0xB0 => :Missing_Startfont_Field, 0xB1 => :Missing_Font_Field, 0xB2 => :Missing_Size_Field,
+      0xB3 => :Missing_Fontboundingbox_Field, 0xB4 => :Missing_Chars_Field,
+      0xB5 => :Missing_Startchar_Field, 0xB6 => :Missing_Encoding_Field,
+      0xB7 => :Missing_Bbx_Field, 0xB8 => :Bbx_Too_Big, 0xB9 => :Corrupted_Font_Header,
+      0xBA => :Corrupted_Font_Glyphs
+    }.freeze
+    ERROR_CODES = ERROR_NAMES.invert.freeze
+    FT_ERRORS = enum(
+      :ft_error,
+      ERROR_NAMES.flat_map { |code, name| [:"FT_Err_#{name}", code] }
+    )
+    ERROR_NAMES.each { |code, name| const_set(:"FT_Err_#{name}", code) }
+
+    require_relative "native/structs"
+
+    attach_function :FT_Init_FreeType, [:pointer], :int
+    attach_function :FT_Done_FreeType, [:pointer], :int
+    attach_function :FT_New_Face, %i[pointer string long pointer], :int
+    attach_function :FT_New_Memory_Face, %i[pointer pointer long long pointer], :int
+    attach_function :FT_Done_Face, [:pointer], :int
+    attach_function :FT_Set_Pixel_Sizes, %i[pointer uint uint], :int
+    attach_function :FT_Set_Char_Size, %i[pointer long long uint uint], :int
+    attach_function :FT_Get_Char_Index, %i[pointer ulong], :uint
+    attach_function :FT_Load_Glyph, %i[pointer uint int32], :int
+    attach_function :FT_Load_Char, %i[pointer ulong int32], :int
+    attach_function :FT_Render_Glyph, %i[pointer int], :int
+    attach_function :FT_Get_Kerning, %i[pointer uint uint uint pointer], :int
+    attach_function :FT_Select_Charmap, %i[pointer int], :int
+    attach_function :FT_Library_Version, %i[pointer pointer pointer pointer], :void
+    attach_function :FT_Property_Set, %i[pointer string string pointer], :int
+
+    module_function
+
+    def check!(code, operation = nil)
+      return if code.zero?
+
+      raise NativeError.new(code, operation: operation)
+    end
+  end
+end

data/lib/freetype/pool.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module FreeType
+  class Pool
+    def initialize
+      @mutex = Mutex.new
+      @states = {}
+      @closed = false
+    end
+
+    def self.open
+      pool = new
+      return pool unless block_given?
+
+      begin
+        yield pool
+      ensure
+        pool.close
+      end
+    end
+
+    def library
+      state.fetch(:library)
+    end
+
+    def face(source, face_index: 0)
+      current = state
+      key = source_key(source, face_index)
+      current.fetch(:faces)[key] ||= current.fetch(:library).face(source, face_index: face_index)
+    end
+
+    def with_face(source, face_index: 0)
+      yield face(source, face_index: face_index)
+    end
+
+    def clear
+      thread = Thread.current
+      current = @mutex.synchronize { @states.delete(thread) }
+      current&.fetch(:library)&.close
+      nil
+    end
+
+    def close
+      states = @mutex.synchronize do
+        return if @closed
+
+        @closed = true
+        previous = @states.values
+        @states = {}
+        previous
+      end
+      states.each { |current| current.fetch(:library).close }
+      nil
+    end
+
+    def closed?
+      @mutex.synchronize { @closed }
+    end
+
+    private
+
+    def state
+      @mutex.synchronize do
+        raise ClosedError, "pool is closed" if @closed
+
+        @states[Thread.current] ||= { library: Library.new, faces: {} }
+      end
+    end
+
+    def source_key(source, face_index)
+      path = source.respond_to?(:to_path) ? source.to_path : source
+      if path.is_a?(String) && File.file?(path)
+        [:path, File.expand_path(path), Integer(face_index)]
+      else
+        [:memory, source.object_id, Integer(face_index)]
+      end
+    end
+  end
+end