################
Displaying Texts
################


This simple tutorial focuses on creating a few texts. As illustrated here: :doc:`/book/subjects/bk_sgo/bk_sg_text_shapes` in the section **Choosing the Type of Text to Display**, there are several types of texts that can be displayed by HOOPS Luminate. The windows version of the tutorial will show all 4 types of texts, while the Linux and MacOS versions of the tutorial will only show ``RED::FNT_TEXTURE`` texts.

First, the ``RED::FNT_BITMAP`` matches bitmap fonts as they can be directly created by Windows using the Windows font mapper. Anyone familiar with the CreateFontIndirect call will recognize the API methods of the ``RED::IFont`` class as they describe more or less the LOGFONT structure used to create the font. The ``RED::FNT_TRIANGLE`` and ``RED::FNT_LINE`` are the OpenGL transcription of Windows fonts using wglUseFontOutlines. Again, the whole HOOPS Luminate font API should look familiar then.

.. figure:: wf_displaying_texts_final_view.png
    :align: center
    
    **The final view of the tutorial that manipulates 2D texts.**


***************************
Creation and Setup of Texts
***************************

The tutorial more or less illustrates the :doc:`/tasks/ta_ca/ta_ca_scenegraph/tk_creating_a_font` and :doc:`/tasks/ta_ca/ta_ca_scenegraph/tk_creating_a_text_shape` tasks, so we won't copy the code here again. That said, there are specific setup calls that should be considered for each font type:

    * The quality of the generated font will be based on the ``RED::IFont::SetChordalDeviation`` method. The value here rules the number of triangles that will be created for the display of the font. This has an influence over the ``RED::FNT_TRIANGLE`` and ``RED::FNT_LINE`` types of fonts.
    * For a ``RED::FNT_TEXTURE`` type of font, the quality of the generated font will be based on the ``RED::IFont::SetGlyphTextureSize`` call. This method rules the size of the bitmap used for each character glyph.


*********************************
Playing with Attachment Positions
*********************************

As indicated in the ``RED::TEXT_ATTACH_POS`` enumeration, we have several attachment positions for strings. The tutorial uses 4 of them, one different for each string displayed. Among the text attachment position, the ``RED::TAP_BASELINE_LEFT``, or all baseline attachments are really useful as they ignore characters descending areas.


******************
Unicode Characters
******************

HOOPS Luminate uses the ``RED::String`` class for string display. The ``RED::String`` is a UTF-8 encoded string that supports Unicode characters and that stores ASCII standard characters as plain ASCII strings (hence the interest of UTF-8 over UCS-2 based strings). Consequently, HOOPS Luminate can display any character assuming the proper charset has been selected in the font using RED::IFont::SetCharset.


****************************
Rotating and Scaling Strings
****************************

Each string in a ``RED::ITextShape`` has an independent positioning information. Strings are added using ``RED::ITextShape::AddString`` for basic placement and ``RED:ITextShape::AddRotatedString`` or ``RED::ITextShape::AddRotatedAndScaledString`` may also be considered.

