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);

* Requires OpenGL: No
* Thread safe: No

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();

* Requires OpenGL: No
* Thread safe: Yes

Creates a new tree using the current global configuration and a random seed.
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);

* Requires OpenGL: No
* Thread safe: Yes

Creates a new tree using the current global configuration and the specified seed.
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)

* Requires OpenGL: *
* Thread safe: Yes

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)

* Requires OpenGL: *
* Thread safe: Yes

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



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)

* Requires OpenGL: No
* Thread safe: Yes

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

* Requires OpenGL: No
* Thread safe: Yes

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.
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()

* Requires OpenGL: No
* Thread safe: Yes

Pushes the current global configuration on the top of the configuration stack.
The function returns false if the configuration stack is full.
The current implementation provides a stack depth of 0x100 (=256) which should be sufficient for most applications.

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


bool	TreeLib::popAttributes()

* Requires OpenGL: No
* Thread safe: Yes

Overwrites the current global configuration with the configuration stored on the top of the configuration stack.
The function returns false if no configurations were stacked.

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



int	TreeLib::saveAttributes()

* Requires OpenGL: No
* Thread safe: Yes

Saves the current global configuration to a dedicated configuration slot. The returned integer represents the saved configuration slot for later reference.
The function returns 0 if the library has not been properly initialized.

Return value: Index of the newly created attribute slot or 0 if the library has not been initialized. The same index is not returned twice even if the respective slot has been deleted.
(Unless you allocate more than 0xFFFFFFFF slots and then odd things may happen)


bool	TreeLib::loadAttributes(TreeLib::Tree, int configuration)

* Requires OpenGL: No
* Thread safe: Yes

Loads a previously saved configuration to the global or tree local configuration.
The first attribute specifies the target tree or NULL if the global configuration should be restored. No validation check is performed.
If a tree's configuration has been altered then the respective tree must be rebuilt for the changes to take effect.
If the specified configuration is invalid then the function returns false.
Passing 0 will cause the function to return true but not perform any operation.

Return value: true on success.



bool	TreeLib::freeAttributes(int configuration)

* Requires OpenGL: No
* Thread safe: Yes

Frees the space required by a previously saved configuration. The specified index becomes invalid and can no longer be loaded.
If the specified configuration is invalid then the function returns false.
Passing 0 will cause the function to return true but not perform any operation.

Return value: true on success.



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

* Requires OpenGL: No
* Thread safe: NO

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.
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()

* Requires OpenGL: No
* Thread safe: Yes

Clears the active composition without rendering.
This function should be invoked only if rendering certain aspects explicitly (i.e. renderCompositionBranches()) without invoking renderComposition().
If neither renderComposition() nor this function is invoked then the render stack will continue to consume memory until the program dies out of lack of FPS or memory, whichever comes first.



bool	TreeLib::renderComposition()

* Requires OpenGL: Yes
* Thread safe: Yes

Renders and flushes the active composition. The library uses on the fly compilation to generate 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()

* Requires OpenGL: Yes
* Thread safe: Yes

Renders the branches of the currently active composition. The library uses on the fly compilation to generate 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.
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.

Passed vertex attributes are:

base: gl_Vertex, gl_Normal, gl_Color (white)
tex0: gl_MultiTexCoord0.xy (generic texcoords), .z (strength of wind), .w (phase of wind)
tex1: gl_MultiTexCoord1.xyz (tangent)
tex2: gl_MultiTexCoord2.xyz (object space wind vector)

Return value: true on success, false otherwise.



bool	TreeLib::renderCompositionLeaves()

* Requires OpenGL: Yes
* Thread safe: Yes

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()

* Requires OpenGL: Yes
* Thread safe: Yes

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()

* Requires OpenGL: Yes
* Thread safe: Yes

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()

* Requires OpenGL: Yes
* Thread safe: Yes

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)

* Requires OpenGL: Yes
* Thread safe: Yes

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.

Return value: OpenGL texture object index on success, 0 otherwise.


int	preloadNormalMap(const char*filename)

* Requires OpenGL: Yes
* Thread safe: Yes

Similar to the above for normal maps. The specified file is expected to contain a greyscale bump-map.

Return value: OpenGL texture object index on success, 0 otherwise.








Attribute specifications:

TL_ERROR

* Domain: Global
* Type: String
* Accessibility: Read

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


TL_VERSION

* Domain: Global
* Type: String/Int
* Accessibility: Read

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

* Domain: Tree
* Type: Int
* Accessibility: Read

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

* Domain: Tree
* Type: Int
* Accessibility: Read

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


TL_LEAVES

* Domain: Tree
* Type: Int
* Accessibility: Read

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

* Domain: Tree
* Type: Float3
* Accessibility: Read

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

* Domain: Tree
* Type: Float3
* Accessibility: Read

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

* Domain: Tree
* Type: Float3
* Accessibility: Read

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

* Domain: Tree
* Type: Float
* Accessibility: Read

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

* Domain: Tree
* Type: Int
* Accessibility: Read&Write

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

* Domain: Tree and Global
* Type: Int
* Accessibility: Read&Write

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

* Domain: Tree and Global
* Type: Int
* Accessibility: Read&Write

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

* Domain: Tree and Global
* Type: Int
* Accessibility: Read&Write

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

* Domain: Tree and Global
* Type: Int/String
* Accessibility: Read&Write

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

* Domain: Tree and Global
* Type: Int/String
* Accessibility: Read&Write

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

* Domain: Tree and Global
* Type: Int/String
* Accessibility: Read&Write

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_AGE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

Queries or sets the tree age (in years) of the global or local tree configuration.
After setting the tree age the tree needs to be rebuild for the changes to take effect.
This value affects the length, thickness and number of branches as well as the number of leaves.
Does not affect the size of leaves.
30.0 by default.



TL_LOD

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

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).
1.0 by default.


TL_LOD_FALLOFF

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the LOD falloff factor. 1.0 causes the LOD layers to drop im multiples of 4 times the tree radius. While the observer is inside this range the tree renders at maximum detail. Increading the falloff value will increase this core sphere as well as the radius of all lower detail layers.
1.0 by default.


TL_LEAF_SIZE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

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.
1.2 by default.


TL_SEGMENT_LENGTH

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the general branch segment length.
After setting the branch segment length the tree needs to be rebuild for the changes to take effect.
Altering this value will cause the tree to have longer or shorter branches.
1.0 by default.


TL_GENERATION_RADIUS

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the generation based radius gain of tree branches.
After setting the branch segment length 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 depending on the age of the respective branch.
0.01 by default.


TL_VARIANCE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

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 randomly bent branches.
0.3 by default


TL_LOWER_MIN_DEVIATION

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the lower sibling deviation angle.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
This value specifies the absolute minimum angle between two sibling branches.
PI/16 by default.


TL_UPPER_MIN_DEVIATION

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the upper sibling deviation angle.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
This value specifies the upper deviation angle between two sibling branches. Branches above this barrier are not affected by their siblings. Branches below are penalized.
PI/8 by default.


TL_IDEAL_CHILD_DEVIATION

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the ideal child deviation angle.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
This value specifies the ideal deviation of a branch from his parent branch node. Branches are penalized depending on their deviation from this angle.
PI/4 by default.


TL_CHILD_DEVIATION_TOLERANCE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the child deviation tolerance angle.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
This value specifies the tolerance angle regarding the ideal deviation of a branch from his parent branch node. Branches cannot deviate further than this angle from the ideal child angle.
PI/4 by default.



TL_VERTICAL_ORIENTATION

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the vertical axis influence on the calculation of a succeeding branch node.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
The higher this value the more branches will lean upwards.
0.2 by default.


TL_FLEETING_ORIENTATION

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the directional axis influence on the calculation of a succeeding branch node.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
The higher this value the more branches will lean away from their respective root node (not necessarily up).
0.4 by default.


TL_MIN_BRANCH_AGE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the lower branch TTL (time to live) constraint.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
Increasing or decreasing this value will affect how long branches live (at least) after their creation.
Branches that exceed their maximum age will not grow further. Branches that exceed their maximum age by a factor of three are removed. The tree trunk is excluded from this rule.
5 by default.


TL_MAX_BRANCH_AGE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the upper branch TTL (time to live) constraint.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
Increasing or decreasing this value will affect how long branches live (at most) after their creation.
Branches that exceed their maximum age will not grow further. Branches that exceed their maximum age by a factor of three are removed. The tree trunk is excluded from this rule.
20 by default.


TL_LEAF_IDEAL_BRANCH_AGE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the ideal branch age for leaves.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
Leaves are of the same size for the entire tree but their positioning is propability based.
Leaves are put to all branch ends and preferably to nodes close to this age.
6 by default.


TL_LEAF_BRANCH_AGE_TOLERANCE

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the ideal branch age tolerance of leaves.
After setting this attribute the tree needs to be rebuild for the changes to take effect.
Specifies the maximum tolerance of branch nodes to grow leaves. Nodes whoes age difers from the ideal leaf age by more than this value are excluded from leaf generation.
Branch end nodes are an exception to this rule.
Increasing this value increases the propability of a branch node to grow a leaf.
8 by default, effectivly giving branches up to an age of 14 a chance to grow a leaf.



TL_SHADOW_CONE_STEEPNESS

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

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_BOTTOM_CAP_STEEPNESS

* Domain: Tree and Global
* Type: Float
* Accessibility: Read&Write

General attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the tree trunk bottom cap cone steepness.
This value takes effect if TL_BOTTOM_CAP is set to TL_POINTY_CAP. It specifies the steepness of the bottom cap cone per unit length.
1.0 by default





TL_MAX_VIEWING_DISTANCE

* Domain: Global
* Type: Float
* Accessibility: Read&Write

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.0 by default


TL_SCALE

* Domain: Global
* Type: Float
* Accessibility: Read&Write

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.0 by default.


TL_ANISOTROPY

* Domain: Global
* Type: Float
* Accessibility: Read&Write

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.0 by default.


TL_IMPOSTER_RANGE

* Domain: Global
* Type: Float
* Accessibility: Read&Write

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.0 by default.


TL_SNOW_DENSITY

* Domain: Global
* Type: Float
* Accessibility: Read&Write

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Queries or sets the global snow density in the range [0.0,1.0]. The greater this value the more the branches and leaves will be covered by snow and ice depending on their vertical orientation.
For this value to take effect shader objects must be available.
0.0 by default.


TL_WIND

* Domain: Global
* Type: Float3
* Accessibility: Read&Write

Global only attribute. Read and write. getAttributefv(...), setAttributefv(...)
Queries or sets the global wind direction/intensity vector. The greater this vector, the more leaves and branches will lean along the specified wind direction. Setting this vector to {0,0,0} will disable wind. The transformations are simple attribute based linear vertex translations performed by the shaders. Shader objects must be available for wind calculations to be successful. If shader compilation fails for some reason then the wind is set to {0,0,0} automatically.
{0.5,0,0} by default.





TL_RENDER_STRATEGY

* Domain: Global
* Type: Int
* Accessibility: Read&Write

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

* Domain: Global
* Type: Int
* Accessibility: Read&Write

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

* Domain: Global
* Type: Int
* Accessibility: Read&Write

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_USE_BARK_SHADERS

* Domain: Global
* Type: Int
* Accessibility: Read&Write

Global only attribute. Read and write. getAttributef(...), getAttributei(...), setAttributef(...), setAttributei(...).
Enables or disables bark shaders. Set to 1 (enabled) or 0 (disabled).
Enabled by default.


TL_EXPORTED_FLOATS_PER_VERTEX

* Domain: Global
* Type: Int
* Accessibility: Read

Global only attribute. Read only. Constant. getAttributef(...), getAttributei(...).
Queries the number of floats returned per vertex of a vertex path (see next entry).
This value is constant at execution time and identical for all trees.
Returns at least 13.





TL_VERTEX_PATH

* Domain: Tree
* Type: Float*
* Accessibility: Read

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, texcoords, wind strength, and wind phase for each vertex in the following order:
x1, y1, z1, nx1, ny1, nz1, tx1, ty1, tz1, u1, v1, s1, p1,(...)    x2, y2, z2, nx2, ny2, nz2, tx2, ty2, tz2, u2, v2, s2, p2 ...
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 number of floats in the returned array is getAttributei(tree,TL_VERTEX_PATH_LENGTH)*(NULL,TL_EXPORTED_FLOATS_PER_VERTEX).
Future implementations may provide additional information per vertex. It is thus recommended to query the TL_EXPORTED_FLOATS_PER_VERTEX attribute.


TL_VERTEX_PATH_LENGTH

* Domain: Tree
* Type: Int
* Accessibility: Read

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


TL_INDEX_PATH

* Domain: Tree
* Type: Int
* Accessibility: Read

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

* Domain: Tree
* Type: Int*
* Accessibility: Read

Tree only attribute. Read only. getAttributei(...) only.
Queries the number of indices (NOT triangles) 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

* Domain: Tree
* Type: Float*
* Accessibility: Read

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.