====== Accessing Billboard Geometry ======

There are two types of billboard geometry: vertical/360-degree billboards, and a single static horizontal billboard.

----

===== Vertical Billboards =====

The SVerticalBillboards structure can house multiple vertical billboard images, each generated by the SpeedTree Compiler. It contains the dimensions of the billboard image as well as a table of texture coordinates that reference the billboard atlas. By default, billboards are rendered with a normal map. It is assumed that the diffuse and normal billboard atlases will be aligned and accessing with the same texture coordinates. m_pTexCoords will hold four floats for each billboard image. These floats represent:


  * Left-most U texcoord

  * Bottom-most V texcoord

  * Unordered List ItemU width (right-most minus the left-most U texcoord)

  * V height (top-most minus the bottom-most V texcoord)

In addition to the m_pTexCoords values, m_pRotated contains an array of bool flags, one per vertical billboard image, specifying if that billboard is rotated in the atlas. These hints are helpful in optimizing the billboard vertex shaders. If the flag is true, the corresponding atlas entry is rotated. 

|^**Note:** In the billboard vertex shader, each billboard image's texcoords are uploaded as an ordered set of four float values. The rotation flag is carried over in the sign bit of the first texcoord if the image is rotated.^|

The SVerticalBillboards structure is below:

<code cpp-qt>
struct SVerticalBillboards
{
    st_float32          m_fWidth;             // width of the billboard, governed by tree extents		
    st_float32          m_fTopPos;            // top-most point of the billboard, governed by tree height
    st_float32          m_fBottomPos;         // bottom-most point, can be below zero for trees with roots, etc.
    st_int32            m_nNumBillboards;     // number of 360-degree billboards generated by Compiler app

    const st_float32*   m_pTexCoords;         // 4 entries per image (left u, bottom v, width u, height v)
    const st_byte*      m_pRotated;           // one entry per image, 1 = rotated, 0 = standard

    // the Compiler app can generate non-rectangular cutouts, reducing the fillrequirements at the
    // cost of added vertices; these vertices are 
    st_int32            m_nNumCutoutVertices;	
    const st_float32*   m_pCutoutVertices;    // # elements = 2 * m_nNumCutoutVertices [ (x,y) pairs ];
                                              // [x,y] values are range [0,1] as percent across height & width

    st_int32            m_nNumCutoutIndices;
    const st_uint16*    m_pCutoutIndices;     // # elements = m_nNumCutoutIndices, indexed triangles
};
</code>

----

===== Cutouts =====

Added as an optional feature, the Compiler application can generate non-rectangular billboard geometry. More more-fitting silhouettes can be created to reduce the fill requirements at the cost of increased vertex processing. The image below shows an example eight-billboard atlas and the corresponding four-triangle cutouts (as opposed to the default two-triangle rectangles).

{{ :billboard_cutouts.jpg?nolink |}}

The cutout coordinates are available as indexed percentage values. That is, they will be rendered as indexed triangles where the coordinates are in the [0.0, 1.0] range. Percentages are used instead of absolute numbers so that the shader may multiply against the current image's geometry width and height as well as its texture coordinate width and height for proper interpolation.


----
===== Horizontal Billboards =====

This is a simple static quad the does not change based on the camera direction other than fading in or out. Like the vertical billboard, it is assumed that the texture coordinates for the diffuse billboard atlas and the normal map billboard atlas will be the same, both accessed by the m_afTexcoords member below.

Horizontal billboards do not use cutouts.

<code cpp-qt>
struct SHorizontalBillboard
{
    st_bool     m_bPresent;        // true if an overhead billboard was exported using Compiler
    Vec3        m_avPositions[4];  // four sets of (xyz) to render the overhead square
    st_float32  m_afTexCoords[8];  // 4 * (s,t) pairs of diffuse/normal texcoords
};
</code>