This page gives you a quick introduction on how to use the volume component in your project.

Inclusion

The project must link against the OgreVolume.lib and must find the header-files inside <OGRE HOME>/Components/Volume/include.

The following headers must be included, depending on which features you want to use:

#include "OgreVolumeChunk.h"
#include "OgreVolumeCSGSource.h"
#include "OgreVolumeCacheSource.h"
#include "OgreVolumeTextureSource.h"

Scene creation via configuration file

Here is an example loading the volume scene from a configuration file. The configuration file must be findable by the resource system of course. Only "OgreVolumeChunk.h" has to be included.

Chunk *volumeRoot = OGRE_NEW Chunk();
SceneNode *volumeRootNode = mSceneMgr->getRootSceneNode()->createChildSceneNode("VolumeParent");
volumeRoot->load(volumeRootNode, mSceneMgr, "volumeTerrain.cfg");

The first line creates the volume chunk which is the MovableObject holding the Volume-Root. Next, a SceneNode is created where the volume(-tree) is attached to. And lastly, the volume is loaded from the configuration file "volumeTerrain.cfg".
mSceneMgr is the SceneManager who should show the volume. Later, when you don't need it anymore, you have to free the volumeRoot Chunk via OGRE_DELETE.

Manual creation of a CSG-Tree

This example skips the configuration file and loads a simple CSG-Scene: An union of a 3D Texture and a sphere with 5 LOD levels. It also setups a material LOD system. "OgreVolumeChunk.h", "OgreVolumeCSGSource.h" and "OgreVolumeTextureSource.h" must be included.
First, create a sphere with the radius 5 at the coordinates 128, 150, 128:

CSGSphereSource sphere (5, Vector3(128, 150, 128));

Now a 3D texture from "volumeTerrainBig.dds" which has the world dimensions 256, 256, 256. The next flag indicates that the trilinear interpolation of the value-selection should be activated. We switch off the trilinear interpolation and the sobel filter of the normal for the sake of faster loading times:

TextureSource volumeTexture ("volumeTerrainBig.dds", 256, 256, 256, true, false, false);

Now combine them:

CSGUnionSource unionSrc (&sphere, &volumeTexture);

Set the general parameters, see the comments for their meaning:

ChunkParameters parameters;
parameters.sceneManager = mSceneMgr; // The SceneManager to use
parameters.src = &unionSrc; // The just created density source.
parameters.baseError = (Real)1.8; // The error of the highest LOD-level
parameters.errorMultiplicator = (Real)0.9; // The factor between each LOD-level (error = baseError * errorMultiplicator  * level)
parameters.skirtFactor = (Real)0.7; // Controls how long the skirts are. The lower the number, the shorter the skirts are. This saves geometry. But if they are too short, cracks might occure.
parameters.scale = 10; // The displayed volume will be scaled by this factor.
parameters.maxScreenSpaceError = 30; // The screen space error controlling when the LOD-levels change.

Create the root-chunk and load now. The two vectors define the area to be scanned in the volume-source. The following integer determines the amount of LOD-levels.

Chunk *volumeRoot = OGRE_NEW Chunk();
volumeRoot->load(mVolumeRootNode, Vector3::ZERO, Vector3(256), 5, &parameters);

Now setup the global volume material:

volumeRoot->setMaterial("triplanarReferenceHigh");

The three lowest LOD-levels should have a cheaper material:

volumeRoot->setMaterialOfLevel(0, "triplanarReferenceLow");
volumeRoot->setMaterialOfLevel(1, "triplanarReferenceLow");
volumeRoot->setMaterialOfLevel(2, "triplanarReferenceLow");