[vtk-developers] New unified text mapper

[Sebastien BARRE]

Hi

(all dashboard maintainers, please update your VTKData)

In an attempt to solve different problems and unify more platforms, a new 
text mapper is now in use:
	vtkOpenGLFreeTypeTextMapper

- It replaces the half-dozen platform-dependent text mappers that were used 
until now 
(http://public.kitware.com/VTK/doc/nightly/html/classvtkTextMapper.html).

- It renders text in the same way on all platforms.

- It honors the AntiAliasing ivar in vtkTextProperty, providing either full 
RGBA anti-aliased text (the default) or the good old binary jaggy text we 
are used to.

- It uses pure OpenGL calls and does not rely on any wgl*() or glX*() API 
(i.e. it should be able to render text offscreen or through Chromium).

- It allows developpers to create a unique baseline image for any 
text-based test (as I speak, more than 60 images have been removed from the 
CVS).

Issues:
======
- Expect some text tests to fail anyway while some last-minute issues are 
fixed (I have the feeling  that sub-pixels pb or floating point rounding 
error will show up).

- If you encounter critical problems, just set VTK_USE_FREETYPE to OFF to 
use the old text mappers.

Technical notes:
==============
- The Freetype library (http://www.freetype.org) in Utilities/freetype 
provides the font rendering engine.

- The FTGL library (thanks to Henry Maddocks) in Utilities/ftgl provides 
the glue between the raster engine (Freetype) and OpenGL. It has been 
heavily patched/optimized/rebugged by myself.

- A set of fonts has been contributed by URW, a German company which 
already contributed fonts to GNU Ghostscript some time ago. Additional 
fonts were borrowed from free fonts packaged in XFree86. All of them are 
embedded in VTK at compile-time (see Rendering/fonts).

Performances:
============
- A lot of issues have been addressed in that area and I think that no real 
performance hint should be expected now. I've performed various tests on 
Windows and Linux boxes:
       1) The old text mappers used to rely on platform specific calls 
(wgl*() or glX*()) to create an OpenGL display list based on fonts 
available on the given platform/server/client (as a side effect, text 
objects on X platforms were not fully scalable, this is not the case 
anymore). These display lists were basically sets of glBitmap() calls (i.e. 
binary images).
       2) The new text mapper supports full anti-aliasing through 
glPixmap(). In that case, it usually performs -5% to +5% better, depending 
on the performance of your graphics board compared to glBitmap().
      3) If anti-aliasing is off (see below), it uses glBitmap() and 
performs as well or better than the previous mappers.
      4) If you are using a vtkScalarBarActor, expect the new text mapper 
to provide 100% speedup in some cases. This is a side-effect of the caching 
method that was used in all old text mappers: if any text mapper was 
destroyed, the cache was emptied (since the scalar bar actor re-creates its 
internal text mapper each time it renders, this was hitting the perfs).

- Note that text anti-aliasing is either achieved by setting the 
AntiAliasing ivar in the relevant vtkTextProperty (default is ON), or at a 
global level by invoking vtkTextProperty::SetGlobalAntiAliasing. The 'L' 
key can be used in ary renderwindow to switch between the 3 different 
global anti-aliasing mode.
http://public.kitware.com/VTK/doc/nightly/html/classvtkTextProperty.html

Demo:
======
- I would suggest the Examples\Annotation\DispAllFonts.tcl and 
Rendering\Testing\Tcl\TestFreetypeTextMapper*.tcl scripts to have a look at 
the new mapper and the new fonts.

- The following usual tests might also be worth checking:
	Examples\Annotation\*.tcl
	Hybrid\Testing\Tcl\TestCaptionActor.tcl
	Hybrid\Testing\Tcl\cubeAxes.tcl
	Hybrid\Testing\Tcl\xyPlot.tcl
	Hybrid\Testing\Tcl\xyPlot2.tcl
	Hybrid\Testing\Tcl\xyPlot3.tcl
	Hybrid\Testing\Tcl\xyPlot4.tcl
	Rendering\Testing\Tcl\ScalarBar.tcl
	Rendering\Testing\Tcl\TestParallelCoordinates.tcl
	Rendering\Testing\Tcl\TestTiling.tcl
	Rendering\Testing\Tcl\labeledContours.tcl
	Rendering\Testing\Tcl\labeledMesh.tcl
	Rendering\Testing\Tcl\multiLineText.tcl

Any feedback is welcome :)

--
Sebastien Barre