@c -*-texinfo-*-
@node Alpha Textures, Texture Mapping, Shaders, Materials
@subsection Alpha and Keycolor in Textures
@cindex alpha
@cindex alpha textures
@cindex keycolor

Crystal Space supports the alpha channel that can be present in some image
files (like @sc{png} and @sc{tga}).

It is important to realize that when you use alpha on an object you must
sort the object back to front. That basically means you'll most likely have
to use the @samp{alpha} render priority (@pxref{HOWTO Render Priorities}) and
also @samp{ztest} for the Z-buffer usage. Also in some cases you may need
to set the @samp{back2front} flag if the object is a genmesh
(@pxref{MeshObject Genmesh}).

It is often hard to get things correct with such a setup so in many cases
it is preferable to use a method named @dfn{binary alpha}. This means that
a pixel is either treated as @dfn{fully opaque} or @dfn{fully transparent} -
the former for alpha values greater than 50%, the latter for alpha values
lower than 50%. In practice, it is probably desireable to only use 0% and 
100% transparency values in the alpha channel. Also, the transparent area(s)
should be filled with a color that is similar to its adjacent opaque pixels, 
as, due texture filtering, this color will slightly bleed into the neighboring
opaque pixels. Choosing an approriate color makes this bleeding non-obvious.

The easiest way to activate binary alpha is to mark the texture as follows in 
your world file:

@example
<texture name="transparent">
    <file>mytexture.png</file>
    <alpha><binary/></alpha>
</texture>
@end example

If you do this then this texture can be used on objects as any other texture.
So the object can simply use @samp{object} render priority and @samp{zuse}
Z-buffer mode.

An alternative way to enable binary alpha is by using a @dfn{keycolor} for the
texture; that is, all pixels of the specified color (in the example magenta)
will be rendered transparent.

@example
<texture name="transparent">
    <file>mytexture.png</file>
    <transparent r="1" g="0" b="1" />
</texture>
@end example

However, using this technique is discouraged as it is less performant than the 
using binary alpha as described above; specifically, when loading a texture
with a keycolor, CrystalSpace will scan the image for pixels of that color and
set their alpha value to 0. Internally, binary alpha and keycolor work in the 
same way (transparency of a pixel is based on whether the alpha value is 
above or below 50%), however, keycolored textures come with a load-time 
performance penalty due to the required processing step.
