GLART week 8: Text
Assigment:
        Add text to any of the previous homework assignments.

Reading:
        Redbook pages 255-277  "Chapter 7: Display Lists"

Examples:
        GLART_8_text.java - flat text drawn over a scene
        GLART_8_textInSpace.java - text drawn in a 3D scene

        Requires images/font_tahoma.png

        Also see demo/DemoText.java and the jocode/JOFont.java
        to generate text using Java's Font capabilities.

Resources:

        Bitmap Font Builder -- creates texture images of character sets


NOTES:
=================================================================

OpenGL does not have any font or text capabilities built-in, but there are
several ways to create text, including building geometry from font shapes,
or drawing images of letters.  This second method is simple and works well
in most situations so we'll explore it here.

The idea is to draw an image of a letter textured onto a quad.  That's not so
complex by itself, but the problem becomes more substantial when you consider
that there are 26 letters in the alphabet, plus upper and lower case, and then
there are numbers, punctuation, etc.  Fortunately with some clever use of
texture coordinates and display lists, we can create a character set and draw
any text string we want with minimal effort.

JOApp contains a print(String) function that will render a text string by
texturing images of characters onto quads. There are several steps that
happen for this function to work.

First we'll need a texture image (font_tahoma.png) that contains a full
character set arranged in order by ascii value.

The JOApp.buildFont() function creates a set of quads, each textured with one
character from the character set image.  The textured quads are rendered
into a set of display lists, so that we can later draw any character
just by calling its display list.

The JOApp.print() function draws text by matching each character in a text string
with the correct display list, then running callList() to draw that character.
print() calls setOrthoOn() to set the projection mode to ortho, and disables
the depth test so text always draws on top of other geometry.

We don't need any new functions to use text in OpenGL, but there are some
settings that affect how text will appear:

     texture - be sure to glEnable(GL_TEXTURE_2D)

     light   - disable lighting (glDisable(GL_LIGHTING)), to insure that
               the text color is even across the screen.  With lighting
               on, some or all of the text may appear shadowed.

     blend   - enable blending so the background of the text will be transparent.
               glEnable(GL_BLEND)
               glBlendFunc(GL11.GL_SRC_ALPHA, GL11.GL_ONE_MINUS_SRC_ALPHA)

     ortho   - set the projection matrix to an orthoganal projection to make it
               easy to place the text flat on the screen (glOrtho())

     depth   - disable the depth test (glDisable(GL_DEPTH_TEST)) before
               drawing text to insure that the text is drawn on top of the
               rendered scene.

     pushAttrib - The glPushAttrib() function is a convenient way to save the
               current OpenGL settings. Subsequent code can change settings (such as
               enabling/disabling, setting lights, textures, materials, etc.) then
               can call glPopAttrib() to return to the previous settings.  Call
               gl.glPushAttrib(GL.GL_ALL_ATTRIB_BITS) to save all OpenGL
               settings, or you can preserve specific settings, for example just
               those affecting light and texture:
               glPushAttrib(GL.GL_TEXTURE_BIT | GL.GL_LIGHTING_BIT)


The JOApp.print() function calls these settings for you, but if you want to
work with text in some other customized situation you can use the print()
function as a starting point.