Folliage Replicator Help

#1 FolliageFile - this is where you get to select what .jpg or .png you want to show.
This allows you to select any texture file. Valid paths include the mod directory, so something like "fps/data/mycoolgrass1" would do fine. Sorry, no compound textures at the moment but that is coming. For the moment, simply use multiple replicator objects.

FolliageCount - this can be just about any number from 1 to 15,500 or maybe even bigger. Sometimes I must have made it too big because no folliage was displayed. I think it has something to do with the size of the replicator area.
The quantity of replicated Grass items you require. Make sure your graphics card can handle it or you'll end up with 1fps (or less!)

FoliageRetries - DKW
When the replicator is tasked with finding a home for each Grass item, it will look at the configuration options described within the replicator and attempt to find a random position to place it. It will choose random locations and then see if they fit the configuration constraints, if not then it will try again. The replicator will attempt this for EACH object. If it does not succeed then it will give up for that object and continue with the next.

Area:
InnerRadiusX = "0"; You can make your foliage area a solid circle, or a ring, using these settings
InnerRadiusY = "0"; Set your InnerRadiusX,Y to zero(0) for a solid circle. For a ring, make them larger. Naturally, these have to be lower than the OuterRadiusX,Y.
The placement area for grass elementsis centered around the replicator position based upon an elliptical ring-area whose inner bound is defined with . The replicator will choose a random polar angle outside this region.

OuterRadiusX = "70"; Mathematically, you can determine the Area of your circle A=2pir then you can decide how many replications (folliageCount) to use to fill it.
OuterRadiusY = "70";
The placement area for grass elementsis centered around the replicator position based upon an elliptical ring-area whose outer bound is defined with . The replicator will choose a random polar angle inside this region.

Dimensions:
MinWidth = "1"; This is the minimum width of the folliageFile.png that will be displayed.
MaxWidth = "2"; If you want all the plants displayed as the same size, set all these to 1.
MinHeight = "1"; If you want some variation to plant dimensions, change them.
MaxHeight = "3"; They default to MinW=1, MaxW=3, MinH=1, MaxH=5
When placing Grass onto the terrain, the Grass can be optionally scaled randomly from Min to Max in Width/Height.

FixAspectRatio = "1"; defaults to true (checked) DKW
Keeps the aspect ratio of the original texture correct. The Height is choosen according to the above settings and is also used for the width as well to keep the aspect ratio correct.

FixSizeToMax = "0"; defaults to false (unchecked) I'm assuming this means you don't want all folliage to be the max size.
Fixes the size to the / settings above (if you don't want random sizes).

OffsetZ = "0"; defaults to zero (0).
When placeing Grass onto the terrain, sometimes they do not quite meet the ground. Also, when they are allowed to be place on steep slopes they can sometimes stick out of the terrain looks damn silly. Use -Z values to lower Grass and +Z to raise them.

RandomFlip = "1"; defaults to true. I think this means some images will be mirrored. This is good. That gives a little more variability to the display.
Randomly flips the the billboard horizontally. This can add a little more variety to the billboard images. Obviously this is only effective on non-horizontally-symmetric textures.

Culling: Culling usually means some sort of polygon or diplay reduction, which will benefit performance.
UseCulling = "1"; defaults to true. I think that means it only displays folliage that can be seen. Folliage will not be displayed behind DIF's or behind the camera FOV
Turns-on the culling facility. If you are using the replicator to create only a few items or only in a very small area them the culling algorithm can actually slow things down slightly. This gives you the ability to turn it off although you should avoid this unless you are sure you know what you're doing!


CullResolution = "64";
The culling algorithm is difficult to explain but it is essential to understanding how to efficiently control large quantities of billboards. Without culling *all* grass elementsare tested to see if they are in view and if so they are rendered. If your grass elementsare spread out over a large distance then chances are that you won't be able to view many of them but they are still tested to see if they are in view. The culling algorithm avoids this and only tests the ones that are in view. How can it know this without testing them, chicken and the egg I hear you shout! Well, the replicator creates a structured database of grass elementsand their positions at the level startup phases. Basically the algorithm splits up your total defined area (see 'RadiusOuterX/Y') into quadrants the smallests of which is this field 'CullResolution'. Above these are progressively larger blocks which cover each lower quadrant. Imagine a cube of blocks where each block has four smaller blocks directly below it repreating for many levels until each small block is your resolution. Teh algorithm can check the larger block first and check to see if it's in view. If it's not it can effectively ignore all the smaller sub-areas below it therefore removing the need to check them. I told you this was difficult to explain!

Basically, the rule is that the replicator will split up the replicated area into blocks the size of 'CullResolution'. The larger your area, the more time and memory are needed to create this structure. Try to keep the 'CullResolution' large enough so that good-size blocks of Grass can be checked quickly but not too large that the blocks are as big as your viewing frustum. Also, your viewing frustum is not simply the 'VisibleDistance' as set in the "Sky" object but the smaller of that or the 'ViewDistance'+'FadeInRegion' as set in this object.

As an example:-

The 'VisibleDistance' is 500,
The 'RadiusOuterX/Y' are 512 (an area 1024 squared),
The 'ViewDistance' is 250 and the 'FadeInRegion' is '50'.

A good setting fr this scene would be 64 as the area is quite large (1024 squared) and results in 1024/64 highest resolution blocks.

IMPORTANT NOTE:-
The algorithm is more memory efficient if the 'CullResolution' can divide the largest diameter of the replicator evenly.
Also I have clamped 'CullResolution' so that you cannot set it higher than half the largest diameter or lower than 8.
Values lower than 8 can result in hundreds of megabytes being allocated for sizable areas!

Use to aid you. If the boxes are spaced very far apart you can try reducing the value else make it bigger if the boxes are very close. At all times monitor you FPS when tweaking this value as it's the ultimate guide.

If you are confused by this field then please drop me an email and I will try to explain it better.

Values of 16/32/64/128/256 are good depending upon your area/visible distance.

This algorithm allows you to maintain *massive* quantities of Grass easily but you must be aware of the memory usage. To this end, the replicator dumps various information to the console each time it creates Grass (@startup & Editor/Apply). You get information such as Node allocations/Time Taken for analysis and approximate memory usages.

#2 ViewDistance = "50";
Controls the point at which the Grass will be completely faded-in.

ViewClosest = "1";
Controls the point nearest to the camera at which the Grass will start fading-out. This can be use to stop Grass entering the cabin when a vehicle like the Racing demo.

FadeInRegion = "10";
FadeOutRegion = "1";
Controls the distances which the fade-in/out will take place. A larger value will result in a slower/longer fade-in/out. The FadeIn/Out extend the ViewDistance/ViewCloset parameters.


AlphaCutoff = "0.2";
Allows you to control the alpha level at which the rendering takes place. This can be very handy in feathering the edges of the Grass.

GroundAlpha = "1";
Allows you to control the alpha level at the base of the billboard. This allows you to reduce the harsh intersection that grass elements have with the terrain.

Animation:
SwayOn = "0"; Checked allows the folliage to sway back and forth.
SwaySync = "0"; Checked has all folliage in this replicator swaying in rhythm
SwayMagSide = "0.1"; Distance of sway from side to side
SwayMagFront = "0.2"; Distance of sway front to back
MinSwayTime = "3"; time period of sway measured in seconds. Lower number sways faster than larger number.
MaxSwayTime = "10";

Lighting:
LightOn = "0"; Checked turns on the animation lighting.
LightSync = "0"; All folliage in this replication has the same lighting
MinLuminance = "0.7"; from zero (0) to one (1)
MaxLuminance = "1"; from zero (0) to one (1)
LightTime = "5"; Time it takes to change from MinLuminance to MaxLuminance measured in seconds

Restrictions:
AllowOnTerrain = "1";

AllowOnInteriors = "0"; If this is checked (or 1) then your folliage will be shown on DIF structures. Usually not a good idea.

AllowOnStatics = "0"; If this is checked (or 1) then your folliage will be shown on StaticShapes (I think). Usually not a good idea.
When the replicator is choosing positions to place Grass you can choose whether to allow or disallow four different object types onto which they can be placed. This provides a very powerful means of placement. replaces the previous option.

AllowOnWater = "0"; If this is checked (or 1) then your folliage will be shown under Water surfaces.

AllowWaterSurface = "0"; Cool for things floating on water, like lilypads or algae.
When the replicator is allowed to placed the objects on water then this option controls whether the objects are allowed to be placed on the surface or the underlying terrain.

AllowedTerrainSlope = "90"; This is theangle of terrain which will allow folliage to be displayed. If you set it at 0, then only flat surface will display folliage. I recommend setting it to less than 45. In my game, it's set at 5.
When placing objects onto the terrain (or other objects) the replicator will ensure that it meets the slope requirements. You can control the maximum slope (from the 'Up' vector 'Z' in degrees). 90degrees gives almost no restriction but something like 15degrees only allows objects to be placed on fairly flat terrain.

Thanks to whoever wrote the Replicator and it's ReadMe files. It's very useful!!!

Tony

#3 I don't have much to add, but it would be great to see this on TDN. Thanks for doing it, it's very useful.

#4 Sim Base:
canSaveDynamicFields - is checked by default. Don't know why.

I think this lets you use and add extra variables to an object in your scripts even if they aren't part of the c++ object, which is a very handy feature in torque. I believe this is enabled for most things by default.


FolliageCount - this can be just about any number from 1 to 15,500 or maybe even bigger. Sometimes I must have made it too big because no folliage was displayed. I think it has something to do with the size of the replicator area.
The quantity of replicated Grass items you require. Make sure your graphics card can handle it or you'll end up with 1fps (or less!)

If i remember right, the foiliage placement involves picking lots of spots based on the seed number and doing a couple ray traces or collision checks or something to see if the plant can go there. This probably only applies to 3d plants. Anyways this could potentially slow down your computer exponentially while loading plants as it runs out of space and does more and more failed checks for clearance for each new plant. So I'm sure there are instances in which you would want that number much much lower, but this is probably one of those those things best to derive through playtesting anyways.


Thanks for doing all of this documentation.

#5 Just to refine what Stephen posted....

The amount of time that foliage takes to render is directly related to a few factors:

* Size of the area in which foliage is to be placed
* Number of foliage billboards to replicate
* Foliage placement restrictions
* Number of times to retry placing foliage when a suitable position cannot be found

The last item in bold is usually the load time killer. Placing a large number of billboards in a small area, with a high retry count, and lots of restrictions will take the longest to replicate. Conversely, placing the same amount of foliage within a larger area with the same retry count will yield better results.

Reducing the foliage retry count will make load times faster, but the amount of foliage replicated may be significantly less than the amount specified in FoliageCount.

It's one of the true "season to taste" widgets in the Torque toolbox. It may take a few hours to find the right balance between load times and foliage coverage.

#6 Great posts here guys! Thanks for the explanation!