Documentation

I hear the plugin itself is great. Why not improve it's usability and add some proper documentation or at least an API reference?

If this exists already, please give links.
Thank you

I second this. Although most people are able to use doxygen themselves, it would be much easier if an official API reference existed.

As a good reference on how to use PLSM2, I always use the Ogre Wiki: http://www.ogre3d.org/wiki/index.php/Paging_Scene_Manager
There are several pages about PLSM2, but unfortunately they are not always linked and/or up-to-date.

A dedicated PLSM website with an own wiki and an API reference would solve these problems, but Tuan is the developer and every minute he works on the website would mean a lost minute for PLSM3! So I´m not sure what to vote for

I also think we could use an official API reference and more documentation. However, if PLSM3 is Eihort compatible, then we should push for PLSM3 development!!

At least then we can use the new version and help with its development, while keeping up to date with OGRE.

KungFooMasta

Although i see how PLSM3 is important for those of you who already know how to use PLSM, it is important to have documentation for all of us newbies who are just starting with it. Only a demo cannot illustrate the correct usage of the plugin, because people usually just copypaste code, but you need to know what it means.. For example, how you could load a terrain with minimal code but still have it split into parts and so on, you really can't figure out even things like that from the demo alone.

I agree that we need better documentation. However there is nothing to stop us newbies from helping each other. Whenever one of us figures something out, even though it may seem trivial or mundane to the "Experts" why not post it here or better still add it to the wiki?

I'm up for pushing PLSM3 dev (I really want the ability to plugin my own tile loader), along with good documention (if a wiki for it, I could help as I learn it).

This is an open source community. All the information is available because you are given the entire source code. If you want better documentation, why not work on it yourself and provide it to the community? Tuan is busy with his own life, and the plugin he's provided is incredible.

I'm sorry, I just feel like this thread is asking for a handout from someone who's already given so much to begin with.

In other words, Grom will never need to post on this forum again, since he has everything he needs from the source, and should be able to solve every problem he has ever encountered. Now back to the real world.

Of course Tuan put in a lot of work and effort in making PLSM2, and we are all greatful he did. Still, its nice to hear what people would like to see, as others who are more willing to contribute back know what is in demand, and what would help most.

KungFooMasta

i know man, it's just that with the wealth of information available for free as it currently is, it seems a little greedy to ask for better documentation unless you're willing to help with the creation of it. sorry if i came off as rude.

First of all, I think we need to understand a few things about open source:-

1) Open source if not all, mostly are free. So expecting a free (but wonderful) plugin comes with good documentation is quite demanding. Ogre itself is a a very good graphics rendering library with good documentation too - but that is not a usual sight.

2) Therefore, asking for documentation is okay, but dont press for it.

3) And like it or not, many times you will have to be able to scour the source code and try to understand it. Or even better, try to understand the concept and algo behind it, and work it from that way.

Of course the best thing is to have a plugin like PLSM2 and many simple examples using it, and all of them are flawless. But I am afraid, this will need community collaboration - WIKI

Hello all,
I'm writing docs so I can understand what the PLSM code does. I thought I would make them available to others and they might be useful. I'll post them here and if others would like to add their comments that would be great. What I didn't understand after a first pass at the code I left
question marks beside. I have yet to merge the wiki page with this one.

Take care

Paging Landscape Scene Manager 2 configuration

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

They contain configuration settings in the form "name=value".

In this document where you see:
"name=xxxx" the "xxxx" is a string value.
"name=n" the "n" is an integer value.
"name=n.nn" the "n.nn" is an floating point value.
"name=yes|no" the "yes|no" is a string value used to set a boolean. You should use either "yes" or "no" but not both.

Order of appearance within the file is not important when setting config file options.


plsm2 config file options:

This file is usually named "paginglandscape2.cfg" but may be different for each application.

DefaultMap=xxxx
Name of the map file(s) to load 'landscape' from. The name of the config file should be the name given here with ".cfg" appended.
Required

GroupName=xxxx
The resource section used to find the file named in "DefaultMap"
Required

BatchMode=yes|no
use all the maps in the config file or only the map named in "DefaultMap"
Default=no

TextureFormatDebug=yes|no
debug setting
optional

Map configuration file options:

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

GroupName=xxxx
The resource section named in the plsm2 config file.
Required

PageSize=n
Size of a page. A page is subdivision of the world.

TileSize=n
Size of a tile. A tile is a subdivision of a page.

Height=n
World Height, should equal the PageSize
Required

Width=n
World Width, should equal the PageSize
Required

ScaleX=n.nn
ScaleY=n.nn
ScaleZ=n.nn

PositionX=n.nn
PositionY=n.nn
PositionZ=n.nn

TextureStretchFactor=n.nn
Scaling factor for texture drawn on a tile?

HeightMapFileName=xxxx
The file name used to load the terrain height map. If this is not specified it will be taken from LandScapeFileName.

LandScapeFileName=xxxx
The file name used to load the terrain height map

TerrainName=xxxx
The file name used to load terrain????. If this is not specified it will be taken from HeightMapFileName, If this is not specified it will be taken from LandScapeFileName.

FileSystem=xxxx
optional filesystem to load resources from?

HeightMapExtension=xxxx
file extension of heightmap file. If this is not specified it will be taken from LandScapeExtension.

HeightMapExportExtension=xxxx
file extension of heightmap file. If this is not specified it will be taken from LandScapeExportExtension.

LandScapeExportFileName=xxxx
Alternate name for heightmap file.

ImageExtension=xxxx
file extension of texture file. If this is not specified it will be taken from ColorMapExtension. If this is not specified it will be taken from TextureExtension.

ImageExportExtension=xxxx
file extension of exported texture file????????. If this is not specified it will be taken from ColorMapExportExtension. If this is not specified it will be taken from TextureExportExtension.

ImageFilename=xxxx
The file name used to load terrain diffuse map????. If this is not specified it will be taken from ColorMapFileName.

Data2DFormat=xxxx
height field mode for plsm2.
Required

MaxValue=n.nn
height multiplier for heightmap

MinValue=n.nn
height multiplier for heightmap

MaterialPerPage=yes|no
is there a separate material for each terrain page?

TextureModifiable=yes|no
is the texture modifyable? (is this for dynamically modified terrain?)

UseLodMapCache=yes|no
?????

RoughnessLod=yes|no
???????

NumMatHeightSplat=n
number of splatting textures

MaterialHeightN=n.nn
The number of these is given by NumMatHeightSplat

SplatFilenameN=xxxx
The number of these is given by NumMatHeightSplat

MaterialDistanceLod=n.nn

VertexColors=yes|no
color terrain using vertex colors?

CoverageVertexColor=yes|no
???????

BaseVertexColor=yes|no
???????

BaseVertexShadow=yes|no
???????

BaseVertexInstantColor=yes|no
???????

MaxNumRenderables=n
???????

IncrementRenderables=n
???????

MaxNumTiles=n
Maximum number of tiles to cache.

IncrementTiles=n
???????

NumRenderablesLoading=n
Is this a cache of tiles? Perhaps the count of max number of tiles to attempt to load simultaneously?

RenderableLoadInterval=n
???????


MaxAdjacentPages=n
???????

MaxPreloadedPages=n
???????

PageLoadInterval=n
???????


MaxRenderLevel=n

ChangeFactor=n.nnn

VisibleRenderables=n.nn

DistanceLOD=n.nn

VertexLit=yes|no

VertexNormals=yes|no

Deformable=yes|no
is terrain dynamically deformable?

SaveDeformation=yes|no
is dynamically deformed terrain saved?

VertexProgramMorph=yes|no
only used if renderlevel > 1

LODMorphStart=n.nn
only used if renderlevel > 1

MaxPixelError=n

BigImage=yes|no

HorizonVisibilityComputing=yes|no

MaxLodUnderCam=yes|no

VertexCompression=yes|no
only used if has vertex shader

NumTextureFormatSupported=n
TextureFormatSupportedN=xxxx

TextureFormat=xxxx
Set texture format. if not defined in NumTextureFormatSupported list then this is automatically added to that list. The texture format type must be defined as a material in the resource group. The texture format must be supported by hardware.
Required

TileInvisibleUnloadFrames=n

PageInvisibleUnloadFrames=n

BaseCameraViewpoint.x=n.nnn
BaseCameraViewpoint.y=n.nnn
BaseCameraViewpoint.z=n.nnn

Baselookat.x=n.nn
Baselookat.y=n.nn
Baselookat.z=n.nn



Uzik, this is really usefull, continue on this way!

really appreciated, thanks.

I combined material with the wiki with what I had,
and got a few more updates. If you notice any errors or omissions
please speak up!

Thanks!

Paging Landscape Scene Manager 2 configuration

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".

In this document where you see:
"name=xxxx" the "xxxx" is a string value.
"name=n" the "n" is an integer value.
"name=n.nn" the "n.nn" is an floating point value.
"name=yes|no" the "yes|no" is a string value used to set a boolean. You should use either "yes" or "no" but not both.

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


PLSM2 run time configuration file options:

This file is usually named "paginglandscape2.cfg" but may be different for each application.

DefaultMap=xxxx
Name of the map configuration file(s) to load 'landscape' from. The name of the map configuration file should be the name given here with ".cfg" appended.
Required

GroupName=xxxx
The resource section used to find the file named in "DefaultMap"
Required

BatchMode=yes|no
Load all the maps in the configuration file or only the map named in "DefaultMap"
Default=no

TextureFormatDebug=yes|no
debug setting
optional

PLSM2 run time map configuration file options:

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"

GroupName=xxxx
The resource section named in the plsm2 configuration file.
Required

PageSize=n
Size of a page. A page is subdivision of the world. must be 2^n + 1, 513 is a good pick in most cases. (Default Value : 513). This 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 the same pagesize and number of pages, you'd get same results or faster. try 1025, 2049. (Default Value : 513)

TileSize=n
Size of a tile. A tile is a subdivision of a page. must be 2^n + 1, 65 is a good pick in most cases. (Default Value : 65). This is difficult to tweak, it determines how big a Vertex Buffer will be. Using Too large a Tilesize (> 193) it will make plsm2 use 32 bit index buffers (slower and not supported on all video cards). Using too small a 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...).

Height=n
World Height, should equal the PageSize
Required

Width=n
World Width, should equal the PageSize
Required

ScaleX=n.nn
ScaleY=n.nn
ScaleZ=n.nn
Terrain scale value, can be different in mapsplitter and application, but must be at least proportional to demo terrain scale value. If not, texture generated for splatting and normals would be false. (Default Value : 1)

PositionX=n.nn
PositionY=n.nn
PositionZ=n.nn

TextureStretchFactor=n.nn
Scaling factor for texture drawn on a tile?

HeightMapFileName=xxxx
The file name used to load the terrain height map. If this is not specified it will be taken from LandScapeFileName.

LandScapeFileName=xxxx
The file name used to load the terrain height map

TerrainName=xxxx
The file name used to load terrain????. If this is not specified it will be taken from HeightMapFileName, If this is not specified it will be taken from LandScapeFileName.

FileSystem=xxxx
optional filesystem to load resources from?

HeightMapExtension=xxxx
file extension of heightmap file. If this is not specified it will be taken from LandScapeExtension.

HeightMapExportExtension=xxxx
file extension of heightmap file. If this is not specified it will be taken from LandScapeExportExtension.

LandScapeExportFileName=xxxx
Alternate name for heightmap file.

ImageExtension=xxxx
file extension of texture file. If this is not specified it will be taken from ColorMapExtension. If this is not specified it will be taken from TextureExtension.

ImageExportExtension=xxxx
file extension of exported texture file????????. If this is not specified it will be taken from ColorMapExportExtension. If this is not specified it will be taken from TextureExportExtension.

ImageFilename=xxxx
The file name used to load terrain diffuse map????. If this is not specified it will be taken from ColorMapFileName.

Data2DFormat=xxxx
height field mode for plsm2. Valid values are: 'HeightField', 'HeightFieldRaw', 'HeightFieldTC' (Default Value : HeightField)
Required

MaxValue=n.nn
height multiplier for heightmap. 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)

MinValue=n.nn
height multiplier for heightmap. In case of Data2DFormat = 'HeightFieldTC' this compresed format and need to know the value range from where the heightfield file was compressed (Default Value: 0)

MaterialPerPage=yes|no
is there a separate material for each terrain page?

TextureModifiable=yes|no
is the texture modifyable? (is this for dynamically modified terrain?)

UseLodMapCache=yes|no
?????

RoughnessLod=yes|no
???????

NumMatHeightSplat=n
number of splatting textures

MaterialHeightN=n.nn
The number of these entries is given by NumMatHeightSplat. They should be numbered starting at Zero.


SplatFilenameN=xxxx
The number of these entries is given by NumMatHeightSplat. They should be numbered starting at Zero.

MaterialDistanceLod=n.nn

VertexColors=yes|no
color terrain using vertex colors?

CoverageVertexColor=yes|no
???????

BaseVertexColor=yes|no
???????

BaseVertexShadow=yes|no
???????

BaseVertexInstantColor=yes|no
???????

MaxNumRenderables=n
MaxNumRenderable is the maximum number of renderables loadable at once.

IncrementRenderables=n
???????

MaxNumTiles=n
Maximum number of tiles to cache.

IncrementTiles=n
???????

NumRenderablesLoading=n
Is this a cache of tiles? Perhaps the count of max number of tiles to attempt to load simultaneously?

RenderableLoadInterval=n
???????

MaxAdjacentPages=n
The radius number of pages LOADED around camera (aren't necessary visible as it depends on visible renderables.) (Default Value : 2)

MaxPreloadedPages=n
The radius number of pages preloaded around camera

PageLoadInterval=n
???????


MaxRenderLevel=n
The maximum LOD level simplification. Must verify 2^MaxRendervel < (TileSize/2). 0 means no LODValue and 100 defines the max possible. (Default Value : 100)

ChangeFactor=n.nnn

VisibleRenderables=n.nn
the radius in number of tiles VISIBLE around camera.

DistanceLOD=n.nn

VertexLit=yes|no
Add normals to the heightmap mesh. Useful for stencil additive shadows

VertexNormals=yes|no

Deformable=yes|no
is terrain dynamically deformable?

SaveDeformation=yes|no
is dynamically deformed terrain saved?

VertexProgramMorph=yes|no
only used if renderlevel > 1. 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 disable it. (on ATI opengl, it leads to a driver bug.)

LODMorphStart=n.nn
only used if renderlevel > 1. 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)

MaxPixelError=n
The maximum error allowed when determining which LOD to use. That would determine complexity on screen. More Precise is slower. (Default Value : 8)

HorizonVisibilityComputing=yes|no
Enable this if your map has mountains, cliffs, etc.. but 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 frame rates, but in particular case. (didn't cost much if enabled anyway.) (Default Value: no)

MaxLodUnderCam=yes|no

VertexCompression=yes|no
If your card supports it, enable it (if you card doesn't support it will be ignored). It divides GPU Memory usage by at least factor 3. (Default Value: no)

NumTextureFormatSupported=n
TextureFormatSupportedN=xxxx

TextureFormat=xxxx
Set texture format. if not defined in NumTextureFormatSupported list then this is automatically added to that list. The texture format type must be defined as a material in the resource group. The texture format must be supported by hardware.

If the texture mode is "ImagePaging" then the terrain is colored using a bitmap. The bitmap is retrieved from the resource manager using the name "ImagePaging".

Required

BigImage=yes|no
Is the terrain texture image one large image instead of small paged images?


TileInvisibleUnloadFrames=n

PageInvisibleUnloadFrames=n

BaseCameraViewpoint.x=n.nnn
BaseCameraViewpoint.y=n.nnn
BaseCameraViewpoint.z=n.nnn

Baselookat.x=n.nn
Baselookat.y=n.nn
Baselookat.z=n.nn

PLSM2 MapSplitter program configuration file options:

ColorMapSplit=yes|no
For "ImagePaging" terrain texturing mode. Should the program split a large image into smaller images to be paged in and out.


It's "Horses for Courses" really isn't it? You can learn better and gain a deeper understanding by browsing the source code but it's easier and quicker (usually) to read the Wiki.
I think it's great what Uzik is doing. When he's finished this bit perhaps we can persuade him to do the same for the map cfg & gen.cfg files. Then it will be up to those with more knowledge to fill in the missing bits.

I've put a lot of the things I've documented into the wiki page.