# A Billboard Example using an Alpha Mask Texture

The purpose of this tutorial is to create a billboard using alpha masking transparency. In a first section, we will describe how to build a simple vertical axis rotation billboard using HOOPS Luminate. Then a diffuse texture and an alpha mask will be applied to it.

## Building the Billboard

A billboard is a simple 2D quad simulating a 3D object. Its principle is to always face up the camera, so that it gives the illusion to be in 3D. They are generally placed quite far of the camera and allow to lighten the scene complexity.

The first step of the tutorial is to create our plane:

```// Creating the plane:
RED::Object* quad = RED::Factory::CreateInstance( CID_REDMeshShape );

RC_TEST( iquad->Quad( RED::Vector3( 0.0, 0.0, 0.0 ), 20.0f, 20.0f, state ) );
```

By default, the `RED::IMeshShape::Quad` function draws a horizontal quad lying along the XY plane. Our billboard needs to be vertical so a `RED::ITransformShape` is added as parent in the scene graph in order to handle this transformation. We will also add another transform shape on top of them to handle the billboard rotation to face the camera.

```// Create a transform node to handle billboard rotation:
RED::Object* billboard = RED::Factory::CreateInstance( CID_REDTransformShape );
billboard->SetID( "Billboard" );
RED::ITransformShape* ibillboard = billboard->As< RED::ITransformShape >();

// Create a transform node to handle the plane rotation:
RED::Object* planenode = RED::Factory::CreateInstance( CID_REDTransformShape );
RED::ITransformShape* iplanenode = planenode->As< RED::ITransformShape >();

// Set the plane matrix to make it vertical and looking in the y direction:
RED::Matrix mat;
RC_TEST( mat.RotationAngleMatrix( RED::Vector3::ZERO, RED_PI2, 0.0, RED_PI2 ) );
mat.Translate( RED::Vector3( 0.0, 0.0, 20.0 ) );
RC_TEST( iplanenode->SetMatrix( &mat, state ) );
```

All of the shapes are added to the scene graph accordingly to the desired hierarchy:

```// Adding the shapes to the scene:
RC_TEST( iplanenode->AddChild( quad, RED_SHP_DAG_NO_UPDATE, state ) );
RC_TEST( ibillboard->AddChild( planenode, RED_SHP_DAG_NO_UPDATE, state ) );
RC_TEST( icamera->AddShape( billboard, state ) );
```

At each frame, the plane needs to be rotated to always face the camera. The pivot axis is situated at the center of the quad and is vertical: rotation around Z. The operation is done on the billboard transform shape.

```// Get the quad-to-eye direction.
// The quad position is (0;0;0), we only have to get the camera position:
RED::Vector3 eye;
RC_TEST( icamera->GetEye( eye ) );

// Compute the horizontal rotation angle:
double angle = atan2( eye._y, eye._x );

// Rotate the billboard to always look at the camera:
RED::Matrix mat;
RC_TEST( mat.RotationAxisMatrix( RED::Vector3::ZERO, RED::Vector3::ZAXIS, angle ) );
RC_TEST( ibillboard->SetMatrix( &mat, state ) );
```

## Setting the Alpha Mask

Once we have our rotating plane, we will add a diffuse texture and an alpha mask to make it transparent. The two texture are loaded with the RED::ImageTool helper:

```// Loading the alpha mask image:
RC_TEST( iresmgr->CreateImage2D( alphamask, state ) );
RC_TEST( RED::ImageTools::Load( alphamask, "../resources/BillboardUsingAlphaMask_alpha.png", RED::FMT_RGBA, true, false, RED::TGT_TEX_2D, state ) );

RED::Object* diffuse;
RC_TEST( iresmgr->CreateImage2D( diffuse, state ) );
RC_TEST( RED::ImageTools::Load( diffuse, "../resources/BillboardUsingAlphaMask_diffuse.png", RED::FMT_RGBA, true, false, RED::TGT_TEX_2D, state ) );
```

The alpha mask texture is a RGBA image. Its masking information must be contained in the alpha channel (`RED::CHN_ALPHA`).

A new material have to be created. Generally, billboards do not need to be enlighten: the material will only contain a `RED::StateShader` and a built-in `RED::RenderShaderSolid` in the `RED::MTL_PRELIT` pass:

```// Creating a material:
RED::Object* material;
RC_TEST( iresmgr->CreateMaterial( material, state ) );
RED::IMaterial* imaterial = material->As< RED::IMaterial >();

RC_TEST( ssh.SetMaskedTransparency( alphamask, RED::MCL_TEX0, RED::Matrix::IDENTITY ) );
RC_TEST( ssh.SetAlphaThreshold( 0.5f ) );

RC_TEST( imaterial->RegisterShader( ssh, state ) );
RC_TEST( imaterial->AddShaderToPass( ssh.GetID(), RED::MTL_PRELIT, RED::LIST_LAST, RED::LayerSet::ALL_LAYERS, state ) );

RED::Color::WHITE, diffuse,   RED::Matrix::IDENTITY, RED::MCL_TEX0,
RED::Color::WHITE, alphamask, RED::Matrix::IDENTITY, RED::MCL_TEX0,
resmgr, rc );
RC_TEST( rc )

RC_TEST( imaterial->RegisterShader( solid, state ) );
RC_TEST( imaterial->AddShaderToPass( solid.GetID(), RED::MTL_PRELIT, RED::LIST_LAST, RED::LayerSet::ALL_LAYERS, state ) );

// Assigning the material to the shape:
RED::IShape* ishape = quad->As< RED::IShape >();
RC_TEST( ishape->SetMaterial( material, state ) );
```

The `RED::StateShader::SetMaskedTransparency` sets the alpha masking texture to the pipeline. The `RED::StateShader::SetAlphaThreshold` defines the value under which the object will be fully transparent and over which it will be fully opaque. In this tutorial, the alpha mask contains only two values: 0 and 1; the threshold is arbitrary set to 0.5.