class SFML::Font
A typeface loaded from a TTF/OTF file.
font = SFML::Font.default # bundled DejaVu Sans font = SFML::Font.load(“/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf”) font = SFML::Font.find(“DejaVuSans”) # search common locations
Constants
- DEFAULT_PATH
-
Path to the font ruby-sfml ships with: DejaVu Sans (Bitstream Vera license, redistributable). See lib/sfml/assets/fonts/DejaVuSans.LICENSE.txt.
- SEARCH_PATHS
Public Class Methods
Source
# File lib/sfml/graphics/font.rb, line 71 def self.default @default ||= load(DEFAULT_PATH) end
The default font bundled with ruby-sfml. Use this when you don’t care which typeface as long as you can render text — examples, debug HUDs, prototypes. Memoized so subsequent calls return the same Font instance.
Source
# File lib/sfml/graphics/font.rb, line 78 def self.find(name) target = name.to_s.downcase.sub(/\.(ttf|otf)\z/, "") SEARCH_PATHS.each do |dir| next unless File.directory?(dir) match = Dir.glob(File.join(dir, "**", "*.{ttf,otf}")).find do |path| File.basename(path).downcase.sub(/\.(ttf|otf)\z/, "") == target end return load(match) if match end nil end
Look up a font on disk by basename (with or without extension). Useful for examples that should “just run” — production code should ship its own font files. Returns nil if nothing is found.
Source
# File lib/sfml/graphics/font.rb, line 35 def self.from_memory(bytes) raise ArgumentError, "expected a String, got #{bytes.class}" unless bytes.is_a?(String) buf = FFI::MemoryPointer.new(:uint8, bytes.bytesize) buf.write_bytes(bytes) ptr = C::Graphics.sfFont_createFromMemory(buf, bytes.bytesize) raise LoadError, "sfFont_createFromMemory returned NULL" if ptr.null? font = allocate font.send(:_take_ownership, ptr) # CSFML doesn't copy the font bytes — keep them pinned so the # GC doesn't free them while CSFML still references the buffer. font.instance_variable_set(:@_memory_pin, buf) font end
Load a font from a Ruby String of bytes — useful when the font lives inside a data: URL, an embedded asset, or a network response. The bytes are copied by SFML before this call returns; the caller’s String can be GC’d safely.
Source
# File lib/sfml/graphics/font.rb, line 54 def self.from_stream(io) stream = SFML::InputStream.new(io) ptr = C::Graphics.sfFont_createFromStream(stream.to_ptr) raise LoadError, "sfFont_createFromStream returned NULL" if ptr.null? font = allocate font.send(:_take_ownership, ptr) # CSFML reads the font lazily from this stream — keep it pinned. font.instance_variable_set(:@_stream_pin, stream) font.instance_variable_set(:@_io_pin, io) font end
Load a TTF/OTF from any Ruby IO-like object — file, in-memory, network-backed reader. Keep the IO open until the Font is no longer in use; CSFML reads glyphs lazily.
Source
# File lib/sfml/graphics/font.rb, line 22 def self.load(path) ptr = C::Graphics.sfFont_createFromFile(path.to_s) raise LoadError, "Could not load font from #{path.inspect}" if ptr.null? font = allocate font.send(:_take_ownership, ptr) font end
Returns the self.
Public Instance Methods
Source
# File lib/sfml/graphics/font.rb, line 165 def _take_ownership(ptr) @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfFont_destroy)) end
Source
# File lib/sfml/graphics/font.rb, line 151 def dup ptr = C::Graphics.sfFont_copy(@handle) raise GraphicsError, "sfFont_copy returned NULL" if ptr.null? font = self.class.allocate font.send(:_take_ownership, ptr) font end
Deep copy. The returned font has its own atlas state; mutate one without affecting the other.
Source
# File lib/sfml/graphics/font.rb, line 101 def family info = C::Graphics.sfFont_getInfo(@handle) info[:family].null? ? nil : info[:family].read_string end
Human-readable family name (e.g. “DejaVu Sans”). Read once via sfFont_getInfo — CSFML returns a static C string from FreeType so we copy out into a Ruby String.
Source
# File lib/sfml/graphics/font.rb, line 108 def has_glyph?(codepoint) cp = codepoint.is_a?(String) ? codepoint.codepoints.first : Integer(codepoint) C::Graphics.sfFont_hasGlyph(@handle, cp || 0) end
true if the font has a glyph for the given Unicode codepoint (Integer) or single-character String.
Source
# File lib/sfml/graphics/font.rb, line 116 def kerning(first, second, character_size:, bold: false) a = first.is_a?(String) ? first.codepoints.first : Integer(first) b = second.is_a?(String) ? second.codepoints.first : Integer(second) fn = bold ? :sfFont_getBoldKerning : :sfFont_getKerning C::Graphics.send(fn, @handle, a || 0, b || 0, Integer(character_size)) end
Horizontal kerning offset between two adjacent glyphs at the given character size. Float, in pixels (often negative — the kern pulls the second glyph leftward).
Source
# File lib/sfml/graphics/font.rb, line 125 def line_spacing(character_size) C::Graphics.sfFont_getLineSpacing(@handle, Integer(character_size)) end
Distance between two consecutive baselines for the given character size. Float, in pixels.
Source
# File lib/sfml/graphics/font.rb, line 94 def smooth=(value) C::Graphics.sfFont_setSmooth(@handle, !!value) end
Set the smooth.
Source
# File lib/sfml/graphics/font.rb, line 91 def smooth? = C::Graphics.sfFont_isSmooth(@handle) # Set the smooth. def smooth=(value) C::Graphics.sfFont_setSmooth(@handle, !!value) end # Human-readable family name (e.g. "DejaVu Sans"). Read once # via `sfFont_getInfo` — CSFML returns a static C string from # FreeType so we copy out into a Ruby String. def family info = C::Graphics.sfFont_getInfo(@handle) info[:family].null? ? nil : info[:family].read_string end # `true` if the font has a glyph for the given Unicode codepoint # (Integer) or single-character String. def has_glyph?(codepoint) cp = codepoint.is_a?(String) ? codepoint.codepoints.first : Integer(codepoint) C::Graphics.sfFont_hasGlyph(@handle, cp || 0) end # Horizontal kerning offset between two adjacent glyphs at the # given character size. Float, in pixels (often negative — the # kern pulls the second glyph leftward). def kerning(first, second, character_size:, bold: false) a = first.is_a?(String) ? first.codepoints.first : Integer(first) b = second.is_a?(String) ? second.codepoints.first : Integer(second) fn = bold ? :sfFont_getBoldKerning : :sfFont_getKerning C::Graphics.send(fn, @handle, a || 0, b || 0, Integer(character_size)) end # Distance between two consecutive baselines for the given # character size. Float, in pixels. def line_spacing(character_size) C::Graphics.sfFont_getLineSpacing(@handle, Integer(character_size)) end # Vertical offset of the underline from the baseline (positive # values point downward). Float, in pixels. def underline_position(character_size) C::Graphics.sfFont_getUnderlinePosition(@handle, Integer(character_size)) end # Thickness of the underline stroke. Float, in pixels. def underline_thickness(character_size) C::Graphics.sfFont_getUnderlineThickness(@handle, Integer(character_size)) end # The internal glyph atlas as a `SFML::Texture` (read-only — we # don't own the pointer; CSFML keeps it alive as long as the # font does). def texture(character_size) ptr = C::Graphics.sfFont_getTexture(@handle, Integer(character_size)) return nil if ptr.null? Texture.send(:_borrow, ptr) end # Deep copy. The returned font has its own atlas state; mutate # one without affecting the other. def dup ptr = C::Graphics.sfFont_copy(@handle) raise GraphicsError, "sfFont_copy returned NULL" if ptr.null? font = self.class.allocate font.send(:_take_ownership, ptr) font end alias clone dup attr_reader :handle # :nodoc: private def _take_ownership(ptr) @handle = FFI::AutoPointer.new(ptr, C::Graphics.method(:sfFont_destroy)) end end
true if smooth.
Source
# File lib/sfml/graphics/font.rb, line 143 def texture(character_size) ptr = C::Graphics.sfFont_getTexture(@handle, Integer(character_size)) return nil if ptr.null? Texture.send(:_borrow, ptr) end
The internal glyph atlas as a SFML::Texture (read-only — we don’t own the pointer; CSFML keeps it alive as long as the font does).
Source
# File lib/sfml/graphics/font.rb, line 131 def underline_position(character_size) C::Graphics.sfFont_getUnderlinePosition(@handle, Integer(character_size)) end
Vertical offset of the underline from the baseline (positive values point downward). Float, in pixels.
Source
# File lib/sfml/graphics/font.rb, line 136 def underline_thickness(character_size) C::Graphics.sfFont_getUnderlineThickness(@handle, Integer(character_size)) end
Thickness of the underline stroke. Float, in pixels.