Delta-Works TreeLib (c) 2007-2008 Stefan Elsen


Q/A

What is TreeLib?

TreeLib is a shared library for Linux and Windows to handle trees. The library handles generation, automated detail approximation and rendering in OpenGL.
An existing OpenGL context is required for rendering.
The library may however be used to simply extract the geometries of the generated trees in order to render them via other methods. A valid OpenGL context is not needed in this case.


Are there any restrictions on how to create the used OpenGL context (if any)?

No. Any context will do. With whatever foundation or method created.
In general You should be able to use whatever language as long as it can create an OpenGL context and open DLLs/SOs. The provided headers are for C/C++ only so far though. You may have to improvise.


Is there a version of TreeLib for Direct3d?

Not at this point. If you wish to use this library to render trees using Direct3d, You will have to extract and render the trees manually.


What extensions does TreeLib use/require?

TreeLib does not require extensions but does look and perform better if certain key extensions are available. Bump-mapping depends on OpenGL Shader Objects (using GLSL, the OpenGL shading lanaguage) being available and will be disabled if those are not supported.
Imposters will require the OpenGL Frame Buffer extension. If this extension is not available then imposter rendering will be disabled and all trees will be rendered in geometry.
Also imposters may be normal-mapped and thus look better if shader objects are available.



Is TreeLib free?

Yes. You may use TreeLib for any purpose, commercial or not, as long as the original behavior and the content of this file remain unchanged. However, charging money for the library or any of its generated geometries as a stand-alone product is prohibited.
If you payed money to acquire this library then you were probably swindled.

You may distribute this library as pleased.
A link to http://www.Delta-Works.org is appreciated but not required.



Is TreeLib open source?

Not for the time being.
TreeLib does depend on a closed-source library of considerable size and cannot be compiled by itself.



Can generated trees be exported?

Yes. The tree geometry may be exported as separate vertex and triangular index data. The leaves may be exported as an array of positions.



How many trees can i use simultaniously?

As many as you like/have memory for.
You may also reuse the same tree as often as you wish throughout the scenery.


Is TreeLib multi thread safe?

Mostly. For the sake of memory and speed efficiency i avoided the use of mutexes per tree.
To see what functions are thread safe in what manner check the function specifications below.


May I reuse the provided textures?

The textures are derivative works of free photos. They may be reused or modified as seen fit.



TreeLib contents:

The core consists of the shared library treelib.dll (treelib.so for linux/unix) and a separate 'textures' folder containing three textures:
bark.png,
bump.png,
and leaves.png
Make sure this folder is located in the same folder as the library itself when rendering or loading textures through the dll.
Additionally the files treelib.h and interface.h/.cpp help simplifying the linking process for C++ applications. To get You started with a simple example application a file 'example.zip' contains a simple GLUT application that renders a single tree to a window.
Should You encounter troubles with the example or need further instruction then feel free to contact me.


Linking TreeLib:

You should start by putting all files into a sub-folder of the project that will access the library. For easier linking it's useful to include the files interface.h and interface.cpp into your project.
The function TreeLib::load(filename) handles all necessary linking and returns true on success.
Alternatively you can link the library and extract the pointers manually.


Generating and rendering trees:

There are currently two ways of creating a tree:
void*tree = TreeLib::createTree() will create a pure random tree and
void*tree = TreeLib::createTreeFromSeed(int) will (re)create a tree from a seed.
When a new tree is created, it receives a copy of the global configuration as its own.
By default generated trees are about the size of real trees with 1.0f being 1 meter. This can be altered using the respective settings.

To render a tree it must first be put into Your scenery using the TreeLib::putTree(tree,position,up,right); where [tree] is Your tree, [position] is a pointer to a 3-float array containing the position, [up] a pointer to a 3-float array containing the up axis, and [right] a pointer to a 3-float array containing the right axis ([up] and [right] are required to be of length 1 and orthogonal to each other).

Example:

float right[3] = {1,0,0},
	up[3] = {0,1,0},
	position[3] = {0,0,0};
TreeLib::putTree(my_tree,position,up,right);

Once all trees have been put into the scenery, a simple call to TreeLib::renderComposition() will render all put trees.

Alternatively You can invoke (or not invoke) the individual tasks using the following methods:

TreeGen::renderCompositionImposters(), TreeGen::renderCompositionBranches(), TreeGen::renderCompositionShadows(), and TreeGen::renderCompositionLeaves()
These functions may be invoked in any order. However, once You're done it's crucial that You invoke the TreeGen::flushComposition() function.
Otherwise the trees of each frame will stack causing a render time explosion.




Textures:

TreeLib requires two (optionally also a third bump-map) textures, one for the leaves and one for the branches. There are two ways of specifying those:

* By string:
	By default textures are defined as filenames and loaded the first time they are needed.
	Supported file types are Bitmap, JPEG, PNG, and TGA.
	Unlike most other tree attributes, changing the filename of a tree's texture's path does not require a tree rebuild.

* By integer:
	You can specify textures directly as OpenGL texture integers, effectivly overriding any specified texture file path.
	Likewise You may also retrieve the OpenGL texture handle of a loaded texture.



Examples:


Linking, creating and rendering:

if (!TreeLib::load("treelib/treelib.dll"))
{
	cout << "Error while linking:\n"<<TreeLib::error()<<endl;
	return -1;
}

TreeLib::Tree my_tree = TreeLib::createTree();
if (!my_tree)
{
	cout << "Error while creating a tree:\n"<<TreeLib::error()<<endl;
	return -1;
}


float right[3] = {1,0,0},
	up[3] = {0,1,0},
	position[3] = {0,0,0};
if (!TreeLib::putTree(my_tree,position,up,right))
{
	cout << "Error while putting:\n"<<TreeLib::error()<<endl;
	return -1;
}

if (!TreeLib::renderComposition())
{
	cout << "Error while rendering:\n"<<TreeLib::error()<<endl;
	return -1;
}



Disabling shadows on a tree:

TreeLib::setAttributei(my_tree,TL_SHADOW,TL_NO_SHADOW);



Decreasing the level of detail of trees:

TreeLib::setAttributef(NULL,TL_LOD,0.75); //this will affect all trees that are created from this point forward

or on a specific tree:

TreeLib::setAttribute(my_tree,TL_LOD,0.75);
TreeLib::rebuildTree(my_tree);


Toggling auto balance:

bool balancing = TreeLib::getAttributei(my_tree,TL_AUTO_BALANCE);
TreeLib::setAttributei(my_tree,TL_AUTO_BALANCE,!balancing);
TreeLib::rebuildTree(my_tree);



Rendering multiple instances of a tree:

float right[3] = {1,0,0},
	up[3] = {0,1,0};

for (int i = 0; i < 10; i++)
{
	position[3] = {i*10,0,0};
	TreeLib::putTree(my_tree,position,up,right);
}

TreeLib::renderComposition();



Function specifications:

bool	TreeLib::init(const char*path);

Initializes the library. [path] should point to to the filename of the library or its folder ("./TreeLib/treelib.dll", "./TreeLib/", "./TreeLib" are valid).
The library must be initialized before trees can be generated and/or rendered. If you used the provided interface.h/.cpp files then TreeLib::load(...) will automatically call this function.
This function does not execute any OpenGL commands. A valid context is thus not needed at this point.

Return value: true on success.
Note: use TreeLib::getAttributecv(NULL,TL_ERROR) to receive an error string.


TreeLib::Tree	TreeLib::createTree();

Creates a new tree using the current global configuration and a random seed.
This function does not execute any OpenGL commands. A valid context is thus not needed at this point.
Trees can be created simultaniously by different threads. You should however not attempt to create trees and alter the global configuration at the same time or your application might crash.

Return value: pointer to the new tree or NULL if an error occured.
Note: use TreeLib::getAttributecv(NULL,TL_ERROR) to receive an error string.


TreeLib::Tree	TreeLib::createTreeFromSeed(int seed);

Creates a new tree using the current global configuration and the specified seed. This function does not execute any OpenGL commands. A valid context is thus not needed at this point.
Trees can be created simultaniously by different threads. You should however not attempt to create trees and alter the global configuration at the same time or your application might crash.

Return value: pointer to the new tree or NULL if an error occured.
Note: use TreeLib::getAttributecv(NULL,TL_ERROR) to receive an error string.


void	TreeLib::discardTree(TreeLib::Tree tree)

Discards a created tree. This function requires a valid OpenGL context if the tree was rendered at least once.
The specified tree is required to be valid. No validation check is performed to check its integrity. The pointer may be NULL though causing the function to return.


void	TreeLib::rebuildTree(TreeLib::Tree tree)

Rebuilds the specified tree using the current tree configuration. If the configuration was not changed then the resulting tree will be identical to the original created one. This function does not execute any OpenGL commands. A valid context is thus not needed at this point.
The specified tree is required to be valid. No validation check is performed to check its integrity. The pointer may be NULL though causing the function to return.



float			TreeLib::getAttributef(TreeLib::Tree tree, TreeLib::Attribute attribute)
const float*	TreeLib::getAttributefv(TreeLib::Tree tree, TreeLib::Attribute attribute)
int				TreeLib::getAttributei(TreeLib::Tree tree, TreeLib::Attribute attribute)
const char*		TreeLib::getAttributecv(TreeLib::Tree tree, TreeLib::Attribute attribute)

Retrieves the respective attribute from the current configuration. If the specified tree is not NULL then the configuration of the specified tree is queried, otherwise the global configuration.
Certain attributes can only be queried from trees, others only globaly. For more information on this check the attribute specification. This function does not execute any OpenGL commands. A valid context is thus not needed at this point.
The specified tree is required to be valid or NULL. No validation check is performed to check its integrity.

Return value: value of the respective attribute or 0/NULL if the attribute was not readable.
Note: use TreeLib::getAttributecv(NULL,TL_ERROR) to receive an error string.



bool TreeLib::setAttributef(TreeLib::Tree tree, TreeLib::Attribute attribute, float value)
bool TreeLib::setAttributefv(TreeLib::Tree tree, TreeLib::Attribute attribute, const float*value)
bool TreeLib::setAttributei(TreeLib::Tree tree, TreeLib::Attribute attribute, int value)
bool TreeLib::setAttributecv(TreeLib::Tree tree, TreeLib::Attribute attribute, const char*value)

Alters the respective attribute of the current configuration. If the specified tree is not NULL then the configuration of the specified tree is altered, otherwise the global configuration.
Changes to the global configuration will affect all subsequently created trees.
Certain attributes can only be altered locally, others only globaly. For more information on this check the attribute specifications.
Note that modifications to a tree's configuration take effect when it is rebuilt via rebuildTree(tree) the next time.
This function does not execute any OpenGL commands. A valid context is thus not needed at this point.
The specified tree is required to be valid or NULL. No validation check is performed to check its integrity.

Return value: true on success, false otherwise.
Note: use TreeLib::getAttributecv(NULL,TL_ERROR) to receive an error string.



bool	TreeLib::pushAttributes()

Pushes the current global configuration on the top of the configuration stack.
This function does not execute any OpenGL commands. A valid context is thus not needed at this point.
The function returns if the configuration stack is full.
The current implementation provides a stack depth of 0x100 (=256) which should be sufficient for most applications.
This function is thread-safe.

Return value: true if the configuration could be pushed to the stack, false otherwise.


bool	TreeLib::popAttributes()

Overwrites the current global configuration with the configuration stored on the top of the configuration stack.
The function returns if no configurations were stacked.
This function is thread-safe.

Return value: true if the configuration could be popped from the stack, false otherwise.




bool	TreeLib::putTree(TreeLib::Tree tree, const float position[3], const float up[3], const float right[3])

Inserts the specified tree into the current composition using the specified orientation.
[position] describes the desired tree position, [up] its up axis and [right] its X axis. [up] and [right] are required to be normalized and orthogonal. No check or normalization is performed to gain performance. Rendering a tree with broken orientation or coordinates may result in undesired effects up to crashes.
The same tree may be inserted any number of times at different locations.
At this point no valid OpenGL context is required.
The specified tree is required to be valid. No validation check is performed to check its integrity. The pointer may be NULL though causing the function to simply return.
For performance reasons this function is NOT thread-safe.



void	TreeLib::flushComposition()

Clears the active composition without rendering.
This function is thread-safe and can be called from different threads.



bool	TreeLib::renderComposition()

Renders and flushes the active composition. The library uses on the fly compilation generating detail as needed.
For rendering a valid OpenGL context is required or the function will fail.
This function is thread-safe and can be called from different threads.
You should, however, not attempt to modify the tree while rendering it or your application may crash.
Once rendered, the active composition is flushed and has to be re-composed using TreeLib::putTree(...).

Return value: true on success, false otherwise.


bool	TreeLib::renderCompositionBranches()

Renders the branches of the currently active composition. The library uses on the fly compilation meaning that detail levels are not generated until needed.
For rendering a valid OpenGL context is required or the function will fail.
This function is thread-safe and can be called from different threads.
You should, however, not attempt to modify the tree while rendering it or your application may crash.
Unlike TreeLib::renderComposition(), this function does not flush the active composition.
The client application is responsible for manually flushing the composition by calling TreeLib::flushComposition().

By default TreeLib will install its own shader if a third bump-mapping texture is provided, thus overriding any custom shader. If You instead wish to provide Your own shader then You can disable bark shaders by setting the global TL_USE_BARK_SHADERS attribute to 0.
Vertex, normal and texcoords are provided via their respective vertex channels, the tangent required for normal mapping is passed as 3d GL_TEXTURE1 texcoords.

Return value: true on success, false otherwise.



bool	TreeLib::renderCompositionLeaves()

Renders the leaves of the currently active composition.
For rendering a valid OpenGL context is required or the function will fail.
This function is thread-safe and can be called from different threads.
You should, however, not attempt to modify the tree while rendering it or your application may crash.
Unlike TreeLib::renderComposition(), this function does not flush the active composition.
The client application is responsible for manually flushing the composition by calling TreeLib::flushComposition().

Leaf rendering strategies
TreeLib provides a total of three leaf rendering strategies or may simply prepare data in accordance to these strategies.
These strategies may be set via the global TL_RENDER_STRATEGY attribute:

TL_CPU_TRANSFORM
Vertex transformations are performed on the CPU, avoiding the use of shaders or the preparation of any information that can be used by custom shaders to increase performance. By default this mode is used only if shader objects are unavailable.

TL_COLLAPSED_QUADS_SHADER
Moves vertex transformations to the vertex shader. The leaves are recorded to display lists and rendered as quads with all four vertices located in the center of the leaf patch. The distinctive vertices are generated from the z and w coordinate of the GL_TEXTURE0 texture coordinates. While the x and y texture components contain the actual texture coordinates, z and w contain the x and y (eye-space) coordinate difference of the respective vertex from the leaf center.
This strategy also installs an appropriate shader which supports lighting and fog but no bump-mapping.
You can, instead, set the used strategy to TL_COLLAPSED_QUADS, which will not alter the currently installed shader but provide the above data.

TL_POINTS_SHADER
Moves vertex transformations to the geometry shader. The leaves are recorded to display lists and rendered as points with one point per leaf patch. The geometry shader then converts these points to quads optically identical to the above methods.
To generate the four vertices, two 2d vectors are provided as the GL_TEXTURE0 texture coordinates. The x and y components form the horizontal eye-space translation, the z and w components the vertical eye-space translation. The four vertices are constructed by adding or subtracting these vectors to the modelview-projected point coordinates.
This strategy also installs an appropriate shader which supports lighting and fog but no bump-mapping.
You can, instead, set the used strategy to TL_POINTS, which will not alter the currently installed shader but provide the above data.

Return value: true on success, false otherwise.





bool	TreeLib::renderCompositionShadows()

Renders the shadows of the currently active composition.
For rendering a valid OpenGL context is required or the function will fail.
This function is thread-safe and can be called from different threads.
You should, however, not attempt to modify the tree while rendering it or your application may crash.
Unlike TreeLib::renderComposition(), this function does not flush the active composition.
The client application is responsible for manually flushing the composition by calling TreeLib::flushComposition().

Return value: true on success, false otherwise.


bool	TreeLib::renderCompositionImposters()

Renders the imposters of the currently active composition. Trees that are considered in range for imposters are not rendered during the previous steps. Imposters technically have no branches, leaves or shadows and simply consist of two textures: a color and a normal map.
Depending on the availability of Shader Objects or Frame Buffer Objects, imposters may look different or be avoided altogether.
For rendering a valid OpenGL context is required or the function will fail.
This function is thread-safe and can be called from different threads.
You should, however, not attempt to modify the tree while rendering it or your application may crash.
Unlike TreeLib::renderComposition(), this function does not flush the active composition.
The client application is responsible for manually flushing the composition by calling TreeLib::flushComposition().

Return value: true on success, false otherwise.


bool	preloadGlobalTextures()

By default textures are loaded when first linked but this may cause lag in inappropriate times if the textures are of significant size.
To prevent this textures can be preloaded. 
preloadGlobalTextures() loads the textures that are currently specified via the TL_BARK_TEXTURE, TL_BARK_BUMP_MAP, and TL_LEAF_TEXTURE attributes.
This function is thread-safe and can be called from different threads.

Return value: true on success, false otherwise.


int		preloadTexture(const char*filename, bool equalize)

Preloads an individual texture. [filename] specifies the library-relative path to the image file. [equalize] may be set to fill all fully transparent pixels with the average color of all non-transparent pixels. This may seem meaningless but experience has shown that the colors of invisible pixels can affect the colors of visible ones in lower mipmapping layers. Set this to true if You encounter black or white borders on leaf patch textures. Not necessary on bark textures.



	extern _preloadNormalMap			preloadNormalMap;















Attribute specifications:

TL_ERROR

Global only attribute. Read only. getAttributecv(...) only.
Returns a string describing the most recently occured error.


TL_VERSION

Global only attribute. Read only. getAttributecv(...) or getAttributei(...).
getAttributecv(...) returns a string representation of the current version.
getAttributei(...) returns an integer containing the current version number.


TL_FACES

Tree only attribute. Read only. getAttributei(...) or getAttributef(...)
Returns an integer containing the number of triangles of the branch-surface of the specified tree (not including the number of leaves it has).
This value is zero until the tree is rendered the first time.
If the tree is rendered in different detail steps then the returned value will be the sum of all faces in all generated detail steps to this point.


TL_NODES

Tree only attribute. Read only. getAttributei(...) or getAttributef(...)
Returns an integer containing the number of nodes the specified tree has.


TL_LEAVES

Tree only attribute. Read only. getAttributei(...) or getAttributef(...)
Returns an integer containing the number of leaf batches the specified tree has.


TL_BOX_LOWER_CORNER

Tree only attribute. Read only. getAttributefv(...) only.
Returns a pointer to the vector containing the lower corner of the surrounding bounding box.
The returned pointer contains three elements. Note: can be NULL if an error occured.


TL_BOX_UPPER_CORNER

Tree only attribute. Read only. getAttributefv(...) only.
Returns a pointer to the vector containing the upper corner of the surrounding bounding box.
The returned pointer contains three elements. Note: can be NULL if an error occured.


TL_CENTER

Tree only attribute. Read only. getAttributefv(...) only.
Returns a pointer to the vector containing the center of the surrounding bounding box.
The returned pointer contains three elements. Note: can be NULL if an error occured.


TL_RADIUS

Tree only attribute. Read only. getAttributef(...) or getAttributei(...).
Returns a float containing the distance from the center of the tree to its outer most leaf/branch.


TL_SEED

Tree only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the seed value of the respective tree. Setting or querying the global seed has no effect.
After setting the tree seed the tree needs to be rebuild for the changes to take effect.
Note that two trees using the same seed will only be identical if all other attributes are the same, too.


TL_SHADOW

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the shadow setting of the global or local tree configuration.
Currently supported values are:
	TL_NO_SHADOW		shadows disabled
	TL_FLAT_BLOB_SHADOW	simple planar blob shadow below the tree and leaf batches
	TL_CONICAL_BLOB_SHADOW	simple conical blob shadow below the tree and leaf batches
The global shadow attribute is TL_CONICAL_BLOB_SHADOW by default.


TL_AUTO_BALANCE

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the auto-balance setting of the global or local tree configuration.
After changing the auto balance attribute the tree needs to be rebuild for the changes to take effect.
Can be 0 (disabled) or 1 (enabled).
If auto balancing is enabled then an updated tree will be bend so that the weight is roughly balanced.
Auto balancing is enabled by default.


TL_ROTATE_LEAVES

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the rotate-leaves setting of the global or local tree configuration.
Can be 0 (disabled) or 1 (enabled).
If leaf rotation is enabled then tree leaf batches will be rotated so that they appear less repetitive.
Leaf rotation is enabled by default.


TL_BARK_TEXTURE

General attribute. Read and write. getAttributef(...), getAttributei(...), getAttributecv(...), setAttributef(...), setAttributei(...), setAttributecv(...).
Queries or sets the bark texture of the global or local tree configuration.
The texture may be specified as filename (string) or OpenGL texture handle (integer). The respective texture is attempted to load the next time it is needed.
Note: filenames are relative to the directory that the dll resides in.

TL_BARK_BUMP_MAP

General attribute. Read and write. getAttributef(...), getAttributei(...), getAttributecv(...), setAttributef(...), setAttributei(...), setAttributecv(...).
Queries or sets the bark bump map of the global or local tree configuration.
The texture may be specified as filename (string) or OpenGL texture handle (integer). The respective texture is attempted to load the next time it is needed. If the bump map is specified as a string then the respective file should contain a grey-scale height map of the material with black=low and white=high. If it's specified as an integer then it should contain a compiled normal map with z pointing up from the texture plane.
Note: filenames are relative to the directory that the dll resides in.


TL_LEAF_TEXTURE

General attribute. Read and write. getAttributef(...), getAttributei(...), getAttributecv(...), setAttributef(...), setAttributei(...), setAttributecv(...).
Queries or sets the leaf texture of the global or local tree configuration.
The texture may be specified as filename (string) or OpenGL texture handle (integer). The respective texture is attempted to load the next time it is needed.
Note: filenames are relative to the directory that the dll resides in.



TL_LOD

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the lod (level of detail) setting of the global or local tree configuration.
After setting the tree lod the tree needs to be rebuild for the changes to take effect.
This value affects the amount of visible faces on all detail levels when rendering the tree.
The level of detail is set to 1.0 by default. Setting it to a higher value will increase the number of faces (setting it to 2.0 will increase the number of faces by a factor of 4, setting it to 0.5 will decrease the number of faces to 1/4).


TL_LEAF_SIZE

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the leaf batch size setting of the global or local tree configuration.
This value affects the visible size of leaf batches while rendering.
0.5 by default.


TL_BASE_LENGTH

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the fractal trunk root length (distance to the next node).
After setting the tree base length the tree needs to be rebuild for the changes to take effect.
Altering this value will cause the tree to stretch or shrink.
1.25 by default.


TL_BASE_RADIUS

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the fractal root node radius.
After setting the tree base radius the tree needs to be rebuild for the changes to take effect.
Altering this value will cause the tree to have thicker or thinner branches.
0.25 by default.


TL_VARIANCE

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the fractal growth noise level.
After setting the tree variance the tree needs to be rebuild for the changes to take effect.
Less variance means more straight branches, more variance means more bent branches.
0.125 by default


TL_SUCCESSOR_RADIUS_SCALE

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the fractal successor radius scale.
After setting the tree successor radius scale the tree needs to be rebuild for the changes to take effect.
0.8 by default


TL_SUCCESSOR_LENGTH_SCALE

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the fractal successor length scale.
After setting the tree successor length scale the tree needs to be rebuild for the changes to take effect.
0.9 by default


TL_BRANCH_RADIUS_SCALE

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the fractal branch radius scale.
After setting the tree branch radius scale the tree needs to be rebuild for the changes to take effect.
0.56 by default


TL_BRANCH_LENGTH_SCALE

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the fractal branch length scale.
After setting the tree branch length scale the tree needs to be rebuild for the changes to take effect.
0.81 by default


TL_BRANCH_MIN_DEVIATION

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the minimum angle between branch siblings (0-360).
After setting the tree branch minimum deviation the tree needs to be rebuild for the changes to take effect.
40 by default
Warning: setting this value higher than 80 may cause tree generation to get stuck in an endless loop.


TL_VERTICAL_ORIENTATION

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the vertical growth orientation.
After setting the tree vertical orientation the tree needs to be rebuild for the changes to take effect.
Assigning a positive value will cause the tree to grow more upwards, giving it a negative value will cause the branches to lean more towards the ground.
2.5 by default


TL_SHADOW_CONE_STEEPNESS

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the shadow cone steepness.
This value takes effect if shadow is set to TL_CONICAL_BLOB_SHADOW. It specifies the steepness of the shadow cone per unit length.
0.1 by default


TL_MAX_VIEWING_DISTANCE

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the maximum viewing distance.
This value specifies the absolute maximum viewing distance of all trees. If a tree's effective distance exceeds this value then
it will not be rendered.
600 by default


TL_SCALE

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the general scenery scale.
After changing the scale attribute all previously constructed trees need to be rebuild for the changes to take effect.
This value affects all other linear values, be they tree trunk/branch length, shadow size, or max viewing distance.
1 by default


TL_ANISOTROPY

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the general texture anisotropy value.
Changing this value will only affect textures that are loaded from this point on. Previously loaded textures are not affected.
2 by default


TL_IMPOSTER_RANGE

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the imposter radius. Trees further away than this distance (from the camera location) are rendered as imposters rather than geometry. The changes take effect immediately and affect all trees.
100 by default



TL_RENDER_STRATEGY

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the active leaf rendering strategy.
TL_BEST_AVAILABLE by default
TreeLib provides a total of three leaf rendering strategies or may simply prepare data in accordance to these strategies:

* TL_CPU_TRANSFORM
Vertex transformations are performed on the CPU, avoiding the use of shaders or the preparation of any information that can be used by custom shaders to increase performance. By default this mode is used only if shader objects are unavailable.

* TL_COLLAPSED_QUADS
& TL_COLLAPSED_QUADS_SHADER
Moves vertex transformations to the vertex shader. The leaves are recorded to display lists and rendered as quads with all four vertices located in the center of the leaf patch. The distinctive vertices are generated from the z and w coordinate of the GL_TEXTURE0 texture coordinates. While the x and y texture components contain the actual texture coordinates, z and w contain the x and y (eye-space) coordinate difference of the respective vertex from the leaf center.
TL_COLLAPSED_QUADS just prepares the data, TL_COLLAPSED_QUADS_SHADER also installs an appropriate shader that supports lighting and fog but no bump-mapping.
If shader objects are unavailable then TL_COLLAPSED_QUADS_SHADER will automatically fall back to TL_CPU_TRANSFORM.

* TL_POINTS
& TL_POINTS_SHADER
Moves vertex transformations to the geometry shader. The leaves are recorded to display lists and rendered as points with one point per leaf patch. The geometry shader then converts these points to quads optically identical to the above methods.
To generate the four vertices, two 2d vectors are provided as the GL_TEXTURE0 texture coordinates. The x and y components form the horizontal eye-space translation, the z and w components the vertical eye-space translation. The four vertices are constructed by adding or subtracting these vectors to the modelview-projected point coordinates.
TL_POINTS just prepares the data, TL_POINTS_SHADER also installs an appropriate shader that supports lighting and fog but no bump-mapping.
If geometry shaders are unavailable then TL_POINTS_SHADER will automatically fall back to TL_COLLAPSED_QUADS_SHADER.

* TL_BEST_AVAILABLE
This strategy is automatically replaced with the fastest available strategy on the target system:
TL_POINTS_SHADER if both shader objects and geometry shaders are available,
TL_COLLAPSED_QUADS_SHADER if shader objects but no geometry shaders are available,
TL_CPU_TRANSFORM if no shader objects are available.
This decission takes place when the leaf composition is rendered the first time. Querying TL_RENDER_STRATEGY after rendering the first time will return the actually used strategy.



TL_IMPOSTER_RESOLUTION

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the current imposter texture resolution (width&height).
Changing this attribute will affect all imposters that are generated from this point on. You can force a global imposter resolution change by rebuilding all trees.
Experience has shown that 128 should be the upper limit due to the lack of mipmapping.
128 by default


TL_MAX_IMPOSTERS_PER_FRAME

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the maximum imposter generation count per frame.
This attribute can be used to throttle the imposter generation if imposters take too long to generate.
5 by default




TL_VERTEX_PATH

Tree only attribute. Read only. getAttributefv(...) only.
Queries the vertex data of the specified tree in the current level of detail. The returned float array contains position, normal, tangent and texcoords for each vertex in the following order:
x1, y1, z1, nx1, ny1, nz1, tx1, ty1, tz1, u1, v1,    x2, y2, z2, nx2, ny2, nz2, tx2, ty2, tz2, u2, v2, ...
The returned array is allocated per tree and is valid until the tree is rebuilt or deleted. Do not attempt to manually delete this array.
To query the number of vertices in the path use TL_VERTEX_PATH_LENGTH. The total length of the returned array is vertices*11.


TL_VERTEX_PATH_LENGTH

Tree only attribute. Read only. getAttributei(...) only.
Queries the number of vertices in the vertex path returned by getAttributefv(tree,TL_VERTEX_PATH).
The returned value remains correct until the tree is rebuilt.


TL_INDEX_PATH

Tree only attribute. Read only. getAttributeiv(...) only.
Queries the index data of the specified tree in the current level of detail. The returned int array contains the vertex indices of the tree branch triangles.
Each three indices of the returned array form one triangle.
The returned array is allocated per tree and is valid until the tree is rebuilt or deleted. Do not attempt to manually delete this array.
To query the number of indices in the path use TL_INDEX_PATH_LENGTH.


TL_INDEX_PATH_LENGTH

Tree only attribute. Read only. getAttributei(...) only.
Queries the number of indices in the index path returned by getAttributeiv(tree,TL_INDEX_PATH).
The returned value remains correct until the tree is rebuild. Note that the returned int contains the number of indices, not triangles.
The number of triangles is indices/3.


TL_LEAF_PATH

Tree only attribute. Read only. getAttributefv(...) only.
Queries the leaf data of the specified tree. The returned array contains the central position of each leaf in x-y-z-order, with each three floats per leaf.
The returned array is allocated per tree and is valid until the tree is rebuilt or deleted. Do not attempt to manually delete this array.
To query the number of leafs in the path use TL_LEAVES. The total length of the returned array is leaves*3. To query the size of the leaves use TL_LEAF_SIZE.



License:

This is a beta-state of the provided library and may as such be distributed and used as pleased as long as the original runtime-behavior of the library is preservered. Any (re)distribution of the library must be free of charges.

This library is provided as is, meaning that no guarantee what so ever is issued regarding runtime-stability and/or damage it may or may not cause.

Modification of the binary library-file is strictly forbidden, including but not limited to disassembly and/or reverse-programming. Also distribution without an unchanged copy of this file is forbidden.

All rights and privileges that have not explicitly been granted are reserved.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.