osgSprites
I. Description
osgSprites is a complete node kit for diplaying large fields of sprite objects in OSG.
The osgSprites library uses a geometry shader to render geometry aligned to screen
space. This has some drawbacks but these are worth the advantages, as it allows the
rendering of one million trees with best of breed graphics gaming cards (2009).
II. Usage
There are three methods for using osgSprites. Programatically, by generating a
.sprites file, or by embedding the Sprites extension in a .osg file. In any case,
osgSprites build the tree forest with two sets of information:
o A Texture Palette.
--------------------
This texture palette is expected to have a palette of RGBA images of sprites. Each image
is referenced by index, starting from the lower left hand corner and counting right. Each
palette will have M rows and N columns, with 1 or more rows and 1 or more columns.
o A list of Sprite Data
The SpriteData consists a list of tuples each with the following pieces of information:
a. width x height the sprite
b. palette index
c. position (X,Y,Z) of the sprite
This information is passed to the osgSprite library by one of the three methods of usage:
A. Using osgSprites Programatically
Use the C++ osgSprites::Sprites interface. Sprites derives from osg::Geode.
The following is an example C++ code example for using
/////////////////////////////////////////////////////////////////////////////////////////////////////////////
static const unsigned int numTrees = 4000;
osg::Geode *loadTrees()
{
// Open the pallete texture
osg::ref_ptr<osg::Image> treePaletteImage = osgDB::readImageFile( "trees.png" );
if( !treePaletteImage.valid() )
{
osg::notify( osg::WARN ) << "Can't open the tree palette image \"trees.png\"" << std::endl;
return NULL;
}
// Make the Palette
osg::ref_ptr<osgSprites::TexturePalette> texturePalette =
new osgSprites::TexturePalette( 1, 5, treePaletteImage.get() );
// Invent some random tree positions
float area = sqrt((double)numTrees)/2.0;
osgSprites::Sprites::SpriteDataList dataList;
for( unsigned int i = 0; i < numTrees; i++ )
{
osgSprites::Sprites::SpriteData treeData;
treeData.width = 2.0f + ((float)(rand()%1000)/1000.0f) * 2.0f;
treeData.height = 4.0f + ((float)(rand()%1000)/1000.0f) * 4.0f;
treeData.paletteIndex = rand() % 5;
treeData.position[0] = -(area*0.5) + ((float)(rand() % 10000)/10000.0f) * area;
treeData.position[1] = -(area*0.5) + ((float)(rand() % 10000)/10000.0f) * area;
treeData.position[2] = 0.0f;
dataList.push_back( treeData );
}
// Create the Sprite Trees
osg::ref_ptr<osgSprites::Sprites> trees = new osgSprites::Sprites( dataList );
trees->setTexturePalette( texturePalette.get() );
/// Hang 'em on a Geode
osg::Geode *geode = new osg::Geode;
geode->addDrawable( trees.get() );
return geode;
}
/////////////////////////////////////////////////////////////////////////////////////////////////////////////
B. Using osgSprites in a .sprites file.
.trees files are XML files with three tags: <Sprite>, <TexturePalette> and <SpriteData>. The following is an
example .sprites file:
<Sprites>
<TexturePalette imageFile="trees.png" numRows="1" numCols="5" />
<SpriteData width="0.7704" height="1.232" paletteIndex="1">
<Position x="-29.255" y="-26.621" z="0" />
</SpriteData>
<SpriteData width="0.7704" height="1.232" paletteIndex="1">
<Position x="-30.053" y="-45.737" z="0" />
</SpriteData>
<SpriteData width="0.7704" height="1.232" paletteIndex="1">
<Position x="-49.823" y="-26.711" z="0" />
</SpriteData>
<SpriteData width="0.7704" height="1.232" paletteIndex="1">
<Position x="-22.484" y="-32.792" z="0" />
</SpriteData>
</Sprites>
The .sprites file is parsed with the osgdb_sprites loader.
C. Extending the .osg file format
The following is an extended .osg file format supporting Sprites:
Geode {
name "example.trees"
nodeMask 0xffffffff
cullingActive TRUE
num_drawables 1
osgSprites::Sprites {
UniqueID Sprites_0
TexturePalette {
fileName "trees.png"
numRows 1
numCols 5
}
Comment {
SpriteData records:
width height paletteIndex X Y Z
}
SpriteData {
0.7704 1.232 1 -2.9255 -2.6621 0
0.7704 1.232 2 -1.0053 -2.5737 0
0.7704 1.232 3 -1.9823 -2.6711 0
0.7704 1.232 4 -2.2484 -1.2792 0
}
}
}
III. Building osgSprites
A. on Non-windows using DWMake
1. In the root directory, type 'make'
% make
2. Install the libraries in their target location (by hand) as appropriate
% sudo cp lib/Linux64/libosgSprites.so@ /usr/local/lib64
% sudo cp lib/Linux64/osgdb_*.so /usr/local/lib64/osgPlugins-2.8.2/
3. Optionally, if you need the development headers
% sudo cp include/osgSprites/ /usr/local/include/
B. Using CMake
If targeting Makefiles, PLEASE MAKE OUT OF SOURCE BUILDS as they will conflict with the
GNUmakefiles of DWMake