MaterialToken

Description

static class Tinman.Terrain.Util.MaterialToken

The MaterialToken class implements the concept of material tokens for terrain rendering.

A material token is a 64-bit value that defines weights for up to 4 materials out of a palette of 256 possible materials:

Bits     | Name | Description               | Range
---------+------+---------------------------+---------
[0 .. 8[ | w0   | Weight of first material  | [0..255]
[8 ..16[ | w1   | Weight of second material | [0..255]
[16..24[ | w2   | Weight of third material  | [0..255]
[24..32[ | w3   | Weight of fourth material | [0..255]
[32..40[ | m0   | ID of first material      | [0..255]
[40..48[ | m1   | ID of second material     | [0..255]
[48..56[ | m2   | ID of third material      | [0..255]
[56..64[ | m3   | ID of fourth material     | [0..255]

A weight value of 255 means that the material is fully realized, a value of 0 means that the material is completely dissolved. Furthermore, the material ID values of a token always appear in descending order, and the last material ID is duplicated in order to mark the token end:

m0 > m1 > m2 > m3     -> four materials
m0 > m1 > m2, m3 = m2 -> three materials
m0 > m1, m2 = m3 = m1 -> two materials
m0 = m1 = m2 = m3     -> one material

The individual material weights are unrelated. It is up to the application to properly interpret the weights.

Public / Methods

Count

[Pure]
public static method Count → (1)

mask in : int64

The material mask (see Mask).

returns → int32

The number of materials.

Counts the number of materials in the given material mask.

Distance

[Pure]
public static method Distance → (2)

tokenA in : int64

First material token.

tokenB in : int64

Second material token.

returns → int32

The relative distance between the material tokens.

Computes the distance between the given material tokens.

For

2 overloads

[Pure]
public static method For1 → (2)

material in : int32

The material ID, in the range [0..255].

weight opt : int32 = 255

The material weight of material in, in the range [0..255].

returns → int64

The material token.

Creates a material token.

[Pure]
public static method For2 → (8)

m0 in : int32

The material ID, in the range [0..255] or -1 if not used.

m1 in : int32

The material ID, in the range [0..255] or -1 if not used.

m2 in : int32

The material ID, in the range [0..255] or -1 if not used.

m3 in : int32

The material ID, in the range [0..255] or -1 if not used.

w0 in : int32

The material weight of m0 in, in the range [0..255].

w1 in : int32

The material weight of m0 in, in the range [0..255].

w2 in : int32

The material weight of m0 in, in the range [0..255].

w3 in : int32

The material weight of m0 in, in the range [0..255].

returns → int64

The material token.

Creates a material token.

If the material IDs m0 in, m1 in, m2 in and m3 in are not distinct, the weights will be summed and clamped at 255.

Mask

[Pure]
public static method Mask → (1)

token in : int64

The material token.

returns → int64

The material bitmask.

Returns the bitmask for the given material token.

A material ID n is mapped to the bit 2^n.

See also

Semantic.MaterialMask

Material​At

[Pure]
public static method MaterialAt → (2)

token in : int64

The material token.

n in : int32

The material index, in the range [0..3].

returns → int32

The material ID.

Returns a material ID of the given token.

Mix

2 overloads

[Pure]
public static method Mix1 → (4)

a in : int64

First material token.

b in : int64

Second material token.

fa in : int32

Scale of first material token, in the range [0..255].

fb in : int32

Scale of second material token, in the range [0..255].

returns → int64

The resulting material token.

Mixes the given material tokens.

[Pure]
public static method Mix2 → (8)

a in : int64

First material token.

b in : int64

Second material token.

c in : int64

Third material token.

d in : int64

Fourth material token.

fa in : int32

Scale of first material token, in the range [0..255].

fb in : int32

Scale of second material token, in the range [0..255].

fc in : int32

Scale of third material token, in the range [0..255].

fd in : int32

Scale of fourth material token, in the range [0..255].

returns → int64

The resulting material token.

Mixes the given material tokens.

Range

[Pure]
public static method Range → (1)

token in : int64

The material token.

returns → int32

The material weight ranges.

Returns the material weight range for the given material token.

A material weight range is a 30-bit integer value, having the following layout:

32      24      16       8       0
 v.......v.......v.......v.......v
  10cccccccccc10bbbbbbbb10aaaaaaaa

a  = minimum weight, in the range [0..255]
b  = maximum weight, in the range [0..255]
c  = maximum weight sum, in the range [0..1020]
10 = guard bits
See also

MaterialToken.RangeMin
MaterialToken.RangeMax
MaterialToken.RangeSum

Range​Max

[Pure]
public static method RangeMax → (1)

weights in : int32

The weight range.

returns → int32

The maximum weight.

Returns the maximum weight of all materials.

See also

MaterialToken.Range

Range​Merge

[Pure]
public static method RangeMerge → (2)

a in : int32

First weight range.

b in : int32

Second weight range.

returns → int32

The merged weight range.

Merges the given weight ranges.

See also

MaterialToken.Range

Range​Min

[Pure]
public static method RangeMin → (1)

weights in : int32

The weight range.

returns → int32

The minimum weight. Will be 0 iff there are no materials present at all.

Returns the minimum weight of all present materials.

See also

MaterialToken.Range

Range​Sum

[Pure]
public static method RangeSum → (1)

weights in : int32

The weight range.

returns → int32

The maximum weight sum.

Returns the maximum weight sum of all material tokens.

Weight​At

[Pure]
public static method WeightAt → (2)

token in : int64

The material token.

n in : int32

The material index, in the range [0..3].

returns → int32

The material weight.

Returns a material weight of the given token.

Weight​For

[Pure]
public static method WeightFor → (2)

token in : int64

The material vector.

materialId in : int32

ID of material which weight to return.

returns → int32

The material weight.

Converts the given material token to a weight for the given material.

Weight​From​Blend​Factor

[Pure]
public static method WeightFromBlendFactor → (3)

f0 in : float32

First dependent blend factor.

f1 in : float32

Second dependent blend factor.

f2 in : float32

Third dependent blend factor.

returns → Vec3F

The independent blend weights.

Computes independent blend weights from the given blend factors.

Given the following blend function:

Blend(v0, v1, f) := v0 * (1 - f) + v1 * f

This method computes the independent blend weights X, Y and Z, so that the following holds true:

Blend(Blend(Blend(a, b, f0), c, f1), d, f2)
=
a * (1 - X - Y - Z) + b * X + c * Y + d * Z
See also

MaterialToken.WeightToBlendFactor

Weight​Sum

[Pure]
public static method WeightSum → (1)

token in : int64

The material token.

returns → int32

The material weight sum.

Returns the material weight sum of the given token.

A weight sum greater than 255 means that the material is overly saturated.

Weight​To​Blend​Factor

[Pure]
public static method WeightToBlendFactor → (3)

wb in : float32

Second independent blend weight.

wc in : float32

Third independent blend weight.

wd in : float32

Fourth independent blend weight.

returns → Vec3F

The dependent blend factors.

Computes dependent blend factors from the given blend weights.

Given the following blend function:

Blend(v0, v1, f) := v0 * (1 - f) + v1 * f

This method computes the dependent blend factors X, Y and Z, so that the following holds true:

Blend(Blend(Blend(a, b, X), c, Y), d, Z)
=
a * wa + b * wb + c * wc + d * wd

where wa is defined as 1 - wb - wc - wd.

See also

MaterialToken.WeightFromBlendFactor

Configuration

Config

public static attribute Config → (get)

value : IConfigurator<int64>

[not-null]
The configurator object.

The configurator object for this type.