============
Text Shaders
============

Ren'Py contains a text shader system that makes it possible to control how
Ren'Py displays text. When enabled, the text shader system uses :doc:`model`
to render two triangles for each unicode character. Shader parts, either specified
from the creator or generated by Ren'Py, are applied to the model, and
can change how text is displayed.

The text shader documentation is in thee parts:

#. How to use text shaders
#. What text shaders are included in Ren'Py
#. How to create new text shaders

Note that while text shaders are intended to be easily used by game creators,
making your own text shaders requires some knowledge of GLSL, the OpenGL Shading
Language, as well as :doc:`model`, and hence is more advanced than most Ren'Py
features.


Using Text Shaders
===================

There are three ways to use text shaders:

**Default Text Shader** The first is to set the default
text shader, using :var:`config.default_textshader`. ::

    define config.default_textshader = "wave:10"

When set this way, the text shader will be used for all text that does not
specify a text shader. It will also be combined with text shaders that
include the default text shader, which is most of them.

Generally, the default textshader should take care of slow text and
shouldn't add more complicated effects.

**Styles** The second way to use text shaders is to set the :propref:`textshader`
style property, either directly or in one of the many ways provided by Ren'Py to
set styles. ::

    style default:
        textshader "sunrise"

    define kitt = Character("KITT", what_textshader="cylon:color=#ff0000|time=2.0")

    screen purchase():
        textbutton "Buy Now":
            textshader "pulse:1.0" action iap.Purchase("dlc")

**Text Tags** The third way to use text shaders is to use the :tt:`appropriate text tag <shader>`
to change the look of a portion of text. ::

    "What's this? A letter from {shader=upside_down}Australia{/shader}?"


Specifying Text Shaders
-----------------------

Text shaders are specified as strings like::

    "wave"
    "jitter:1.0, 3.0"
    "pulse:pulse_zoom=1.5:pulse_time=1.0"

The first part of the string, before the first colon, is the name of the text shader.
The rest of the string is a series of uniforms that are passed to the shader,
separated by colons. (Uniforms are parameters that are passed to the shader,
that can be used to control how the shader works.)

Uniforms can be specified by name follwed by =, or the name can be
omitted to set each uniform in order. (Omitting the name is not supported in Ren'Py 7.) While
internally all uniforms begin with u\_, the u\_ can be omitted for brevity.

The value of a uniform can be:

* Between 1 and 4 numbers, separated by commas. These can be used with the
  the float, vec2, vec3, or vec4 types.
* A color, beginning with #. (For example, #f00 or #ff0000 for red.) This
  creates a a vec4 corresponding to that color. This color will be
  premultiplied by its alpha channel.

Uniform values can't be expressions or access variables, though it is
possible to use text interpolation to create a string that can be
evaluated as a textshader tag or its parameter.


Finally, text shaders can be combined with each other using the | operator.
For example::

    "jitter:1.0, 3.0|pulse:pulse_zoom=1.5:pulse_time=1.0"

This will apply both the wave and colors shaders to the text. This only works
if the shaders are compatible with each other, and do not use the same
uniforms (or use the uniform in a way that is compatible with each other, in
which case it takes the value from the last shader in the list).

Unless a textshader has `include_default` set to False, the default textshader
will be combined with the textshader specified in the style or tag.
