TINMAN 3D / REALTIME TERRAIN
Software Development Kit - User Manual

class ModelGeometry in Tinman.Engine.Models

Abstract base class for IModelGeometry implementations.

abstract class ModelGeometry implements IModelGeometry

Remarks

This class provides factory methods for building instances of the IModelGeometry interface:

Logging

Logger

The logger object of this class.

public static readonly field Logger
type ILogger

Public / Attributes

IndexCount

The vertex index count.

public abstract property IndexCount { get }
type int32
value [>=0] The vertex index count. Will be 0 iff ReadIndices returns null.
overrides IModelGeometry.IndexCount

InstanceBuffer

The resource handle that returns an IGeometryBuffer object that holds instance data to use for this model geometry object.

public virtual property InstanceBuffer { get }
type IResourceHandle
value The instance buffer to use for geometry instancing or null if geometry instancing is disabled for this model geometry object.
implements IModelGeometry.InstanceBuffer

MemoryConsumption

Returns the estimated memory consumption of this object.

public property MemoryConsumption { get }
type int64
value [>=0] The estimated memory consumption, in bytes.
implements IMemoryConsumption.MemoryConsumption

VertexCount

The vertex count.

public abstract property VertexCount { get }
type int32
value [>0] The vertex count.
overrides IModelGeometry.VertexCount

VertexFormat

The vertex format flags.

public abstract property VertexFormat { get }
type ModelVertexFormat
value The format flags.
overrides IModelGeometry.VertexFormat

Public / Constants

InstanceFormat

The vertex elements to use for instance buffers.

public static readonly field InstanceFormat
type VertexElements

Remarks:

The vertex buffer layout for instance data is defined as follows:

@0 : Float x 3 (Position)
@12 : Float x 3 (Tangent)
@24 : Float x 3 (Tangent)
@36 : UInt8_Norm_Srgb x 4 (Color)
@40 : Float x 1 (TextureCoords)
@44 : - pad -
@48 : - end -
To write instance data, use the InstanceWrite method.

Public / Constructors

Box

Builds an axis-aligned box.

public static method Box (Box3D box, int32 normals = 0, int32 texCoords = 0)
type IModelGeometrySimple
params box The box coordinates.
  normals Generate normal vectors? Defaults to 0.
> 0: Generate normals by right-hand rule for CCW faces (see figure).
< 0: Generate normals by right-hand rule for CW faces (see figure).
= 0: Do not generate normals.
  texCoords [>=0] The texture coordinate repeat count per face. Set to 0 to disable texture coordinates. Defaults to 0.
returns [not-null] The model geometry.

Remarks:

The following figure shows the mapping from the given box to the 3D model:

   121-----221
   /|      /|
  / |     / |
122-----222 |
 | 111---|-211
 | /     | /
 |/      |/
112-----212
where 111 maps to X1, Y1, Z1 and 222 maps to X2, Y2, Z2.

Build

Creates a builder for IModelGeometry objects.

public static method Build ()
type ModelGeometryBuilder
returns [not-null] The model geometry builder.

Capsule

Builds a capsule.

public static method Capsule (float64 length, float64 radius, int32 segments = 12, int32 modulo = 1)
type IModelGeometrySimple
params length [>=0] The distance between A and B.
  radius [>=0] The hemisphere radius at A and B.
  segments [>=3] The number of circle segments. Defaults to 8.
  modulo [>=1] The modulo to use for generating segment lines. Defaults to 1.
returns [not-null] The model geometry.

Remarks:

  ________________
 /                \     A = (0,0,0)
|  A------------B  |
 \________________/     B = (0,length,0)

   |____________|       length

                |__|    radius

See also:

Generic

Cone

Builds a cone.

public static method Cone (float64 length, float64 radius, int32 segments = 12, int32 modulo = 1)
type IModelGeometrySimple
params length [>=0] The distance between A and B.
  radius [>=0] The disc radius at A.
  segments [>=3] The number of circle segments. Defaults to 12.
  modulo [>=1] The modulo to use for generating segment lines. Defaults to 1.
returns [not-null] The model geometry.

Remarks:

     B
    /|\        A = (0,0,0)
   / | \
  /  |  \      B = (0,length,0)
 /   |   \
+----A----+

     |____|    radius

See also:

Generic

Cylinder

Builds a cylinder.

public static method Cylinder (float64 length, float64 radius, int32 segments = 12, int32 modulo = 1)
type IModelGeometrySimple
params length [>=0] The distance between A and B.
  radius [>=0] The disc radius at A and B.
  segments [>=3] The number of circle segments. Defaults to 12.
  modulo [>=1] The modulo to use for generating segment lines. Defaults to 1.
returns [not-null] The model geometry.

Remarks:

 ____________
|            |    A = (0,0,0)
A------------B
|____________|    B = (0,length,0)

See also:

Generic

Disc

Builds a disc that is perpendicular to (0,1,0).

public static method Disc (float64 radius, int32 segments = 12)
type IModelGeometrySimple
params radius [>=0] The disc radius at A.
  segments [>=3] The number of circle segments. Defaults to 12.
returns [not-null] The model geometry.

Remarks:

+--A--+    A = (0,0,0)
   |__|    radius

See also:

Generic

Dynamic

Creates an instance of IModelGeometryDynamic.

public static method Dynamic (int32 vertices, ModelVertexFormat format, int32 indices = 0)
type IModelGeometryDynamic
params vertices [>0] The vertex count.
  format The vertex format.
  indices [>=0] The index count or 0 for none.
returns [not-null] The dynamic model geometry.

See also:

IModelGeometry.Dynamic

Generic

Builds a 3D primitive from a generic, possibly degenerated capsule.

public static method Generic (float64 length, float64 radiusA, float64 radiusB, int32 capA, int32 capB, int32 segments = 12, int32 modulo = 1)
type IModelGeometrySimple
params length [>=0] The distance between A and B.
  radiusA [>=0] The radius at A.
  radiusB [>=0] The radius at B.
  capA The cap to build at A.
  capB The cap to build at B.
  segments [>=3] The number of circle segments. Defaults to 12.
  modulo [>=1] The modulo to use for generating segment lines. Defaults to 1.
returns The model geometry or null if empty.

Remarks:

The point A is at (0,0,0), the point B is at (0, length ,0):

  ________________
 /                \
|  A------------B  |    Round (cap > 1)
 \________________/

    ____________
   |            |
   A------------B       Flat  (cap = 0)
   |____________|

    ____________

   A------------B       None  (cap < -1)
    ____________


   |____________|       length

|__|            |__|    radiusA, radiusB
By choosing parameter values carefully, a variety of 3D primitives can be built with this method:
Primitive  | len = 0 | rA = 0 | rB = 0 | rA = rB | cA | cB
-----------+---------+--------+--------+---------+----+----
Capsule    |    no   |    no  |    no  |   yes   |  1 |  1
-----------+---------+--------+--------+---------+----+----
Cone       |    no   |   yes  |    no  |    no   | -1 |  0
           |    no   |    no  |   yes  |    no   |  0 | -1
-----------+---------+--------+--------+---------+----+----
Cylinder   |    no   |    no  |    no  |   yes   |  0 |  0
-----------+---------+--------+--------+---------+----+----
Disc       |   yes   |    no  |    no  |   yes   |  0 |  0
-----------+---------+--------+--------+---------+----+----
Hemisphere |   yes   |    no  |    no  |    no   |  1 |  0
           |   yes   |    no  |   yes  |   yes   |  0 |  1
-----------+---------+--------+--------+---------+----+----
Line       |    no   |   yes  |   yes  |   yes   | -1 | -1
-----------+---------+--------+--------+---------+----+----
Point      |   yes   |   yes  |   yes  |   yes   | -1 | -1
-----------+---------+--------+--------+---------+----+----
Sphere     |   yes   |    no  |    no  |   yes   |  1 |  1
-----------+---------+--------+--------+---------+----+----
Tube       |    no   |    no  |    no  |   yes   | -1 | -1
where len is length, rA is radiusA, rB is radiusB, cA is capA and cB is capB.

See also:

Capsule
Cone
Cylinder
Disc
Hemisphere
Line
Sphere
Tube

Hemisphere

Builds a hemisphere.

public static method Hemisphere (float64 radius, int32 segments = 12, int32 modulo = 1)
type IModelGeometrySimple
params radius [>=0] The hemisphere radius at A.
  segments [>=3] The number of circle segments. Defaults to 12.
  modulo [>=1] The modulo to use for generating segment lines. Defaults to 1.
returns [not-null] The model geometry.

Remarks:

 _
| \     A = (0,0,0)
A  B
|_/     B = (0,radius,0)

See also:

Generic

Line

Builds a line segment.

public static method Line (float64 length)
type IModelGeometrySimple
params length [>=0] The distance between A and B.
returns [not-null] The model geometry.

Remarks:

A------------B    A = (0,0,0)
                  B = (0,length,0)

See also:

Generic

Shape

Builds a 3D shape.

public static method Shape (IShape shape, bool triangles = true, bool lines = true, float64 u0 = 0, float64 v0 = 0, float64 u1 = 1, float64 v1 = 1)
type IModelGeometrySimple
params shape [not-null] The 2D shape.
  triangles Generate triangles? Defaults to true.
  lines Generate lines Defaults to true.
  u0 Texture U-coordinate to map to X1 of Bounds.
  v0 Texture V-coordinate to map to Y1 of Bounds.
  u1 Texture U-coordinate to map to X2 of Bounds.
  v1 Texture V-coordinate to map to Y2 of Bounds.
returns The model geometry or null if empty.

Remarks:

The shape is in the XY-plane, having the normal vector (0,0,1). Texture coordinates are generated in the range (u0, v0) to ( u1, v1), which maps to TopLeft resp. BottomRight of Bounds.

The triangles of the 3D shape are obtained by first converting the given shape to Mesh and then using TriangleAt.

The lines of the 3D shape are obtained by first converting the given shape to Graph and then using EdgeAt.

Sphere

Builds a sphere.

public static method Sphere (float64 radius, int32 segments = 12, int32 modulo = 1)
type IModelGeometrySimple
params radius [>=0] The sphere radius.
  segments [>=3] The number of circle segments. Defaults to 12.
  modulo [>=1] The modulo to use for generating segment lines. Defaults to 1.
returns [not-null] The model geometry.

Remarks:

  ___
 /   \
|  A  |    A = (0,0,0)
 \___/

   |__|    radius

See also:

Generic

SphereIco

Builds a sphere by subdividing an icosahedron.

public static method SphereIco (Vec3D center, float64 radius, int32 levels, int32 levelsEdges = 0, bool textureCoordinates = false)
type IModelGeometrySimple
params center The sphere center.
  radius The sphere radius. If negative, the sphere will be mirrored at center, making the normals point inwards.
  levels [>=0] Subdivisions to perform for faces (see Triangles ). Level 7 generates approximately one million triangles.
  levelsEdges [0..levels] Subdivisions to perform for edges (see Lines). Level 7 generates approximately one million lines. Defaults to 0.
  textureCoordinates Generate U and V texture coordinates?
The U-coordinate range [0..1] is mapped to longitude [-180° .. +180°].
The V-coordinate range [0..1] is mapped to latitude [ +90° ..  -90°].
Vertex positions are mapped to geographic coordinates using the conventions of Geocentric. Defaults to false.
returns [not-null] The model geometry.

Remarks:

The number of triangle vertices resp. line vertices (see Count) can be computed from the subdivision count levels resp. levelsEdges as follows:

vertices = 4 ^ levels * 60
The first eight subdivision levels produce the following triangle resp. line vertex counts:
count = 0 : vertices =      60
count = 1 : vertices =     240
count = 2 : vertices =     960
count = 3 : vertices =   3,840
count = 4 : vertices =  15,360
count = 5 : vertices =  61,440
count = 6 : vertices = 245,760
count = 7 : vertices = 983,040

Tube

Builds a tube.

public static method Tube (float64 length, float64 radius, int32 segments = 12, int32 modulo = 1)
type IModelGeometrySimple
params length [>=0] The distance between A and B.
  radius [>=0] The hemisphere radius at A and B.
  segments [>=3] The number of circle segments. Defaults to 12.
  modulo [>=1] The modulo to use for generating segment lines. Defaults to 1.
returns [not-null] The model geometry.

Remarks:

______________
                  A = (0,0,0)
A------------B
______________    B = (0,length,0)

See also:

Generic

Wrap

Creates a new instance of ModelGeometry.

[Pure]
public static method Wrap (VertexArrays vertices, int32[] indices = null)
type IModelGeometry
params vertices [not-null] The vertex data to wrap.
  indices The index data to wrap or null to create non-indexed geometry. Defaults to null.
returns [not-null] The model geometry.

Remarks:

The given vertices object and indices array will be referenced by the returned IModelGeometry object, no data is copied.

Public / Methods

CreateResource

Creates a new resource object, using the given graphics context.

[OwnerReturn]
public method CreateResource (Graphics graphics)
type IResource
params graphics [not-null] The graphics context to use.
returns [not-null] The resource object.
implements IResourceHandle.CreateResource

Remarks:

Resource objects may implement the IMemoryConsumption interface. In this case, the reported memory consumption will be interpreted as an estimate on how much GPU memory is consumed by the resource. This estimate can then be used for resource caching (e.g. CacheMemory).

Exceptions:

Dynamic

Makes this model geometry dynamic.

public virtual method Dynamic ()
type IModelGeometryDynamic
returns [not-null] The dynamic model geometry.
implements IModelGeometry.Dynamic

Remarks:

If necessary, a new model geometry is created by copying index and vertex data from this model geometry.

Exceptions:

Equals

Compares this object with the given one.

[Pure]
public abstract method Equals (IResourceHandle other)
type bool
params other The object to compare to.
returns true if this object is equal to other, false if not.

Instanced

Configures geometry instancing for this model geometry.

public virtual method Instanced (IResourceHandle instanceBuffer)
type IModelGeometry
params instanceBuffer The resource handle that returns an IVertexBuffer object that holds instance data to use for this model geometry object or null to disable geometry instancing. The instanceBuffer value will be returned by the IModelGeometry property of the returned model geometry object.
returns [not-null] The resulting model geometry.
implements IModelGeometry.Instanced

See also:

IModelGeometry

InstanceWrite

Writes instance data to the given buffer.

public static method InstanceWrite (ByteBuffer buffer, float32 positionX, float32 positionY, float32 positionZ, float32 tangentX = 1, float32 tangentY = 0, float32 tangentZ = 0, float32 normalX = 0, float32 normalY = 1, float32 normalZ = 0, float32 scale = 1, int64 color = ~0)
params buffer [not-null] The output byte buffer.
  positionX X-coordinate of instance position.
  positionY Y-coordinate of instance position.
  positionZ Z-coordinate of instance position.
  tangentX X-component of unit-length side vector.
  tangentY Y-component of unit-length side vector.
  tangentZ Z-component of unit-length side vector.
  normalX X-component of unit-length up vector.
  normalY Y-component of unit-length up vector.
  normalZ Z-component of unit-length up vector.
  scale Uniform instance scale factor.
  color The instance color.

Remarks:

This method will write a full vertex, according to InstanceFormat, including padding for alignment.

Optimized

Optimizes this model geometry by reordering those vertices that are actually referenced by the index data.

public virtual method Optimized ()
type IModelGeometry
returns [not-null] The optimized geometry, without instancing. Will be this if ReadIndices return null.
implements IModelGeometry.Optimized

ReadIndices

Read vertex index data.

public abstract method ReadIndices ()
type int32[]
returns The vertex index data or null iff IndexCount returns 0 (i.e. the geometry is not indexed).
overrides IModelGeometry.ReadIndices

Exceptions:

ReadVertices

Reads vertex data.

public abstract method ReadVertices ()
type VertexArrays
returns [not-null] The vertex data array.
overrides IModelGeometry.ReadVertices

Exceptions:

Reduced

Reduce the floating-point precision for this model geometry?

public virtual method Reduced (bool reduced)
type IModelGeometry
params reduced Use 32-bit floating-point precision (true) or 64-bit floating-point precision ( false)?
returns [not-null] The reduced geometry.
implements IModelGeometry.Reduced

Remarks:

Using reduced precision will consume less memory resp. storage space, but might introduce jitter artifacts during rendering.

Transform

Transforms the model geometry using the given matrix.

public virtual method Transform (Mat4D matrix)
type IModelGeometry
params matrix The transformation matrix.
returns [not-null] The transformed geometry.
implements IModelGeometry.Transform