class ShaderTerrainMesh

Bases: PandaNode

This class provides functionality to render heightfields of large sizes utilizing the GPU. Internally a quadtree is used to generate the LODs. The final terrain is then rendered using instancing on the GPU. This makes it possible to use very large heightfields (8192+) with very reasonable performance. The terrain provides options to control the LOD using a target triangle width, see ShaderTerrainMesh.setTargetTriangleWidth().

Because the Terrain is rendered entirely on the GPU, it needs a special vertex shader. There is a default vertex shader available, which you can use in your own shaders. IMPORTANT: If you don’t set an appropriate shader on the terrain, nothing will be visible.

Inheritance diagram

__init__() → None

This constructs a new terrain mesh. By default, no transform is set on the mesh, causing it to range over the unit box from (0, 0, 0) to (1, 1, 1). Usually you want to set a custom transform with NodePath.setScale()

setHeightfield(heightfield: Texture) → None

This sets the heightfield texture. It should be 16bit single channel, and have a power-of-two resolution greater than 32. Common sizes are 2048x2048 or 4096x4096.

You should call generate() after setting the heightfield.

getHeightfield() → Texture

This returns the terrain heightfield, previously set with setHeightfield()

Return type

Texture

setChunkSize(chunk_size: size_t) → None

This sets the chunk size of the terrain. A chunk is basically the smallest unit in LOD. If the chunk size is too small, the terrain will perform bad, since there will be way too many chunks. If the chunk size is too big, you will not get proper LOD, and might also get bad performance.

For terrains of the size 4096x4096 or 8192x8192, a chunk size of 32 seems to produce good results. For smaller resolutions, you should try out a size of 16 or even 8 for very small terrains.

The amount of chunks generated for the last level equals to (heightfield_size / chunk_size) ** 2. The chunk size has to be a power of two.

getChunkSize() → size_t

This returns the chunk size, previously set with setChunkSize()

Return type

size_t

setGeneratePatches(generate_patches: bool) → None

If this option is set to true, GeomPatches will be used instead of GeomTriangles. This is required when the terrain is used with tesselation shaders, since patches are required for tesselation, whereas triangles are required for regular rendering.

If this option is set to true while not using a tesselation shader, the terrain will not get rendered, or even produce errors. The same applies when this is option is not set, but the terrain is used with tesselation shaders.

getGeneratePatches() → bool

This returns whether patches are generated, previously set with setGeneratePatches()

setUpdateEnabled(update_enabled: bool) → None

This flag controls whether the terrain should be updated. If this value is set to false, no updating of the terrain will happen. This can be useful to debug the culling algorithm used by the terrain.

getUpdateEnabled() → bool

This returns whether the terrain is getting updates, previously set with setUpdateEnabled()

setTargetTriangleWidth(target_triangle_width: float) → None

This sets the desired width a triangle should have in pixels. A value of 10.0 for example will make the terrain tesselate everything in a way that each triangle edge roughly is 10 pixels wide. Of course this will not always accurately match, however you can use this setting to control the LOD algorithm of the terrain.

getTargetTriangleWidth() → float

This returns the target triangle width, previously set with ShaderTerrainMesh.setTargetTriangleWidth()

uvToWorld(coord: LTexCoord) → LPoint3

This transforms a texture coordinatefrom uv-space (0 to 1) to world space. This takes the terrains transform into account, and also samples the heightmap. This method should be called after generate().

Return type

LPoint3

uvToWorld(u: float, v: float) → LPoint3
Return type

LPoint3

generate() → bool

This generates the terrain mesh, initializing all chunks of the internal used quadtree. At this point, a heightfield and a chunk size should have been set, otherwise an error is thrown.

If anything goes wrong, like a missing heightfield, then an error is printed and false is returned.

static getClassType() → TypeHandle
Return type

TypeHandle

property heightfield
Getter

This returns the terrain heightfield, previously set with setHeightfield()

Setter

This sets the heightfield texture. It should be 16bit single channel, and have a power-of-two resolution greater than 32. Common sizes are 2048x2048 or 4096x4096.

You should call generate() after setting the heightfield.

Return type

Texture

property chunk_size
Getter

This returns the chunk size, previously set with setChunkSize()

Setter

This sets the chunk size of the terrain. A chunk is basically the smallest unit in LOD. If the chunk size is too small, the terrain will perform bad, since there will be way too many chunks. If the chunk size is too big, you will not get proper LOD, and might also get bad performance.

For terrains of the size 4096x4096 or 8192x8192, a chunk size of 32 seems to produce good results. For smaller resolutions, you should try out a size of 16 or even 8 for very small terrains.

The amount of chunks generated for the last level equals to (heightfield_size / chunk_size) ** 2. The chunk size has to be a power of two.

Return type

size_t

property generate_patches
Getter

This returns whether patches are generated, previously set with setGeneratePatches()

Setter

If this option is set to true, GeomPatches will be used instead of GeomTriangles. This is required when the terrain is used with tesselation shaders, since patches are required for tesselation, whereas triangles are required for regular rendering.

If this option is set to true while not using a tesselation shader, the terrain will not get rendered, or even produce errors. The same applies when this is option is not set, but the terrain is used with tesselation shaders.

Return type

bool

property update_enabled
Getter

This returns whether the terrain is getting updates, previously set with setUpdateEnabled()

Setter

This flag controls whether the terrain should be updated. If this value is set to false, no updating of the terrain will happen. This can be useful to debug the culling algorithm used by the terrain.

Return type

bool

property target_triangle_width
Getter

This returns the target triangle width, previously set with ShaderTerrainMesh.setTargetTriangleWidth()

Setter

This sets the desired width a triangle should have in pixels. A value of 10.0 for example will make the terrain tesselate everything in a way that each triangle edge roughly is 10 pixels wide. Of course this will not always accurately match, however you can use this setting to control the LOD algorithm of the terrain.

Return type

float