OpenGL Texture Map Image class. More...

#include <GLImg.h>

Inheritance diagram for icl::qt::GLImg:

Public Types
typedef math::FixedColVector < float, 3 >	Vec3
	3D vector type
typedef utils::Function< Vec3, int, int >	grid_function
	a grid function returns a 3D pos from given 2D grid position
Public Member Functions
	GLImg (const core::ImgBase *src=0, core::scalemode sm=core::interpolateNN, int maxCellSize=4096)
	creates a new GLImg instance
	~GLImg ()
	destructor
void	update (const core::ImgBase *src, int maxCellSize=4096)
	set new texture data
void	setScaleMode (core::scalemode sm)
	sets the texture interpolation mode
bool	isNull () const
	returns whether a non-null images was buffered
void	draw2D (const utils::Rect &r, const utils::Size &windowSize)
	draws the image to the given 2D rect
void	draw2D (const float a[2], const float b[2], const float c[2], const float e[2], const utils::Size &windowSize)
	draws the image to the given quadrangle
void	draw3D (const float a[3], const float b[3], const float c[3], const float d[3], const float na[3]=0, const float nb[3]=0, const float nc[3]=0, const float nd[3]=0, const utils::Point32f &texCoordsA=utils::Point32f(0, 0), const utils::Point32f &texCoordsB=utils::Point32f(1, 0), const utils::Point32f &texCoordsC=utils::Point32f(0, 1), const utils::Point32f &texCoordsD=utils::Point32f(1, 1))
	draws the texture to the given nodes quad in 3D space
void	draw3DGeneric (int numPoints, const float xs, const float ys, const float zs, int xyzStride, const utils::Point32f texCoords, const float nxs=0, const float nys=0, const float *nzs=0, int nxyzStride=1, bool invertNormals=false)
	draws the texture using the given 3D Points, texture coordinates and optionally given normals
void	draw3D (const float a[3], const float b[3], const float c[3])
	draws the texture to given quad that is spanned by two vectors
void	drawToGrid (int nx, int ny, const float xs, const float ys, const float zs, const float nxs=0, const float nys=0, const float nzs=0, const int stride=1, bool invertNormals=false)
	draws the single texture spread to a given grid of nodes
void	drawToGrid (int nx, int ny, grid_function gridVertices, grid_function gridNormals=grid_function())
	draws the texture to an nx x ny grid whose positions and normals are defined by functions
utils::Size	getCells () const
	returns the number of internal cells used for the texture
void	bind (int xCell=0, int yCell=0)
	binds the given texture cell using glBindTexture(...)
utils::Size	getSize () const
	returns the image size
int	getWidth () const
	returns current image height
int	getHeight () const
	returns current image width
int	getChannels () const
	returns current image channel count
core::depth	getDepth () const
	returns the image depth
core::format	getFormat () const
	returns the image format
utils::Rect	getROI () const
	returns the image roi
utils::Time	getTime () const
	returns the current images time stamp
void	setBCI (int b=-1, int c=-1, int i=-1)
	sets up current brightness contrast and intensity
std::vector< utils::Range64f >	getMinMax () const
	returns the current minimun and maximum values for all channels
std::vector< icl64f >	getColor (int x, int y) const
	retuns the color at a given image location or a zero sized vector, (x,y) is outside the image
const core::ImgBase *	extractImage () const
	creates core::ImgBase version of the currently buffered images
const ImageStatistics &	getStats () const
	returns statistics of the currently buffered image
void	setDrawGrid (bool enabled, float *color=0)
	sets whether to visualize the pixel-grid or not
void	setGridColor (float *color)
	sets the grid color
const float *	getGridColor () const
	returns the current grid color
core::scalemode	getScaleMode () const
	returns the current scalemode
void	lock () const
	locks the texture buffer
void	unlock () const
	unlocks the texture buffer
Static Public Member Functions
static int	getMaxTextureSize ()
	returns the maximum texture map size that is supported by the present OpenGL system
Private Attributes
Data *	m_data
	internal data structure

Detailed Description

OpenGL Texture Map Image class.

The GLImg provides a simple interface to use ICL images as OpenGL texture maps.

Image Textures

Copying an image to a texture is applied in two steps. First, the image data is internally buffered. Then later the data is uploaded to the graphics memory. The buffering mechanism is restricted by the maximum texture size that is supported by the OpenGL system. Usually, the maximum texture size is 4096 or 8192, but the OpenGL standard does only say, that at least 64 must be supported. Therefore, it cannot be guaranteed that each image can be represented by a single OpenGL texture. Instead, larger images are represented by a 2D array of tiles, where each tile is represented by a single OpenGL texture.

Internal Buffering

Since the image data potentially needs to be split into several tiles, is is simpler to align the buffered data in image tiles. In order to minimize the amount of glTexImage2D calls, the data is furthermore buffered in interleaved data order. Here, byte-, short- and float- typed images (icl8u, icl16s and icl32f) are supported natively, i.e. they are buffered and uploaded in their native core::format. The other depths (icl32s and icl64f) are not supported natively, i.e. image of this core::depth are already buffered as floats. For int-typed images (icl32s) this, means, that very high image values cannot be represented correctly. And double typed images are also clipped to the float range and accuracy.

Uploading Texture Data

While the image buffering step is applied immediately (usually in the working thread), uploading the texture data to the graphics hardware is applied in a deferred manner. This has to reasons:

It is not allowed to access OpenGL from several threads. Due to the Qt-dependency, OpenGL will always live in the applications main thread.
If textures are visualized more frequently then their data is changed. A simple internal dirty-flag can be used to decide, whether the OpenGL texture data is already up-to-date.

In other words, when the texture is drawn (i.e. using GLImg::draw2D or GLImg::draw3D), the buffered data is automatically uploaded to the graphics hardware if this is necessary.

Member Typedef Documentation

typedef utils::Function<Vec3,int,int> icl::qt::GLImg::grid_function

a grid function returns a 3D pos from given 2D grid position

typedef math::FixedColVector<float,3> icl::qt::GLImg::Vec3

3D vector type

Constructor & Destructor Documentation

icl::qt::GLImg::GLImg	(	const core::ImgBase *	src = `0`,
		core::scalemode	sm = `core::interpolateNN`,
		int	maxCellSize = `4096`
	)

creates a new GLImg instance

optional parameters are

Parameters:

src	optionally given source image (if null, isNull() will return true)
sm	texture interpolation mode (either interpolateNN or interpolateLIN)
maxCellSize	the cells size (see Internal Buffering)

icl::qt::GLImg::~GLImg ( )

destructor

Member Function Documentation

void icl::qt::GLImg::bind	(	int	xCell = `0`,
		int	yCell = `0`
	)

binds the given texture cell using glBindTexture(...)

void icl::qt::GLImg::draw2D	(	const utils::Rect &	r,
		const utils::Size &	windowSize
	)

draws the image to the given 2D rect

This method is optimized for the OpenGL parameters set by the ICLQt::Widget class

void icl::qt::GLImg::draw2D	(	const float	a[2],
		const float	b[2],
		const float	c[2],
		const float	e[2],
		const utils::Size &	windowSize
	)

draws the image to the given quadrangle

This method is optimized for the OpenGL parameters set by the ICLQt::Widget class

void icl::qt::GLImg::draw3D	(	const float	a[3],
		const float	b[3],
		const float	c[3],
		const float	d[3],
		const float	na[3] = `0`,
		const float	nb[3] = `0`,
		const float	nc[3] = `0`,
		const float	nd[3] = `0`,
		const utils::Point32f &	texCoordsA = `utils::Point32f(0, 0)`,
		const utils::Point32f &	texCoordsB = `utils::Point32f(1, 0)`,
		const utils::Point32f &	texCoordsC = `utils::Point32f(0, 1)`,
		const utils::Point32f &	texCoordsD = `utils::Point32f(1, 1)`
	)

draws the texture to the given nodes quad in 3D space

the point order is

          a ---- b
          |      |
          |      |
          c ---- d

An addition to the corner 3D positions (a, b, c, and d), optionally normals (na, nb, nc and nd) can be given. The normals are only used, if none of the normal pointers is null. Additionally non-standard texture coordinates can be used to draw only parts of the texture.

void icl::qt::GLImg::draw3D	(	const float	a[3],
		const float	b[3],
		const float	c[3]
	)		`[inline]`

draws the texture to given quad that is spanned by two vectors

void icl::qt::GLImg::draw3DGeneric	(	int	numPoints,
		const float *	xs,
		const float *	ys,
		const float *	zs,
		int	xyzStride,
		const utils::Point32f *	texCoords,
		const float *	nxs = `0`,
		const float *	nys = `0`,
		const float *	nzs = `0`,
		int	nxyzStride = `1`,
		bool	invertNormals = `false`
	)

draws the texture using the given 3D Points, texture coordinates and optionally given normals

The strides are given in float-units. If normals are not given (i.e. at least one of the points nxs, nys or nzs is null, no normals will be set.

void icl::qt::GLImg::drawToGrid	(	int	nx,
		int	ny,
		const float *	xs,
		const float *	ys,
		const float *	zs,
		const float *	nxs = `0`,
		const float *	nys = `0`,
		const float *	nzs = `0`,
		const int	stride = `1`,
		bool	invertNormals = `false`
	)

draws the single texture spread to a given grid of nodes

size limitation

This does only work, if the texture size (width and height) is smaller than the maximum texture size supported by openGL. Usually, this is >= 4096.

data layout

The grid data layout is row-major, i.e. the grid node at (x,y) is obtained by (xs[idx], ys[idx], zs[idx]) where idx is stride*(x+nx*y). By using the stride parameter, this function can be used for both, planar and interleaved data.

interleaved data

          typedef FixedColVector<float,4> V4;
          const int nx = 20, ny = 30;
          icl::Array2D<V4> grid(nx,ny); // interleaved data with stride = 4
          // (...) fill grid nodes with values
          ImgQ image = create("lena");
          GLImg gli(&image);
          V4 &v = grid[0];
          gli.drawToGrid(nx,ny,&v[0],&v[1],&v[2],0,0,0,4);

planar data

add code from example above const int dim = nx*ny; std::vector<float> xs(dim), ys(dim), zs(dim); (...) fill xs, ys and zs with data gli.drawToGrid(nx,ny,xs.data(), ys.data(), zs.data());

void icl::qt::GLImg::drawToGrid	(	int	nx,
		int	ny,
		grid_function	gridVertices,
		grid_function	gridNormals = `grid_function()`
	)

draws the texture to an nx x ny grid whose positions and normals are defined by functions

The grid results are buffered internally in order to avoid extra function evaluations. Once, the data is buffered, it is passed to GLImg::drawGrid(int,int,const float*,const float*,const float*,const float*,const float*,const float*,int)

Examples

          GLImg::Vec3 grid_func(int x, int y){
            float nx = 30, ny = 20;
            return GLImg::Vec3(x-(nx/2),y-(ny/2),(nx/10.) * sin(float(x)/5 + t*5 )) * (300./nx);
          }
          
          void renderGrid(){
             GLImg gli(&image);
             static utils::Time first = utils::Time::now();
             float t = (utils::Time::now() - first).toSecondsDouble();
             gli.drawToGrid(30,20,grid_func);
          }

const core::ImgBase* icl::qt::GLImg::extractImage ( ) const

creates core::ImgBase version of the currently buffered images

Please note, that the ownership is not passed to the caller!

utils::Size icl::qt::GLImg::getCells ( ) const

returns the number of internal cells used for the texture

int icl::qt::GLImg::getChannels ( ) const

returns current image channel count

std::vector<icl64f> icl::qt::GLImg::getColor	(	int	x,
		int	y
	)		const

retuns the color at a given image location or a zero sized vector, (x,y) is outside the image

core::depth icl::qt::GLImg::getDepth ( ) const

returns the image depth

core::format icl::qt::GLImg::getFormat ( ) const

returns the image format

const float* icl::qt::GLImg::getGridColor ( ) const

returns the current grid color

int icl::qt::GLImg::getHeight ( ) const

returns current image width

static int icl::qt::GLImg::getMaxTextureSize ( ) [static]

returns the maximum texture map size that is supported by the present OpenGL system

std::vector<utils::Range64f> icl::qt::GLImg::getMinMax ( ) const

returns the current minimun and maximum values for all channels

utils::Rect icl::qt::GLImg::getROI ( ) const

returns the image roi

core::scalemode icl::qt::GLImg::getScaleMode ( ) const

returns the current scalemode

utils::Size icl::qt::GLImg::getSize ( ) const [inline]

returns the image size

const ImageStatistics& icl::qt::GLImg::getStats ( ) const

returns statistics of the currently buffered image

utils::Time icl::qt::GLImg::getTime ( ) const

returns the current images time stamp

int icl::qt::GLImg::getWidth ( ) const

returns current image height

bool icl::qt::GLImg::isNull ( ) const

returns whether a non-null images was buffered

void icl::qt::GLImg::lock ( ) const

locks the texture buffer

void icl::qt::GLImg::setBCI	(	int	b = `-1`,
		int	c = `-1`,
		int	i = `-1`
	)

sets up current brightness contrast and intensity

if b=c=i=-1 then, brightness is adapted automatically

void icl::qt::GLImg::setDrawGrid	(	bool	enabled,
		float *	color = `0`
	)

sets whether to visualize the pixel-grid or not

void icl::qt::GLImg::setGridColor ( float * color )

sets the grid color

void icl::qt::GLImg::setScaleMode ( core::scalemode sm )

sets the texture interpolation mode

void icl::qt::GLImg::unlock ( ) const

unlocks the texture buffer

void icl::qt::GLImg::update	(	const core::ImgBase *	src,
		int	maxCellSize = `4096`
	)

set new texture data

if source is null, the texture handle is deleted and isNull() will return true

Member Data Documentation

Data* icl::qt::GLImg::m_data [private]

internal data structure

internal data pointer

The documentation for this class was generated from the following file:

/home/jenkins/workspace/icl-manual-trunk/icl-manual/ICLQt/src/ICLQt/GLImg.h

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes