Ogre Line Chart        

General


This code snippet demonstrates how to make a line chart in Ogre. The snippet is a combination of a shader that does the drawing and a class that manages the resources for that shader. A demo application is also presented that makes use of the snippet.

The corresponding forum discussion thread can be found here. In case of questions or suggestions, please post there.

The line chart that is drawn looks like this:
Image




The code


This snippet is composed of the following files:

  • The Cg shader that requires PS2.0 support
  • The material script for the shader
  • The header file for the class that manages the resources
  • The source file for the same class



The shader


This is the shader used to draw the line chart. The basic principle of the shader is very simple:

  • Find the index of the current and the next point in the data
  • Find the height of the plot line on the current x position
  • Calculate the alpha value of the current pixel


The fragment shader has four arguments:

  • The data of the chart packed in a 1D gray-scale texture
  • The tint color of the chart
  • The width of the texture
  • The number of points in the texture (might not be the same as the width due to power-of-two padding)


The code is the following:

/*-----------------------------------------------------------------------------
2011, Adis Hamzic
-----------------------------------------------------------------------------*/

struct VertexIn 
{
   float4 position : POSITION;
   float2 texCoord : TEXCOORD0;
};

struct VertexOut
{
   float4 position : POSITION;
   float2 texCoord : TEXCOORD0;
};

VertexOut plotvp(VertexIn input, uniform float4x4 modelViewProj)
{
	//just pass the values through
	VertexOut output;
	output.position = mul(modelViewProj, input.position);
	output.texCoord = input.texCoord;
	return output;
}

struct PixelOut
{
	float4 color : COLOR;
};

PixelOut plotfp(VertexOut input,
	sampler1D points : TEXUNIT0,
	uniform float4 tintColor,
	uniform float texWidth,
	uniform float pointCount)
{
	PixelOut output;
	
	//get the index of the current and the next element in the texture
	//take into account the power-of-two padding for the texture
	//dx - the increment on the x axis
	//lx - the local offset on the x axis
	float dx = 1.0f / (texWidth - 1);
	float index = input.texCoord.x * (pointCount / texWidth);
	float lx = fmod(index, dx);
	index = index - lx;
	float nextIndex = index + dx;
	
	//get the values of the points
	float point = tex1D(points, index).x;
	float nextPoint = tex1D(points, nextIndex).x;
	
	//calculate the increment value on the y axis and the slope
	float dy = nextPoint - point;
	float k = dy / dx;
	
	//get the offset of the current point from the plot line
	float yOffset = lx * k;
	float plotY = yOffset + point;
	float yDistance = plotY - (1.0f - input.texCoord.y);
	
	float alpha = 0.0f;
	if(yDistance < 0)
	{
		//we are above the plot line
		alpha = exp(100.0f * yDistance);
	}
	else
	{
		//we are below the plot line
		float c = yDistance;
		float c2 = c * c;
		float c3 = c2 * c;
		alpha = (1113 * c3 - 586.8 * c2 + 356.9 * c + 49) /
			(c3 + 859.1 * c2 + 321.2 * c + 49.1);
	}
	
	output.color = float4(tintColor.xyz, tintColor.w * alpha);
	return output;
}



The material script


The material script is only used to register the shaders so we can use them in the code easily.

vertex_program Plot/plotvp cg            
{
    source plot.cg
    entry_point plotvp
    profiles vs_2_0 arbvp1
	
	default_params
	{
		param_named_auto modelViewProj worldviewproj_matrix
	}
}

fragment_program Plot/plotfp cg            
{
    source plot.cg
    entry_point plotfp
    profiles ps_2_0 arbfp1
	
	
	default_params
	{
		param_named pointCount float
		param_named texWidth float
		param_named tintColor float4 1 0 0 1
	}
}



The class header


The class managing the resources for our shader is named Plot. This class manages a list of points that will be drawn. A new material is constructed with a user-specified name that can be attached to any object where we wish the chart to be drawn. A short explanation of all the methods is presented below.

/*-----------------------------------------------------------------------------
2011, Adis Hamzic
-----------------------------------------------------------------------------*/

#ifndef _plot_hpp_
#define _plot_hpp_

#include <string>

#include <OgreMaterial.h>
#include <OgreTexture.h>

class Plot
{
public:
	typedef std::list<Ogre::Real> DataType;

public:
	Plot(const std::string& pMaterialName, int pPointCount, Ogre::Real pDefaultValue, bool pAutoscale = true,
		const Ogre::ColourValue& pTintColor = Ogre::ColourValue(1, 0, 0, 1));
	~Plot();

	void addPoint(Ogre::Real pValue);
	void clearPoints();

	const DataType& getData() const;
	void setData(const DataType& pData);

	int getPointCount() const;
	void setPointCount(int pPointCount);

	float getDefaultValue() const;
	void setDefaultValue(Ogre::Real pDefaultValue);

	bool getAutoscale() const;
	void setAutoscale(bool pAutoscale);

	const Ogre::ColourValue& getTintColor() const;
	void setTintColor(const Ogre::ColourValue& pTintColor);

protected:
	void createTexture();
	void updateData();
	void normalizeData();

private:
	Ogre::MaterialPtr m_Material;
	Ogre::TexturePtr m_DataTexture;

	int m_PointCount;
	Ogre::Real m_DefaultValue;
	bool m_Autoscale;
	Ogre::ColourValue m_TintColor;

	DataType m_Data;
};

#endif //_plot_hpp_



The class implementation


The implementation of the above class looks like this:

/*-----------------------------------------------------------------------------
2011, Adis Hamzic
-----------------------------------------------------------------------------*/

#include "Plot.hpp"

#include <algorithm>

#include <OgreMaterialManager.h>
#include <OgreTextureManager.h>
#include <OgreTechnique.h>
#include <OgreHardwarePixelBuffer.h>

Plot::Plot(const std::string& pMaterialName, int pPointCount, Ogre::Real pDefaultValue, 
	bool pAutoscale, const Ogre::ColourValue& pTintColor) :
	m_PointCount(pPointCount), m_DefaultValue(pDefaultValue), m_Autoscale(pAutoscale),
	m_TintColor(pTintColor), m_Data(pPointCount, pDefaultValue)
{
	//create a new material with the given name
	m_Material = Ogre::MaterialManager::getSingleton().create(pMaterialName,
		Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);

	Ogre::Pass* pass = m_Material->getTechnique(0)->getPass(0);
	pass->setSceneBlending(Ogre::SBT_TRANSPARENT_ALPHA);

	pass->setVertexProgram("Plot/plotvp");
	pass->setFragmentProgram("Plot/plotfp");

	Ogre::TextureUnitState* state = pass->createTextureUnitState();
	state->setTextureFiltering(Ogre::TFO_NONE);
	state->setTextureAddressingMode(Ogre::TextureUnitState::TAM_MIRROR);

	createTexture();
	updateData();
}

Plot::~Plot()
{
	m_Material->unload();
	m_DataTexture->unload();
}

void Plot::addPoint(Ogre::Real pValue)
{
	//add a point to the front of the list
	//remove the one on the back to preserve length
	m_Data.push_back(pValue);
	m_Data.pop_front();
	updateData();
}

void Plot::clearPoints()
{
	//set all points to the default value
	for(DataType::iterator i = m_Data.begin(); i != m_Data.end(); ++i)
		*i = m_DefaultValue;
	updateData();
}

const Plot::DataType& Plot::getData() const
{
	return m_Data;
}

void Plot::setData(const Plot::DataType& pData)
{
	//manually set data, updates the number of points used
	//may cause the data texture to be created again
	m_Data = pData;
	m_PointCount = m_Data.size();
	createTexture();
	updateData();
}

int Plot::getPointCount() const
{
	return m_PointCount;
}

void Plot::setPointCount(int pPointCount)
{
	//set the number of points used
	//may cause the data texture to be created again
	m_PointCount = pPointCount;
	m_Data.resize(m_PointCount, m_DefaultValue);
	createTexture();
	updateData();
}

float Plot::getDefaultValue() const
{
	return m_DefaultValue;
}

void Plot::setDefaultValue(Ogre::Real pValue)
{
	//sets the default value
	//use clear to reset all values to it
	m_DefaultValue = pValue;
}

bool Plot::getAutoscale() const
{
	return m_Autoscale;
}

void Plot::setAutoscale(bool pAutoscale)
{
	//should we use autoscaling or did the user do it
	m_Autoscale = pAutoscale;
	updateData();
}

const Ogre::ColourValue& Plot::getTintColor() const
{
	return m_TintColor;
}

void Plot::setTintColor(const Ogre::ColourValue& pTintColor)
{
	//set the color of the chart
	m_TintColor = pTintColor;
	updateData();
}

void Plot::createTexture()
{
	//get a dimension that is a power of two
	// http://graphics.stanford.edu/~seander/bithacks.html#RoundUpPowerOf2
	int textureSize = m_Data.size();
	textureSize--;
	textureSize |= textureSize >> 1;
	textureSize |= textureSize >> 2;
	textureSize |= textureSize >> 4;
	textureSize |= textureSize >> 8;
	textureSize |= textureSize >> 16;
	textureSize++;

	//do we need to recreate the texture
	if(!m_DataTexture.isNull() && textureSize != m_DataTexture->getWidth())
	{
		m_DataTexture->unload();
		m_DataTexture.setNull();
	}

	if(m_DataTexture.isNull())
	{
		//create a new texture and add it to the material
		std::string textureName = "DataTextureFor" + m_Material->getName();
		m_DataTexture = Ogre::TextureManager::getSingleton().createManual(textureName,
			Ogre::ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME, Ogre::TEX_TYPE_1D,
			textureSize, 1, 0, Ogre::PF_L8);
		m_Material->getTechnique(0)->getPass(0)->getTextureUnitState(0)->setTextureName(textureName);
	}
}

void Plot::normalizeData()
{
	//get buffer to the data texture
	Ogre::HardwarePixelBufferSharedPtr buffer = m_DataTexture->getBuffer();
	buffer->lock(Ogre::HardwareBuffer::HBL_NORMAL);
	Ogre::uint8* data = (Ogre::uint8*)buffer->getCurrentLock().data;

	if(m_Autoscale)
	{
		//if we are using autoscale, get the axis span used for scaling
		std::pair<DataType::iterator, DataType::iterator> minMaxElement = 
			std::minmax_element(m_Data.begin(), m_Data.end());
		Ogre::Real minElement = *minMaxElement.first;
		Ogre::Real maxElement = *minMaxElement.second;
		Ogre::Real span = maxElement - minElement;

		if(span > 0.0001f)
		{
			//scale using the span to [0, 1]
			int dataI = 0;
			for(DataType::iterator i = m_Data.begin(); i != m_Data.end(); ++i, ++dataI)
				data[dataI] = Ogre::uint8(((*i - minElement) / span) * 255);
		}
		else
		{
			//the span is too small, fill values with zeros
			memset(buffer->getCurrentLock().data, 0, buffer->getSizeInBytes());
		}
	}
	else
	{
		//not using autoscaling, use raw values, but clamp them first to avoid overflowing
		int dataI = 0;
		for(DataType::iterator i = m_Data.begin(); i != m_Data.end(); ++i, ++dataI)
		{
			Ogre::Real value = *i;
			if(value > 1.0f)
				value = 1.0f;
			if(value < 0.0f)
				value = 0.0f;
			data[dataI] = Ogre::uint8(value * 255);
		}
	}

	buffer->unlock();
}

void Plot::updateData()
{
	//set gpu parameters and update texture data
	Ogre::GpuProgramParametersSharedPtr fragmentProgParams = m_Material->getTechnique(0)->
		getPass(0)->getFragmentProgramParameters();
	fragmentProgParams->setNamedConstant("pointCount", float(m_Data.size()));
	fragmentProgParams->setNamedConstant("texWidth", float(m_DataTexture->getWidth()));
	fragmentProgParams->setNamedConstant("tintColor", m_TintColor);

	normalizeData();
}



Methods


The meaning of the methods of the class should be clear, but here is an explanation of them anyway:

Method Explanation
Plot::Plot(const std::string& pMaterialName, int pPointCount, Ogre::Real pDefaultValue, bool pAutoscale, const Ogre::ColourValue& pTintColor) Class constructor. It will create a material with the given name and use the other arguments to set the parameters accordingly
Plot::~Plot() Class destructor. It will try to unload the material and the texture so don't use them after destruction.
void Plot::addPoint(Ogre::Real pValue) Adds a point to the end of the chart and removes one on the other end.
void Plot::clearPoints() Clears all points, ie. it sets them to the default value.
const DataType& getData() const Return a const reference to the list of points.
void setData(const DataType& pData) Set the list of points to the given value. Note that this will also change the number of points managed by the class to the size of the list.
int getPointCount() const Return the number of points managed by the class.
void setPointCount(int pPointCount) Set the number of points managed by the class. If the number is highrt than the current one, the list will be padded with the default value.
float getDefaultValue() const Return the default value for the points.
void setDefaultValue(Ogre::Real pDefaultValue) Set the default value for the points.
bool getAutoscale() const Return the value that specifies weather the class performs auto-scaling of the data.
If this is set to true, the scale of the x axis will be min, max. If the value is set to false, the scale is set to 0, 1 and all the values are clamped.

Note that if the value is true and the difference between max and min is too small, the chart will only display zeros.
void setAutoscale(bool pAutoscale) Sets the value described above.
const Ogre::ColourValue& getTintColor() const Returns the color of the chart.
void setTintColor(const Ogre::ColourValue& pTintColor) Sets the color of the chart.



Using the class


Using the Plot class is really simple. You first have to instance the class with the name of the material, the number of points and the default value for the points. You may also specify weather the chart should be auto-scaled and what color it should have.

This code creates a plot that will use the material name TestPlotMaterial, have 50 points with the default value of 0.5 and not use auto-scaling:

Plot* myPlot = new Plot("TestPlotMaterial", 50, 0.5f, false);


To add points to the plot we use this code:

myPlot->addPoint(value);


And finally, to display the chart on the screen, we just set the material of some object (eg. an Overlay) to the same name:

overlay->setMaterialName("TestPlotMaterial");



Demo


You can view a more detailed demonstration of this snippet in a demo that has been prepared.

Type Link Format Size
Source Source download 7z (7 zip) 94 KB
Binary Binary download 7z (7 zip) 3.1 MB


See also