The SpeedTree SDK defines several vertex properties, some familiar to everyone, while others are SpeedTree-specific and bear some explanation. The vertex property enumeration EVertexProperty is defined in Core.h.
| Note: The terms “leaf cards” and “facing leaves”, used below, are more or less the same thing: leaf geometry that turns to face the camera (sometimes called “sprites”). While SpeedTree has evolved away from using these for most models, they are still supported. Originally termed “leaf cards” because they were always rectangular in shape, they can now be arbitrarily shaped and were renamed to “facing leaf” geometry. |
VERTEX_PROPERTY_POSITION: (x, y, z) values, used by all geometry types. For almost all SpeedTree geometry, this holds the standard three-dimensional position coordinates. For facing leaf geometry, it holds the position where the facing leaf card is placed (see VERTEX_PROPERTY_LEAF_CARD_CORNER below).
VERTEX_PROPERTY_DIFFUSE_TEXCOORDS: (x, y) values, used by all geometry types. Standard diffuse texture coordinates. For branch geometry, these values will often fall out of the range [0.0, 1.0], but for atlased textures, they should stay within [0.0, 1.0]. Note that the V coordinate in UV pairs can be flipped in the Compiler as needed by some rendering engines.
VERTEX_PROPERTY_NORMAL: (x, y, z) values, used by all geometry types. Traditional geometric normal (normalized).
VERTEX_PROPERTY_LOD_POSITION: (x, y, z) values, used by all geometry types. Part of the SpeedTree LOD system is scaling geometry down as the camera moves farther away (e.g. small branches become thinner until they have zero volume). VERTEX_PROPERTY_LOD_POSITION holds the lower-LOD position counterpart to VERTEX_PROPERTY_POSITION, though they are sometimes the same value. The vertex shader lerps between then as the LOD drops.
VERTEX_PROPERTY_GEOMETRY_TYPE_HINT: A single value, used only when different SpeedTree geometry types are mixed together. This property is used by the SpeedTree shaders to determine which wind algorithm to apply. Different tree geometry types (e.g. branches or fronds) can be packed into a single draw call. Because each geometry type can have different wind code, there has to be a way to differentiate the types per-vertex. The geometry hints are defined as macros in the Include_SetUp.fx shader template:
ST_GEOMETRY_TYPE_HINT_BRANCHES = 0
ST_GEOMETRY_TYPE_HINT_FRONDS = 1
ST_GEOMETRY_TYPE_HINT_LEAVES = 2
ST_GEOMETRY_TYPE_HINT_FACING_LEAVES = 3
ST_GEOMETRY_TYPE_HINT_RIGID_MESHES = 4
VERTEX_PROPERTY_LEAF_CARD_CORNER: (x, y, z) values, applies to facing leaves only. The two-dimensional position coordinates for the leaf are defined by the (x, y) pair. In the vertex shader, they're rotated to face then camera then added to VERTEX_PROPERTY's (x, y, z) value to take their place in the overall shape of the tree. The (z) value of VERTEX_PROPERTY_LEAF_CARD_CORNER contains an offset value to prevent z-fighting among other leaf geometry lying in the same plane.
VERTEX_PROPERTY_LEAF_CARD_LOD_SCALAR: A single value, applied to facing leaves only. Part of the SpeedTree LOD system is, as the camera moves away, for some leaf geometry to get scaled down to zero area to reduce triangles, while the remaining leaf geometry is scaled up to maintain the tree's overall silhouette. As a tree instance transitions between two discrete LODs, this vertex property is used as a target scalar. If no LOD is active, this property is 1.0. If a leaf is to grow, a value greater than 1.0 is used and the vertex shader will lerp between 1.0 and this scalar value across the LOD transition.
VERTEX_PROPERTY_LEAF_CARD_SELF_SHADOW_OFFSET: Unused in version 7.x of the SpeedTreeSDK A single value, applies to facing leaves only. There is no correct way to make facing leaf geometry self-shadow, but we use this offset to reduce some of the problems associated with it. When rendering into the shadow map, the facing leaf's position is offset by this value multiplied against the light direction, preventing a poorly- or half-rendered shadow across the facing leaf geometry.
VERTEX_PROPERTY_WIND_BRANCH_DATA: (x, y, z, w) values, shared by all geometry types if wind is enabled. These four values are need for the core branch wind vertex shader algorithm (note that all geometry types make calls to the branch wind because they have to move with the parent branch). The individual values are:
x: Wind weight, level 1
y: Packed wind normal, level 1
z: Wind weight, level 2
w: Packed wind normal, level 2
VERTEX_PROPERTY_WIND_EXTRA_DATA: (x, y, z) values, interpreted differently by different geometry types if wind is enabled. Used by the more advanced wind algorithms, these values are interpreted differently by fronds and leaf geometry (both mesh & facing):
x: Packed ripple direction (fronds), or wind scalar (leaves)
y: Ripple scalar (fronds), or packed growth direction (leaves)
z: Length percent (fronds), packed ripple direction (leaves)
VERTEX_PROPERTY_WIND_FLAGS: A single value, applies to leaf geometry only. If less than zero, the main leaf wind algorithm should be applied. Otherwise, apply the alternate leaf wind algorithm.
VERTEX_PROPERTY_LEAF_ANCHOR_POINT: (x, y, z) values, used by non-facing leaf geometry only. Defines the pivot point used by the wind algorithm.
VERTEX_PROPERTY_BONE_ID: A single value, applies to all geometry types. Not used by the standard SpeedTree wind algorithm, but made available to users employing alternate approaches. This is a standard bone ID value. not included in SRT files by default, must be enabled in the Compiler.
VERTEX_PROPERTY_BRANCH_SEAM_DIFFUSE: (x, y, z) values, used by branch geometry only. Branch seam blending uses two texture lookups, one for VERTEX_PROPERTY_DIFFUSE_TEXCOORDS and another at VERTEX_PROPERTY_BRANCH_SEAM_DIFFUSE.xy. (z) is used to determine the amount to blend, per-vertex.
VERTEX_PROPERTY_BRANCH_SEAM_DETAIL: (x, y) values, used by branch geometry only. For branch seam blending where a detail layer is used, the two texture lookups are VERTEX_PROPERTY_DETAIL_TEXCOORDS (below) and VERTEX_PROPERTY_BRANCH_SEAM_DETAIL.xy. The diffuse blend value, VERTEX_PROPERTY_BRANCH_SEAM_DIFFUSE.z, is used to determine the detail blend as well.
VERTEX_PROPERTY_TANGENT: (x, y, z) values, used by all geometry types. Traditional geometric tangent (normalized). The binormal is derived from the normal and tangent values to save space.