Introduction

Before continuing, be aware that this applies to the Paging Scene Manager.

These notes apply to the Ogre version 1.4(Eihort) compatible version of PLSM2. The previous version is not significantly different so it will probably also apply to the 1.2 version.

Configuration files are text files with the file extension ".cfg".

They contain configuration settings in the form "name=value". For exampe: "ImageSplit=yes"

Binary options are set using 'yes' or 'no'

Order of appearance within the file is not important when setting configuration file options. The character case of the strings IS important.

You must have two configuration files per map, one to split maps into pages, and one for use by the plugin to render them.

Having created a new map, let's say a 4096x4096 map, you want to visualize it with PLSM:

• First you'll want to define a map splitter config file, which defines how you want to split and texture it.
• Then you want to add the map config file name to the maptools.cfg list of maps that your mapsplitter can handle, even adding it as the defaultmap and disable batching so that it splits only that one, and not all the maps you have on the list.
• You launch Mapsplitter. Be warned, depending on the options selected, it can be a VERY long process.
• Once you filled you hard disk with the split map data, you now can make the run time configuration file.
• There you are required to define at least where to find files, how to load them, and some default texture mode to apply.

Map Selection Configuration

The configuration files maptools.cfg and paginglandcsape2.cfg list available files and defaults.

The config file maptools.cfg is used by the MapSplitter.exe tool and paginglandscape2.cfg is used by the sample Demo_PagingLandScape2.exe. When you use the plugin in your own application you can use a copy of paginglandscape2.cfg and rename it (to, say, PLSMTerrain.cfg) and load it using Scene Manager's setWorldGeometry method.

Example:

mSceneMgr->setWorldGeometry( Ogre::String("PLSMTerrain.cfg") );

maptools.cfg

• DefaultMap: Name of the map that will be loaded, or handled first if batchmode is selected.
• GroupName: Resource group name where the map config files can be found
• <Short Map Name>=<Config File Name>: Assigns config file name (without .cfg extension... so gcanyon_height_4k2k.gen refers to gcanyon_height_4k2k.gen.cfg) to short map name, you may list more than one map and they can all be split one after another in batch mode.

• BatchMode=yes/no

Specify if you want all the maps to be split, or just the default map.

Example (maptools.cfg):

# Default Map, will split only this map if BatchMode=no
    DefaultMap=MyTerrain

    # Other maps, will split all of these if BatchMode=yes
    puget_sound=puget_1k.gen
    grand_canyon=gcanyon_height_4k2k.gen
    MyTerrain=WorldTerrainMap.gen

    # resource group under which all PLSM2 resources can be found
    GroupName=PLSM2

    # BatchMode: yes = split all maps above, no = split only default map
    BatchMode=no

paginglandscape2.cfg

• DefaultMap: Sets which map is loaded on startup. "none" causes PLSM2 to not load any map (Default Value : none)
• GroupName: Resource group name where the map config files can be found
• <Short Map Name>=<Config File Name>: Assigns config file name (again without .cfg extension) to short map name, you may list more than one map and choose between them by setting DefaultMap.

• TextureFormatDebug: Try forbidden textureformat combinations (Default Value : no)

Example (paginglandscape2.cfg):

# Default Map, will load this at start up
    DefaultMap=MyTerrain

    # Other maps
    puget_sound=puget_1k
    grand_canyon=gcanyon_height_4k2k
    MyTerrain=WorldTerrainMap

    # resource group under which all PLSM2 resources can be found
    GroupName=PLSM2

    # Don't try forbidden textureformat combinations
    TextureFormatDebug=no

Terrain map specification

The file name of the configuration file should be the name given in the "DefaultMap" section of the plsm2 configuration file with ".cfg" appended. I.E. for "DefaultMap=Test" the map configuration filename is "Test.cfg"

Common options for both config files

Map definition

• GroupName : All of your terrain maps and textures should be in this resource group. (see resource.cfg)
• LandScapeFileName : Terrain filename (without extension), must be in ogre resource path and in "GroupName" group
• LandScapeExtension : Terrain filename extension. Raw if 16 bits raw, any supported Devil image type if 8 bits, and PNG 16 bits is also supported. (Default Value : png)
• LandScapeExportExtension : Terrain export extenstion (raw if you want to export 16 bits terrain or any devil...)
• TextureExtension : Texture Extension generated, PNG is ok as it's lossless. DDS isn't supported for now. (Default Value : png)
• ScaleX, ScaleY, ScaleZ : Terrain scale value, can be different in mapsplitter and demo, but must be at least proportionnal to demo terrain scale value. If not, texture generated for splatting and normals would be false. (Default Value : 1)
• PageSize : Size of the Heightfield page in pixels, must be 2^n + 1, 513 is a good pick in most cases. (Default Value : 513)
• TileSize : Size of the Heightfield Tile in pixels, must be 2^n + 1, 65 is a good pick in most cases. (Default Value : 65)

Map Splitter Configuration

Heightmap definition

• OutDirectory : Directory where you want to store all generated files (using "LandScapeFileName" at the end would use the map name as stated in the previous config parameter "LandScapeFileName" )
• MiniMap : Creates a MiniMap usable as an overlay when wandering on the map. (Default Value : no)
• Paged : If you want to split terrain map and texture maps or not. Mainly useful for debugging. (Default Value : yes)

DataSource

• Data2DFormat : 'HeightField', 'HeightFieldRaw', 'HeightFieldTC' (Default Value : HeightField)
• MaxValue, MinValue : In case of Data2DFormat = 'HeightFieldTC' this compresed format and need to know the value range from where the heightfield file was compressed (Default Value : 5000, 0)

Texturing

• ColorMapName : Big Texture Map that your Heighfield tool did generates along with map, and that you wnat to split into small texture usable by the PLSM2 (Textureformat=Image)
• ColorMapSplit : If you want to split your color map, to be used with Textureformat=Image texturemode at runtime(Default Value : no)
• ImageSplit : binary option ( set to 'yes' on 'no' ) for "ImagePaging" terrain texturing mode. If the ColorMapSplit option is not set this option is checked. Causes the program split a large image into smaller images to be paged in and out.
• LitColorMapSplit : if you want to light it, se below for lighting option.(Default Value : no)
• InfiniteMap : If you want your map to be infinitizable.(Default Value : no)
• HeightMapBlurFactor : If you want smooth your heightmap.(Default Value : 0.0f)
• Equalize : Make sure heights use the whole range 0-255 or 0-65535.(Default Value : no)
• HeightMap : If you want to split your heightmap into same format (8 bits images files or 16 bits raw or png files, usable with data2dformat = HeightField, HeightFieldRaw, or HeightFieldTC).(Default Value : no)
• NormalMap : Generates normal maps. RGB is xyz normal. (Default Value : no)
• HeightNormalMap : Generates normal maps and store it as RGB as XYZ normal and Alpha as 8 bits HeightMap (usable with data2dformat = HeightFieldN, or HeightFieldNTC) cannot be combined with Raw files (it gives 8 bits instead of 16 bits.)
  (Default Value : no)
• ColorMapGenerated : Generates a colormap. Ugly... for now. (Default Value : no)
• LitColorMapGenerated : Generates a colormap but with modulated with light, see below. (Default Value : no)
• NumMatHeightSplat : Specifies the number of height splats that will be used. (Default Value : 0)
• MaterialHeight1, MaterialHeight2 : In percentage of max terrain height, below MaterialHeight1 its Splat0, up MaterialHeight1 but below MaterialHeight2 its Splat1, up MaterialHeight1 but below MaterialHeight2 its Splat2, up its Splat3.
• SplatFilename0, SplatFilename1, SplatFilename2, SplatFilename3, SplatFilenameX : Map defining textures used as input for averaging colors in BaseTexture map generation.
• BaseMap : Base map for big scale maps, used for long distance instead of splatting or just as BaseTexture. (Default Value : no)
• LitBaseMap : Same but with modulated with light. (Default Value : no)
• CoverageMap : Coverage is RGBA, each channel has info for 1 splat (Textureformat=splatting3). (Default Value : no)
• AlphaMaps : Generates 1 alpha map per splatting (Textureformat=splatting2, splatting4, splatting6, splatting7). (Default Value : no)
• LightMap : Generates a lightmap, with 8bits texture white is full light to black being full shadow(see Textureformat=splatting4). (Default Value : no)
• ShadowMap : For debugs, mainly inverse of lightmap. (Default Value : no)
• Sunx, Suny, Sunz : Sun Direction to generate the lightmaps.
• Ambient, Diffuse, Blur : Parameters for lightmap generation.
• ZHorizon : Horizon mapping with sun always on Z axis, and thus can be use in a shader to real-time shadows a terrain. (Default Value : no)
• ''NumSplatMapToSplit, SplatMapName0, SplatMapName1, SplatMapName(N)' : Specifies additional map you want to split. (user provided alpha spla maps, for roads or anything)

* AlphaSplatRGBAMaps, AlphaSplatLightMaps, RGBMaps, HorizonMap, ElevationMap, PVSMap'' : deprecated. (Default Value : no)

• TextureModifiable does texture should/can be updated on the fly by user (painting/deformations)

Run Time Configuration (Plugin Configuration)

Paging Option

• Width: World Width, The number of Pages in the world in the x dimension. Required
• Height: World Height, The number of Pages in the world in the z dimension. Required
• VisibleRenderables is the radius number of tiles VISIBLE around camera.
• MaxAdjacentPages is the radius number of pages LOADED around camera (aren't necessary visible as it depends on visible renderables.) (Default Value : 2)
• MaxPreloadedPages is the radius number of pages preloaded around camera
  (has to be superior to MaxAdjacentPages as an adjacent pages has to be preloaded prior to be loaded.)(Default Value : 3)
• MaxNumRenderable is the maximum number of renderables loadable at once.
• MaxNumTiles is the maximum number of Tiles loadable at once. (The size of the tiles cache)

DataSource Definition

• Data2DFormat : 'HeightField', 'HeightFieldRaw', 'HeightFieldN', 'HeightFieldTC', 'HeightFieldNTC','HeightFieldRawTC', 'HeightFieldRaw'. Specify the format of page heightmap data source. Heightfield is 8-16bits image files, HeightFieldRaw is for 16 bits Raw, ---N is 8bits heightmap + normal file, and TC source is scaled using MaxValue, MinValue. (Default Value : HeightField)
  Data2DFormat explained here.
• MaxValue, MinValue : in case of Data2DFormat = 'HeightFieldTC' this compressed format and need to know the value range from where the heightfield file was compresed. (Default Value : 5000,0)
• Deformable : does terrain should support real-time deformation. (Default Value : no)
• TextureStretchFactor : scale factor between pagesize and texturesize. for exemaple having a 1024 texture on 513 page size would give a TextureStretchFactor of 2. (Default Value : 1.0f)

Material Definition

• TextureFormat : Defines how landscape will be textured. If you want to use you own texture, Image it
  Texture Modes explained here.
• NumTextureFormatSupported : put here the number of supported texture format supported (depends on what textures you have splitted using mapsplitted (is there alpha, base, coverage or light textures? )
• TextureFormatSupported<n> : list all texture format supported by this map. (e.g. TextureFormatSupported0=Base TextureFormatSupported1=InstantBase etc...)
• MaterialHeight1, MaterialHeight2 : in percentage of max terrain height, below MaterialHeight1 its Splat0, up MaterialHeight1 but below MaterialHeight2 its Splat1, up MaterialHeight1 but below MaterialHeight2 its Splat2, up its Splat3. (used in Real-time splatting modes, and when deformation make texture to update.)
• SplatFilename0, SplatFilename1, SplatFilename2, SplatFilename3 : map defining textures used as input for averaging colors in BaseTexture map generation.
  Textureformat=splatting4)

Advanced Options

• MaxRenderLevel : The maximum LOD level simplification. Must verify 2^MaxRendervel < (TileSize/2). 0 means no LODValue and 100 defines the max possible. (Default Value : 100)
• MaxPixelError : The maximum error allowed when determining which LOD to use. That would determine complexity on screen. More Precise means slower. (Default Value : 8)
• PageSize : determines how 'GPU batched' your terrain will be, as it determines the size of the texture per page. Bigger is Better, but not all video card would support too big texture. (note that plsm2 demos uses small pagesize like 257, mainly for page management testing), that can lead to false impression that PLSM2 is slower than TSM. At same pagesize and number of page, you'd get same results or faster. try 1025, 2049. (Default Value : 513)
• TileSize : Difficult to tweak, determines how big a Vertex Buffer will be. Using Too big Tilesize (> 193). make plsm2 to use 32 bits index buffers (slower and not supported on all video cards). using too small Tilesize (<65) would make plsm2 handle thousands of tiles each frames and wouldn't be very GPU Batch friendly, but gives much more Culling opportunities (Frustum Culling, Horizon Culling, Octree Culling...). (Default Value : 65)
• VertexCompression : If your card supports it, enable it (if you card doesn't suport it will be ignored). It divides GPU Memory usage by at least factor 3. (Default Value : no)
• VertexProgramMorph : If you notice too much popping when tiles changes Lod, this reduce it a lot. But it has a big performance cost, so in case of bad performance, be sure to diable it. (on ATI opengl, it leads to a driver bug.)
• HorizonVisibilityComputing : enable it if your map have moutains, cliffs... not if it's mainly a plane. Everything (for now just other terrain tiles, soon also any objects) hidden by Terrain Tiles will not be send to GPU, saving massive amounts of framerates, but in particular case. (didn't cost much if enabled anyway.) (Default Value : no)
• LODMorphStart: This is as a proportion of the distance between the current LODs effective range, and the effective range of the next lower LOD (Default Value : 0.2f)
• HorizonVisibilityComputing: enable it if your map have moutains, cliff... not if it's mainly a plane. everything hidden will not be send to GPU, thus saving framerates.. (Default Value : no)
• VertexLit: add normals to the heightmap mesh. Useful for stencil additive shadows.

Originally by Tuan Kuranes

English fixed up by EagleEye