Getting and using images of spans


Spans (see Alph) are used in Fenfire as the basis of text- and image-based media. An important primitive in the Fenfire platform is showing the image contained in a span. However, to do this efficiently and in accordance with the focus+context principle, we need to load and unload levels of detail of images flexibly.

Libvob provides the basic architectural features for this: (XXX link to memorypool design) competing degradable allocations from a pool of memory, and mipzip files and classes that allow easy loading/unloading of mipmap levels.

What is left for Fenfire to provide is the infrastructure to go from spans to vobs and as easily as possible from the vobs to the usage information to be given to the memory pool.


There are several details which will make life difficult:

User-visible interface

The interfaces SpanImageFactory and SpanImageVob in the package org.fenfire.spanimages are the

SpanImageFactory SpanImageVob org.nongnu.libvob.Vob org.nongnu.alph.ImageSpan SpanImageFactory SpanImageVob org.nongnu.libvob.Vob org.nongnu.alph.ImageSpan fenfirespansint1

Apart from the option of creating different SpanImageFactory objects with different properties for e.g. page backgrounds, this is all the other classes need to see.


The implementations are in (once an AWT implementation is made, it will be in the package org.fenfire.spanimages.fuzzybear).

ImageSpan vs PageImageSpan

It is reasonable to expect different treatment of ImageSpan and PageImageSpan objects: for PageImageSpan objects, we will often want libpaper backgrounds and text-enhancing transformations.

SpanImageFactory MuxSpanImageFactory SpanImageFactory MuxSpanImageFactory fenfirespansint2

The MuxSpanImageFactory object delegates calls to one factory for PageImageSpan objects and to the other for plain ImageSpan objects.

Caching of SpanImageVob objects

The caching is taken care by another step added to the chain:

SpanImageFactory CachingSpanImageFactory SpanImageFactory CachingSpanImageFactory fenfirespans_caching

The CachingSpanImageFactory will first check its cache and only if it does not find the object cached will it recreate it.

Repository of loaded textures

The twin classes PageScrollBlockImager and ImageScrollBlockImager take care of mapping spans to OpenGL textures (mipzips).

ScrollBlockImager PageScrollBlockImager ImageScrollBlockImager SingleImage ScrollBlockImager PageScrollBlockImager ImageScrollBlockImager SingleImage fenfirespans_sbimg

An important architectural feature is that the classes are not static: this allows us to, e.g, plug in filters for the images of PageImageSpan.

The Single Image class

The class used by the repositories to represent the single images is SingleImage.

SingleImage SingleImage fenfirespans_sbimg_single

Mapping Images to Paper objects

The libPaper paper abstraction is useful for rendering sections of the images, with various settings. The input should be the TexGen matrix for the paper texture, and the GL texture object.

We may want to change this interface to include the scale of the characters on the paper at some point to allow better text enhancement.

PaperMaker SingleImage PaperMaker SingleImage fenfirespans_paper

Statistics accumulation and memory pool handling

Now we come to the raison d'etre of this architecture: centralized handling of the feedback from vobscene rendering. The TexAccum class in Libvob is able to accumulate the approximate number of pixels rendered at each mipmap level of each texture. This is collected by the SingleImage .

Because the MemoryPartitioner approach is a bit hard for us to interface with here (the quality - calling time stuff is not optimal for us) we have our own partitioner.

The PoolManager keeps a set of active textures. PoolManager PoolManager fenfirespans_texaccum

The final piece: the default implementation of SpanImageFactory

The class DefaultSpanImageFactory uses the above bits to implement the SpanImageFactory interface.

The only task it needs to do is to itself is to create the texgen matrix from the dimensions of the actual span versus the whole page.

SpanImageFactory DefaultSpanImageFactory ScrollBlockImager PoolManager PaperMaker SpanImageFactory DefaultSpanImageFactory ScrollBlockImager PoolManager PaperMaker fenfirespans_imgfactoryimpl