ecache

Documentation

Overview

The ecache subpackage defines the GlyphCacheHandler interface used within etxt, provides a default cache implementation and exposes a few more helper types to assist you if you want to implement your own.

Since glyph rasterization is usually an expensive CPU process, caches are a vital part of any real-time text rendering pipeline.

As far as practical advice goes, "how to determine the size of my cache" would be the main topic of discussion. Sadly, there's no good rule of thumb to say "set your cache size to half its peak memory usage" or similar. Cache sizes really depend on your use-case: sometimes you have only a couple fonts at a few fixed sizes and you want your cache to fit everything. Sometimes you determine your font sizes based on the current screen size and can absolutely not pretend to cache all the masks that the renderers may generate. The DefaultCache.PeakSize() function is a good tool to assist you, but you will have to figure out your requirements by yourself... or just set an arbitrary cache size like 16MB (16*1024*1024 bytes) and see how far does that get you.

Index

• func CacheEntryInstant() uint32
• func GlyphMaskByteSize(mask GlyphMask) uint32
• type CachedMaskEntry
  • func NewCachedMaskEntry(mask GlyphMask) (*CachedMaskEntry, uint32)
  • func (self *CachedMaskEntry) Hotness(instant uint32) uint32
  • func (self *CachedMaskEntry) IncreaseAccessCount()
• type DefaultCache
  • func NewDefaultCache(maxByteSize int) (*DefaultCache, error)
  • func (self *DefaultCache) ApproxByteSize() int
  • func (self *DefaultCache) GetMask(key [3]uint64) (GlyphMask, bool)
  • func (self *DefaultCache) NewHandler() *DefaultCacheHandler
  • func (self *DefaultCache) PassMask(key [3]uint64, mask GlyphMask)
  • func (self *DefaultCache) PeakSize() int
• type DefaultCacheHandler
  • func (self *DefaultCacheHandler) ApproxCacheByteSize() int
  • func (self *DefaultCacheHandler) GetMask(index GlyphIndex) (GlyphMask, bool)
  • func (self *DefaultCacheHandler) NotifyFontChange(font *Font)
  • func (self *DefaultCacheHandler) NotifyFractChange(fract fixed.Point26_6)
  • func (self *DefaultCacheHandler) NotifyRasterizerChange(rasterizer emask.Rasterizer)
  • func (self *DefaultCacheHandler) NotifySizeChange(size fixed.Int26_6)
  • func (self *DefaultCacheHandler) PassMask(index GlyphIndex, mask GlyphMask)
  • func (self *DefaultCacheHandler) PeakCacheSize() int
• type Font
• type GlyphCacheHandler
• type GlyphIndex
• type GlyphMask

Functions

func CacheEntryInstant

func CacheEntryInstant() uint32

A time instant related to the system's monotonic nano time, but with some arbitrary downscaling applied (close to converting nanoseconds to hundredth's of seconds).

func GlyphMaskByteSize

func GlyphMaskByteSize(mask GlyphMask) uint32

Returns an approximation of the GlyphMask's size in bytes.

With Ebitengine, the exact amount of mipmaps and helper fields is not known, so the values may not be very representative of actual memory usage. With gtxt, the returned values are precise.

Types

type CachedMaskEntry

type CachedMaskEntry struct {
	Mask            GlyphMask // Read-only.
	ByteSize        uint32    // Read-only.
	CreationInstant uint32    // see CacheEntryInstant. Read-only.
	// contains filtered or unexported fields
}

A cached mask with additional information to estimate how much the entry is being used. Cache implementers may use this type to make their life easier.

func NewCachedMaskEntry

func NewCachedMaskEntry(mask GlyphMask) (*CachedMaskEntry, uint32)

Creates a new cached mask entry for the given GlyphMask.

func (*CachedMaskEntry) Hotness

func (self *CachedMaskEntry) Hotness(instant uint32) uint32

A measure of "bytes accessed per time". Coldest entries (smallest values) are candidates for eviction. Concurrent-safe.

func (*CachedMaskEntry) IncreaseAccessCount

func (self *CachedMaskEntry) IncreaseAccessCount()

Must be called after accessing an entry in order to keep the Hotness() heuristic making sense. Concurrent-safe.

type DefaultCache

type DefaultCache struct {
	// contains filtered or unexported fields
}

The default etxt cache. It is concurrent-safe (though not optimized or expected to be used under heavily concurrent scenarios), it has memory bounds and uses random sampling for evicting entries.

func NewDefaultCache

func NewDefaultCache(maxByteSize int) (*DefaultCache, error)

Creates a new cache bounded by the given size.

The given size must be at least 1024. If you don't want a constrained cache, call with (1 << 30) (1GB) or similar.

func (*DefaultCache) ApproxByteSize

func (self *DefaultCache) ApproxByteSize() int

Returns an approximation of the number of bytes taken by the glyph masks currently stored in the cache.

func (*DefaultCache) GetMask

func (self *DefaultCache) GetMask(key [3]uint64) (GlyphMask, bool)

Gets the mask associated to the given key.

func (*DefaultCache) NewHandler

func (self *DefaultCache) NewHandler() *DefaultCacheHandler

Returns a new cache handler for the current cache. While DefaultCache is concurrent-safe, handlers can only be used non-concurrently. One can create multiple handlers for the same cache to be used with different renderers.

func (*DefaultCache) PassMask

func (self *DefaultCache) PassMask(key [3]uint64, mask GlyphMask)

Stores the given mask with the given key.

func (*DefaultCache) PeakSize

func (self *DefaultCache) PeakSize() int

Returns an approximation of the maximum amount of bytes that the cache has been filled with at any point of its life.

This method can be useful to determine the actual usage of a cache within your application and set its capacity to a reasonable value.

type DefaultCacheHandler

type DefaultCacheHandler struct {
	// contains filtered or unexported fields
}

A default implementation of GlyphCacheHandler.

func (*DefaultCacheHandler) ApproxCacheByteSize

func (self *DefaultCacheHandler) ApproxCacheByteSize() int

Provides access to DefaultCache.ApproxByteSize().

func (*DefaultCacheHandler) GetMask

func (self *DefaultCacheHandler) GetMask(index GlyphIndex) (GlyphMask, bool)

Implements GlyphCacheHandler.GetMask(...)

func (*DefaultCacheHandler) NotifyFontChange

func (self *DefaultCacheHandler) NotifyFontChange(font *Font)

Implements GlyphCacheHandler.NotifyFontChange(...)

func (*DefaultCacheHandler) NotifyFractChange

func (self *DefaultCacheHandler) NotifyFractChange(fract fixed.Point26_6)

Implements GlyphCacheHandler.NotifyFractChange(...)

func (*DefaultCacheHandler) NotifyRasterizerChange

func (self *DefaultCacheHandler) NotifyRasterizerChange(rasterizer emask.Rasterizer)

Implements GlyphCacheHandler.NotifyRasterizerChange(...)

func (*DefaultCacheHandler) NotifySizeChange

func (self *DefaultCacheHandler) NotifySizeChange(size fixed.Int26_6)

Implements GlyphCacheHandler.NotifySizeChange(...)

func (*DefaultCacheHandler) PassMask

func (self *DefaultCacheHandler) PassMask(index GlyphIndex, mask GlyphMask)

Implements GlyphCacheHandler.PassMask(...)

func (*DefaultCacheHandler) PeakCacheSize

func (self *DefaultCacheHandler) PeakCacheSize() int

Provides access to DefaultCache.PeakSize().

type Font

type Font = sfnt.Font

Same as etxt.Font.

type GlyphCacheHandler

type GlyphCacheHandler interface {

	// Notifies that the font in use has changed.
	NotifyFontChange(*Font)

	// Notifies that the text size (in pixels) has changed.
	NotifySizeChange(fixed.Int26_6)

	// Notifies that the rasterizer has changed. Typically, the
	// rasterizer's CacheSignature() will be used to tell them apart.
	NotifyRasterizerChange(emask.Rasterizer) // called on config changes too

	// Notifies that the fractional drawing position has changed.
	// Only the _6 decimal bits must be considered.
	NotifyFractChange(fixed.Point26_6)

	// Gets the mask image for the given glyph index and current configuration.
	// The bool indicates whether the mask has been found (as it may be nil).
	GetMask(GlyphIndex) (GlyphMask, bool)

	// Passes a mask image for the given glyph index and current
	// configuration to the underlying cache. PassMask should only
	// be called after GetMask() fails.
	//
	// Given a specific configuration, the contents of the mask image
	// must always be consistent. This implies that passed masks may be
	// ignored if a mask is already cached under that configuration, as
	// it will be considered superfluous. In other words: passing different
	// masks for the same configuration may cause inconsistent results.
	PassMask(GlyphIndex, GlyphMask)
}

A GlyphCacheHandler acts as an intermediator between a glyph cache and another object, typically a Renderer, to give the later a clear target interface to conform to while abstracting the details of an underlying cache, which might be finickier to deal with directly in a performant way.

GlyphCacheHandler's can't be used concurrently unless the concrete implementation explicitly says otherwise.

type GlyphIndex

type GlyphIndex = sfnt.GlyphIndex

Same as etxt.GlyphIndex.

type GlyphMask

type GlyphMask = *ebiten.Image

Same as etxt.GlyphMask.