Text string class. More...

#include <VR3Text.h>

Public Member Functions
Constructor, Destructor and Initialization
	VR3Text (const char str, int resy=VR3TEXT_DEF_RESY, const char fontname=VR3TEXT_DEF_FONT, unsigned int charset=VR3TEXT_DEF_CHARSET)
	Text object constructor.
	~VR3Text ()
	Text object destructor.
Text String Management
void	LoadText (const char *str)
	Loads new text in the VR3Text object.
void	UseFont (int resy=VR3TEXT_DEF_RESY, const char fontname=VR3TEXT_DEF_FONT, unsigned int charset=VR3TEXT_DEF_CHARSET, const char str=0)
	Change the font used for text rendering.
Get and Set Functions
void	GetColor (GLfloat *color)
	Gets the text color into the given vector.
void	SetColor (GLfloat r, GLfloat g, GLfloat b, GLfloat a=1.0f)
	Sets the text color using the given values.
void	SetColor (const GLfloat *color)
	Sets the text color using the given vector.
void	GetPivotPoint (GLfloat *vec)
	Gets the position of the pivot point.
void	SetPivotPoint (GLfloat x, GLfloat y, GLfloat z)
	Sets the position of the pivot point.
void	SetPivotPoint (const GLfloat *vec)
	Sets the position of the pivot point.
void	GetPosition (GLfloat *p)
	Retrieves the position of the current object.
void	SetPosition (GLfloat x, GLfloat y, GLfloat z=0.0f)
	Sets the object position.
void	SetPosition (const GLfloat *point)
	Sets the object position.
void	GetScale (GLfloat *s)
	Gets the object scale.
void	SetScale (GLfloat scx, GLfloat scy)
	Sets the scaling factors.
void	SetScale (const GLfloat *s)
	Sets the scaling factors.
void	GetRotationMatrix (GLfloat *m)
	Retrieves the rotation matrix of the text object.
void	SetRotationMatrix (const GLfloat *m)
	Sets the rotation matrix of the text object.
void	Hide ()
	Hides the text object.
void	UnHide ()
	Unhides the text object.
Transformation Functions
void	SetRotation (GLfloat angle, GLfloat x, GLfloat y, GLfloat z)
	Sets the rotation of the text around the specified axis.
void	SetRotation (GLfloat angle, GLfloat *axis)
	Sets the rotation of the text around the specified axis.
void	RotateLocal (GLfloat angle, GLfloat x, GLfloat y, GLfloat z)
	Rotates the text around the specified axis (local coordinates)
void	RotateLocal (GLfloat angle, GLfloat *axis)
	Rotates the text around the specified axis (local coordinates)
void	RotateGlobal (GLfloat angle, GLfloat x, GLfloat y, GLfloat z)
	Rotates the text around the specified axis (world coordinates)
void	RotateGlobal (GLfloat angle, const GLfloat *axis)
	Rotates the text around the specified axis (parent or world coordinates)
void	TranslateLocal (GLfloat x, GLfloat y, GLfloat z=0.0f)
	Moves the text along the main axes (local coordinates)
void	TranslateLocal (const GLfloat *vec)
	Moves the text along the main axes (local coordinates)
void	TranslateGlobal (GLfloat x, GLfloat y, GLfloat z=0.0f)
	Moves the text along the main axes (world coordinates)
void	TranslateGlobal (const GLfloat *vec)
	Moves the object along the main axes (world coordinates)
Drawing Functions
void	Draw3D (int flags=0)
	Draws the text object as a standard 3D object.
void	Draw2D (int flags=0)
	Draws the text object as a 2D screen message.
Private Member Functions
	VR3Text (const VR3Text &)
	Disable default copy constructor.
VR3Text &	operator= (const VR3Text &)
	Disable default assignment operator.
Font Preparation Function
void	PrepareFont (int resy, const char *fontname, unsigned int charset)
	Creates a font and set it as active.
VAO and VBOs Preparation Function
void	PrepareVAO ()
	Prepares the VAO for the background.
Private Attributes
std::string	m_string
	Text string.
GLfloat	m_color [4]
	Text color (default is opaque white)
GLfloat	m_pos [3]
	Text string position (first character of the string, lower left corner)
GLfloat	m_scale [2]
	Text scaling.
GLfloat	m_rotation_matrix [16]
	Text rotation matrix.
GLfloat	m_pivot [3]
	Current pivot point position for rotations.
bool	m_ishidden
	Hidden flag.
GLuint	m_VAO
	VAO associated with a character.
GLuint	m_VBO
	VBO associated with the above VAO (vertex attributes)
HDC	m_mdc
	Memory device context used for current font management.
HFONT	m_font
	Currently active font for this text object.
std::string	m_fontname
	Currently active font name.
unsigned int	m_charset
	Currently active character set.
int	m_border [4]
	Minimum and maximum pixel coordinates in the character cell.
int	m_maxsize
	Size of the character texture in pixels.
GLuint	m_shader_program
	Shader program to be used to render the string.
const GLint *	m_unilocs
	Pointer to the uniform location array defined for the program.
GLuint	m_textures [256]
	Array the textures to use when drawing the text object.
GLfloat	m_charspace [256]
	Array of displacement values to pass the shaders while drawing strings.

Detailed Description

Text string class.

This class represents a text string to be rendered in the OpenGL scene as text, together with other objects in the scene. We use the windows GDI+ API and therefore all VR3Text services are only available to windows users. This is not the only way to render text in the OpenGL scene, but is the preferred one since we take advantage of the hardware acceleration. In the current implementation, there is no unicode support and the only character codes that we are able to write go from 0 to 255 (the meaning depends on the character set).

Characters are drawn as textures on simple square meshes. By default, the square meshes have a width and height of 1.0 units (which may be scaled at will using the provided transformation functions). The glyph won't always be square-shaped, indeed we have that it will be fitted to the square using its maximum dimension (width or height). Using GDI+-provided information, we are able to draw the squares at the right distance in order to obtain proper text rendering.

A VR3Text string object may be rendered in two different ways (and this is the reason for the two different draw methods.

Draw3D(): Text is rendered as a standard object in the 3D space, and the user may s pecify the desired rotation, translation and scale (along the local X and Y axes only). Depending on the type of font used, we may obtain overlapping characters, this could lead to bad looking artifacts because of depth testing having random behaviour. To avoid this situation we slightly displace the squares corresponding to subsequent characters along the local Z axis (by VR3TEXT_ZDISPLACEMENT units, which is scaled accordingly to the X axis scaling).

Draw2D(): The text is rendered as an on-screen message, this type of text does not alter the depth buffer and is not affected by other objects depth. This also means that if this type of text is not drawn at the end of the frame, objects drawn after it may hide the text string. When this type of drawing mode is chosen, rotation and position along the Z axis will have no effect on rendering. X and Y position and translation will be considered to render the text on the screen. In particular, the screen is considered a plane having its origin in the lower left screen corner and having height and width given by the number of pixels in each direction (viewport size). If not scaled, a character will always have its (invisible) cell covering a full screen unit, that is, a single pixel.

NOTE: Text string objects will never take part in the physical simulation, they are not considered ordinary objects in this case. The above also holds for shadow mapping: text strings will never work as casters or receivers in when a VR3ShadowController is active and working on the scene.

NOTE: Even when the color specified for the VR3Text object is a solid one (alpha component 1.0) transparency will always be an issue because rendered text will blend with what is behind it to allow character textures linear filtering. The drawing order considerations done for VR3Obj objects are again valid in this case. Parts of the character square that end up with an alpha value of 0.0 even after linear filtering will be considered as positioned on the far clipping plane for depth comparison purpose (this does not prevent the depth test artifacts above, but limit their effect as if the character texture was rendered on a fairly tight character-shaped polygon).

Definition at line 97 of file VR3Text.h.

Constructor & Destructor Documentation

VR3Text::VR3Text ( const VR3Text & ) [private]

Disable default copy constructor.

VR3Text::VR3Text	(	const char *	str,
		int	resy = `VR3TEXT_DEF_RESY`,
		const char *	fontname = `VR3TEXT_DEF_FONT`,
		unsigned int	charset = `VR3TEXT_DEF_CHARSET`
	)

Text object constructor.

This constructor is used to build a text object with the specified content, using the specified font name and the specified character set. The desired resolution (number of pixels) in the y direction is specified using the resy input parameter, this is only a target value and the effective resolution may be lower depending on the windows font availability. The resolution parameter does not affect the size of the final rendered text, only its quality.

Parameters:

[in]	str	The text string
[in]	resy	The desired number of pixels in the Y direction
[in]	fontname	The name of the font to use for rendering
[in]	charset	The selected character set

VR3Text::~VR3Text ( )

Text object destructor.

Member Function Documentation

void VR3Text::Draw2D ( int flags = 0 )

Draws the text object as a 2D screen message.

Only the X and Y position and scaling are considered to render the text message on the screen. No depth test takes place in this case and the depth buffer is not altered as well.

Parameters:

[in] flags Draw flags (currently ignored)

void VR3Text::Draw3D ( int flags = 0 )

Draws the text object as a standard 3D object.

The text object is drawn at the specified position, with the specified scale and rotation. The position identifies the position in world space coordinates of the lower left corner of the first character in the string.

Parameters:

[in] flags Draw flags (currently ignored)

void VR3Text::GetColor ( GLfloat * color )

Gets the text color into the given vector.

Parameters:

[out] color The text color

void VR3Text::GetPivotPoint ( GLfloat * vec )

Gets the position of the pivot point.

Retrieves the pivot point position of the current object, i.e. the point in which the rotation axis is fixed. The coordinates are expressed in world coordinates.

Parameters:

[out] vec The retrieved pivot point position (3 components)

void VR3Text::GetPosition ( GLfloat * p )

Retrieves the position of the current object.

Returns the position of the text in world coordinates.

Parameters:

[out] p The retrieved object position (3 components)

void VR3Text::GetRotationMatrix ( GLfloat * m )

Retrieves the rotation matrix of the text object.

Returns the current orientation of the object as a 16-elements array, notice that this orientation matrix is relative to the world coordinates. The matrix is a column-major order.

Parameters:

[out] m The rotation matrix (16 components)

void VR3Text::GetScale ( GLfloat * s )

Gets the object scale.

Returns the current scaling of the object as a 2-components vector (the z axis is not considered because text has no depth).

Parameters:

[out] s The retrieved scaling vector (2 components)

void VR3Text::Hide ( ) [inline]

Hides the text object.

This method forces the text rendering to take no action, the text will not be visible no matter what.

Definition at line 368 of file VR3Text.h.

void VR3Text::LoadText ( const char * str )

Loads new text in the VR3Text object.

This function is used to change the string content of the VR3Text object. It will not change the font used and is the function to be used when updating the string text. We have to make sure that all needed textures (for the user characters) are already loaded in the texture array. Old textures not needed anymore are deleted from the array (corresponding to character in the old string but not in the new one).

Parameters:

[in] str The new string text

VR3Text& VR3Text::operator= ( const VR3Text & ) [private]

Disable default assignment operator.

void VR3Text::PrepareFont	(	int	resy,
		const char *	fontname,
		unsigned int	charset
	)		`[private]`

Creates a font and set it as active.

This function is used to create a font depending on the user specified parameters, the created font is then set as active on the memory device context m_mdc.

Parameters:

[in]	resy	The desired number of pixels in the Y direction
[in]	fontname	The name of the desired font
[in]	charset	The selected character set

void VR3Text::PrepareVAO ( ) [private]

Prepares the VAO for the background.

The VAO to be used to draw the string will always include a vertex position VBO and a texture coordinate VBO. This function is used to prepare the VAO with the two required VBOs and send the data to the GL.

void VR3Text::RotateGlobal	(	GLfloat	angle,
		const GLfloat *	axis
	)		`[inline]`

Rotates the text around the specified axis (parent or world coordinates)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in]	angle	The rotation angle
[in]	axis	The rotation axis (3 components)

Definition at line 442 of file VR3Text.h.

void VR3Text::RotateGlobal	(	GLfloat	angle,
		GLfloat	x,
		GLfloat	y,
		GLfloat	z
	)

Rotates the text around the specified axis (world coordinates)

Rotates the text object of angle degrees around the axis defined by (x,y,z) running through the pivot point. The axis is expressed in global world coordinates. The default pivot point is the origin of the string. The specified rotation is added to previous rotations, allowing the composition of subsequent rotations.

Parameters:

[in]	angle	The rotation angle
[in]	x,y,z	The rotation axis components

void VR3Text::RotateLocal	(	GLfloat	angle,
		GLfloat *	axis
	)		`[inline]`

Rotates the text around the specified axis (local coordinates)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in]	angle	The rotation angle
[in]	axis	The rotation axis (3 components)

Definition at line 421 of file VR3Text.h.

void VR3Text::RotateLocal	(	GLfloat	angle,
		GLfloat	x,
		GLfloat	y,
		GLfloat	z
	)

Rotates the text around the specified axis (local coordinates)

Rotates the current text of angle degrees around the axis defined by (x,y,z) running through the pivot point. The axis is expressed in the current object local coordinates. The default pivot point is the origin of the object's local reference frame. The specified rotation is added to previous rotations, allowing the composition of subsequent rotations.

Parameters:

[in]	angle	The rotation angle
[in]	x,y,z	The rotation axis components

void VR3Text::SetColor ( const GLfloat * color )

Sets the text color using the given vector.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in] color The new text color (4 components)

void VR3Text::SetColor	(	GLfloat	r,
		GLfloat	g,
		GLfloat	b,
		GLfloat	a = `1.0f`
	)

Sets the text color using the given values.

Parameters:

[in] r,g,b,a The components of the new text color

void VR3Text::SetPivotPoint	(	GLfloat	x,
		GLfloat	y,
		GLfloat	z
	)

Sets the position of the pivot point.

Sets the pivot point of the current text string, i.e. the point in which the rotation axis is fixed. By default the pivot point coincides with the origin of the string. Changing the pivot point position allows the object to rotate around an axis different from the default one The coordinates are expressed in the parent's reference frame. If the object has no parent, the pivot point position is expressed in world coordinates.

Parameters:

[in] x,y,z The pivot point position coordinates

void VR3Text::SetPivotPoint ( const GLfloat * vec )

Sets the position of the pivot point.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in] vec The pivot point position (3 components)

void VR3Text::SetPosition	(	GLfloat	x,
		GLfloat	y,
		GLfloat	z = `0.0f`
	)

Sets the object position.

Sets the position of the current object. The coordinates are expressed in world coordinates. The default value for z will be particularly useful when dealing with 2D rendered text strings.

Parameters:

[in] x,y,z The coordinates of the new object position

void VR3Text::SetPosition ( const GLfloat * point )

Sets the object position.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in] point The new object position (3 components)

void VR3Text::SetRotation	(	GLfloat	angle,
		GLfloat	x,
		GLfloat	y,
		GLfloat	z
	)

Sets the rotation of the text around the specified axis.

Rotates the text object of angle degrees around the axis defined by (x,y,z) running through the pivot point. The default pivot point is the origin of the text string (lower left corner). The specified rotation overwrites previous rotations (the rotation matrix is recalculated).

Parameters:

[in]	angle	The rotation angle
[in]	x,y,z	The rotation axis components

void VR3Text::SetRotation	(	GLfloat	angle,
		GLfloat *	axis
	)		`[inline]`

Sets the rotation of the text around the specified axis.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in]	angle	The rotation angle
[in]	axis	The rotation axis (3 components)

Definition at line 400 of file VR3Text.h.

void VR3Text::SetRotationMatrix ( const GLfloat * m )

Sets the rotation matrix of the text object.

Sets the rotation matrix of the text, forcing this way the orientation of the object with reference to the world.

Parameters:

[in] m The new rotation matrix (16 components, column-major order)

void VR3Text::SetScale	(	GLfloat	scx,
		GLfloat	scy
	)

Sets the scaling factors.

Sets the scaling factors along the main axes. The scaling can be not-uniform specifying different factors, or uniform if the same factor is specified once for the 2 axes (x and y).

Parameters:

[in] scx,scy The scaling factors

void VR3Text::SetScale ( const GLfloat * s )

Sets the scaling factors.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in] s The new text scale (2 components)

void VR3Text::TranslateGlobal	(	GLfloat	x,
		GLfloat	y,
		GLfloat	z = `0.0f`
	)

Moves the text along the main axes (world coordinates)

Moves the text along the main axes of the specified amount, starting from its current position. The default value for z will be particularly useful when dealing with 2D rendered text strings.

Parameters:

[in] x,y,z Translation vector components

void VR3Text::TranslateGlobal ( const GLfloat * vec ) [inline]

Moves the object along the main axes (world coordinates)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in] vec Translation vector (3 components)

Definition at line 476 of file VR3Text.h.

void VR3Text::TranslateLocal ( const GLfloat * vec ) [inline]

Moves the text along the main axes (local coordinates)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

[in] vec Translation vector (3 components)

Definition at line 459 of file VR3Text.h.

void VR3Text::TranslateLocal	(	GLfloat	x,
		GLfloat	y,
		GLfloat	z = `0.0f`
	)

Moves the text along the main axes (local coordinates)

Moves the text in its own reference system of the specified amount, starting from its current position. The default value for z will be particularly useful when dealing with 2D rendered text strings.

Parameters:

[in] x,y,z Translation vector components

void VR3Text::UnHide ( ) [inline]

Unhides the text object.

This method renders the object visible again, its children will be hidden or not depending on their private visibility status.

Definition at line 374 of file VR3Text.h.

void VR3Text::UseFont	(	int	resy = `VR3TEXT_DEF_RESY`,
		const char *	fontname = `VR3TEXT_DEF_FONT`,
		unsigned int	charset = `VR3TEXT_DEF_CHARSET`,
		const char *	str = `0`
	)

Change the font used for text rendering.

This function is used to change the font used for text rendering, the optional parameter str allows to change also the text content of the VR3Text object. When this function is called, the textures already created for the used letters are deleted and new textures are created using the new font. To avoid creating useless textures, a new string content may be specified using the second parameter. If no parameters are provided, default initial font and character set settings restored.

Parameters:

[in]	resy	The desired number of pixels in the Y direction
[in]	fontname	The new font name
[in]	charset	The selected character set
[in]	str	The new VR3Text string content (if not 0)

Member Data Documentation

int VR3Text::m_border[4] [private]

Minimum and maximum pixel coordinates in the character cell.

Definition at line 129 of file VR3Text.h.

unsigned int VR3Text::m_charset [private]

Currently active character set.

Definition at line 127 of file VR3Text.h.

GLfloat VR3Text::m_charspace[256] [private]

Array of displacement values to pass the shaders while drawing strings.

Each character will be drawn in a certain position depending on the previous ones.

Definition at line 143 of file VR3Text.h.

GLfloat VR3Text::m_color[4] [private]

Text color (default is opaque white)

Definition at line 102 of file VR3Text.h.

HFONT VR3Text::m_font [private]

Currently active font for this text object.

Definition at line 123 of file VR3Text.h.

std::string VR3Text::m_fontname [private]

Currently active font name.

Definition at line 125 of file VR3Text.h.

bool VR3Text::m_ishidden [private]

Hidden flag.

Definition at line 113 of file VR3Text.h.

int VR3Text::m_maxsize [private]

Size of the character texture in pixels.

Definition at line 131 of file VR3Text.h.

HDC VR3Text::m_mdc [private]

Memory device context used for current font management.

Definition at line 121 of file VR3Text.h.

GLfloat VR3Text::m_pivot[3] [private]

Current pivot point position for rotations.

Definition at line 110 of file VR3Text.h.

GLfloat VR3Text::m_pos[3] [private]

Text string position (first character of the string, lower left corner)

Definition at line 104 of file VR3Text.h.

GLfloat VR3Text::m_rotation_matrix[16] [private]

Text rotation matrix.

Definition at line 108 of file VR3Text.h.

GLfloat VR3Text::m_scale[2] [private]

Text scaling.

Definition at line 106 of file VR3Text.h.

GLuint VR3Text::m_shader_program [private]

Shader program to be used to render the string.

Definition at line 134 of file VR3Text.h.

std::string VR3Text::m_string [private]

Text string.

Definition at line 100 of file VR3Text.h.

GLuint VR3Text::m_textures[256] [private]

Array the textures to use when drawing the text object.

Definition at line 139 of file VR3Text.h.

const GLint* VR3Text::m_unilocs [private]

Pointer to the uniform location array defined for the program.

Definition at line 136 of file VR3Text.h.

GLuint VR3Text::m_VAO [private]

VAO associated with a character.

Definition at line 116 of file VR3Text.h.

GLuint VR3Text::m_VBO [private]

VBO associated with the above VAO (vertex attributes)

Definition at line 118 of file VR3Text.h.

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

include/VR3Text.h

VR3Text Class Reference

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation