OSDL::Video::OpenGL::GLTexture Class Reference

Encapsulates an OpenGL texture, constructed directly or not from a surface, that can be loaded as resource. More...

#include <OSDLGLTexture.h>

Public Types
enum	TextureDimensionality { Disabled, OneDim, TwoDim }
	Texture support can be disabled, or enabled for 1D or 2D textures. More...
enum	TextureFlavour { None, Basic, For2D, For3D }
	Texture flavours are presets that can be chosen as a whole. More...
Public Member Functions
	GLTexture (const std::string textureFilename, TextureFlavour flavour, bool preload=true)
	Constructs a texture out of an image stored in a file.
	GLTexture (Surface &sourceSurface, TextureFlavour flavour)
	Constructs a texture out of an existing surface, whose ownership is taken.
virtual	~GLTexture () throw ()
	Virtual destructor, deallocates the owned internal surface, if any.
virtual Length	getWidth () const
	Returns the width of this texture.
virtual Length	getHeight () const
	Returns the height of this texture.
virtual bool	wasUploaded () const
	Returns true iff the texture has already been uploaded to the video card.
virtual void	upload ()
	Uploads the internal texture to the OpenGL context, i.e.
virtual void	remove ()
	Removes this texture, supposedly already uploaded, from the video card.
virtual void	setAsCurrent () const
	Sets this texture as the current texture: further textured renderings will make use of it.
virtual bool	isResident ()
	Returns true iff this texture is loaded in texture memory.
virtual bool	load ()
	Loads the texture image from file.
virtual bool	unload ()
	Unloads the texture image that may be contained by this instance.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
Static Public Member Functions
static TextureDimensionality	GetTextureDimensionality ()
	Returns the current texture dimensionality.
static void	SetTextureDimensionality (TextureDimensionality Dimensionality=TwoDim)
	Sets the current texture dimensionality.
static void	SetTextureFlavour (TextureFlavour textureFlavour)
	Sets the current texture state according to specified texture flavour.
static void	SetTextureEnvironmentParameter (GLEnumeration targetEnvironment, GLEnumeration environmentParameter, GLfloat parameterValue)
	Sets a parameter of a texture environment.
static void	SetTextureEnvironmentParameter (GLEnumeration targetEnvironment, GLEnumeration environmentParameter, const GLfloat *parameterValues)
	Sets the parameters of a texture environment.
static void	UnbindCurrentTexture ()
	Ensures no (2D) texture is currently bound.
static std::string	GetExtensionForFlavour (TextureFlavour flavour)
	Returns the filename extension which corresponds to the specified texture flavour.
Static Public Attributes
static TextureDimensionality	CurrentTextureDimensionality
	Stores the current texture dimensionality.
Protected Member Functions
void	setUpInternalSurfaceFrom (Surface &sourceSurface)
	Uploads an adequately converted surface, copied from the specified one, and deallocates it iff no OpenGL context can be lost, otherwise keeps it in texture cache.
Protected Attributes
GLTextureIdentifier	_id
	Identifier given by OpenGL to reference this texture.
TextureFlavour	_flavour
	Stores the current texture flavour.
bool	_unloadable
	Some textures should not be unloaded, as their content cannot be loaded from file, this is notably the case when their source surface is generated (ex: rendered text from a font) rather than simply loaded from an image file.
Private Member Functions
	GLTexture (const GLTexture &source)
	Copy constructor made private to ensure that it will never be called.
GLTexture &	operator= (const GLTexture &source)
	Assignment operator made private to ensure that it will never be called.

Detailed Description

Encapsulates an OpenGL texture, constructed directly or not from a surface, that can be loaded as resource.

The ownership of the source surface is not taken by GLtexture instances, since they have to convert it anyway into their own specific format for OpenGL.

This converted surface can be kept by the GLtexture for future use.

It is recommended to do so, insofar as, on some platforms, some operations, such as resizing, destroy the OpenGL context, including bound textures.

In this case, they have to be reloaded, which might be easier if they have kept their converted surface.

Note:: OpenGL support must have been selected and be available at configure time so that these OpenGL services can be used. Moreover as soon as a texture is uploaded, a proper OpenGL context must be available.

See also:: 'http://osdl.sourceforge.net', then 'Documentation', 'Rendering', 'OpenGL + SDL' for further implementation details.

Definition at line 122 of file OSDLGLTexture.h.

Member Enumeration Documentation

enum OSDL::Video::OpenGL::GLTexture::TextureDimensionality

Texture support can be disabled, or enabled for 1D or 2D textures.

Default is 'TwoDim', enabled for 2D textures.

Enumerator:

Disabled
OneDim
TwoDim

Definition at line 138 of file OSDLGLTexture.h.

enum OSDL::Video::OpenGL::GLTexture::TextureFlavour

Texture flavours are presets that can be chosen as a whole.

'None' does not change state of texture settings, whereas 'Basic' sets classical settings for filters and texture coordinate management, and 'For2D' selects settings appropriate for 2D rendering.

Enumerator:

None
Basic
For2D
For3D

Definition at line 152 of file OSDLGLTexture.h.

Constructor & Destructor Documentation

GLTexture::GLTexture	(	const std::string	textureFilename,
		TextureFlavour	flavour,
		bool	preload = `true`
	)			`[explicit]`

Constructs a texture out of an image stored in a file.

Parameters:

	textureFilename	the filename of the texture image, whose format (PNG, JPEG, etc.) will be auto-detected from content.
	preload	the image will be loaded directly by this constructor iff true, otherwise only its path will be stored to allow for later loading.
	flavour	the texture flavour that should be used.

The internal surface, corresponding to the image, will be, if needed, automatically kept back and managed by this texture, so that it can be reloaded in an OpenGL context if necessary, should the context be lost.

Note:: A constructed texture is not uploaded to the video card yet.

Exceptions:

GLTextureException

if the operation failed.

Definition at line 120 of file OSDLGLTexture.cc.

References load(), and LOG_DEBUG_TEXTURE.

GLTexture::GLTexture	(	Surface &	sourceSurface,
		TextureFlavour	flavour
	)

Constructs a texture out of an existing surface, whose ownership is taken.

Parameters:

	sourceSurface	the surface from which the texture will be defined.
	flavour	the texture flavour that should be used.

The internal surface, corresponding to the image, will be, if needed, automatically kept back and managed by this texture, so that it can be reloaded in an OpenGL context if necessary, should the context be lost.

Definition at line 168 of file OSDLGLTexture.cc.

References LOG_DEBUG_TEXTURE, and setUpInternalSurfaceFrom().

GLTexture::~GLTexture ( ) throw () [virtual]

Virtual destructor, deallocates the owned internal surface, if any.

Definition at line 184 of file OSDLGLTexture.cc.

References _unloadable, LOG_DEBUG_TEXTURE, and unload().

OSDL::Video::OpenGL::GLTexture::GLTexture ( const GLTexture & source ) [explicit, private]

Copy constructor made private to ensure that it will never be called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

std::string GLTexture::GetExtensionForFlavour ( TextureFlavour flavour ) [static]

Returns the filename extension which corresponds to the specified texture flavour.

For example, for the For2D flavour, ".tex2D" shall be returned.

Exceptions:

GLTextureException

if the flavour is not known.

Definition at line 1124 of file OSDLGLTexture.cc.

References Basic, For2D, For3D, None, and OSDL::Video::Pixels::toString().

Length GLTexture::getHeight ( ) const [virtual]

Returns the height of this texture.

Exceptions:

GLTextureException

if the texture is not already loaded.

Definition at line 262 of file OSDLGLTexture.cc.

Referenced by OSDL::Video::Surface::displayAt(), OSDL::Video::Surface::displayAtCenter(), OSDL::Video::Surface::displayAtCenterWithAlpha(), OSDL::Video::Surface::displayAtCenterWithFadeIn(), OSDL::Video::Surface::displayAtCenterWithFadeOut(), OSDL::Video::Surface::displayCenteredHorizontallyAt(), OSDL::Video::Surface::displayCenteredHorizontallyWithAlphaAt(), OSDL::Video::Surface::displayWithAlphaAt(), toString(), and upload().

GLTexture::TextureDimensionality GLTexture::GetTextureDimensionality ( ) [static]

Returns the current texture dimensionality.

Definition at line 816 of file OSDLGLTexture.cc.

References CurrentTextureDimensionality.

Length GLTexture::getWidth ( ) const [virtual]

Returns the width of this texture.

Exceptions:

GLTextureException

if the texture is not already loaded.

Definition at line 249 of file OSDLGLTexture.cc.

Referenced by OSDL::Video::Surface::displayAt(), OSDL::Video::Surface::displayAtCenter(), OSDL::Video::Surface::displayAtCenterWithAlpha(), OSDL::Video::Surface::displayAtCenterWithFadeIn(), OSDL::Video::Surface::displayAtCenterWithFadeOut(), OSDL::Video::Surface::displayCenteredHorizontallyAt(), OSDL::Video::Surface::displayCenteredHorizontallyWithAlphaAt(), OSDL::Video::Surface::displayWithAlphaAt(), toString(), and upload().

bool GLTexture::isResident ( ) [virtual]

Returns true iff this texture is loaded in texture memory.

Exceptions:

GLTextureException

if the operation failed.

Definition at line 648 of file OSDLGLTexture.cc.

References _id, and LOG_DEBUG_TEXTURE.

bool GLTexture::load ( ) [virtual]

Loads the texture image from file.

Returns:: true iff the image had to be actually loaded (otherwise it was already loaded and nothing was done).

Exceptions:

Ceylan::LoadableException

whenever the loading fails.

Note:: Loading (the internal texture image) does not imply uploading it to the video card.

Definition at line 720 of file OSDLGLTexture.cc.

References OSDL::Video::Surface::LoadImage(), LOG_DEBUG_TEXTURE, and setUpInternalSurfaceFrom().

Referenced by GLTexture(), and upload().

GLTexture& OSDL::Video::OpenGL::GLTexture::operator= ( const GLTexture & source ) [private]

Assignment operator made private to ensure that it will never be called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void GLTexture::remove ( ) [virtual]

Removes this texture, supposedly already uploaded, from the video card.

Exceptions:

GLTextureException

if the texture could not be removed.

Definition at line 543 of file OSDLGLTexture.cc.

References _id.

void GLTexture::setAsCurrent ( ) const [virtual]

Sets this texture as the current texture: further textured renderings will make use of it.

Exceptions:

GLTextureException

if the operation failed.

Definition at line 593 of file OSDLGLTexture.cc.

References _id.

void GLTexture::SetTextureDimensionality ( TextureDimensionality Dimensionality = TwoDim ) [static]

Sets the current texture dimensionality.

Definition at line 825 of file OSDLGLTexture.cc.

References CurrentTextureDimensionality.

Referenced by SetTextureFlavour().

void GLTexture::SetTextureEnvironmentParameter	(	GLEnumeration	targetEnvironment,
		GLEnumeration	environmentParameter,
		const GLfloat *	parameterValues
	)			`[static]`

Sets the parameters of a texture environment.

Parameters:

	targetEnvironment	the texture environment to set.
	environmentParameter	the symbolic name of a texture environment parameter.
	parameterValue	pointer to a parameter array that contains either a single symbolic constant, single floating-point number, or an RGBA color.

Exceptions:

GLTextureException

should an error occur.

Definition at line 1152 of file OSDLGLTexture.cc.

void GLTexture::SetTextureEnvironmentParameter	(	GLEnumeration	targetEnvironment,
		GLEnumeration	environmentParameter,
		GLfloat	parameterValue
	)			`[static]`

Sets a parameter of a texture environment.

Parameters:

	targetEnvironment	the texture environment to set.
	environmentParameter	the symbolic name of a texture environment parameter.
	parameterValue	a single symbolic constant, a single floating-point number, or an RGBA color.

Exceptions:

GLTextureException

should an error occur.

Definition at line 1011 of file OSDLGLTexture.cc.

Referenced by SetTextureFlavour().

void GLTexture::SetTextureFlavour ( TextureFlavour textureFlavour ) [static]

Sets the current texture state according to specified texture flavour.

Parameters:

textureFlavour

the selected texture flavour.

Exceptions:

GLTextureException

if the operation failed, including if no OpenGL support is available.

Definition at line 835 of file OSDLGLTexture.cc.

References Basic, OSDL::Video::OpenGL::OpenGLContext::EnableFeature(), For2D, For3D, None, SetTextureDimensionality(), SetTextureEnvironmentParameter(), OSDL::Video::Pixels::toString(), TwoDim, and OSDL::Video::OpenGL::TwoDimensionalTexturing.

Referenced by OSDL::Video::OpenGL::OpenGLContext::set2DFlavour(), OSDL::Video::OpenGL::OpenGLContext::set3DFlavour(), and upload().

void GLTexture::setUpInternalSurfaceFrom ( Surface & sourceSurface ) [protected]

Uploads an adequately converted surface, copied from the specified one, and deallocates it iff no OpenGL context can be lost, otherwise keeps it in texture cache.

Parameters:

sourceSurface

the surface to upload. In all cases it will be copied and converted, therefore it will remain untouched.

The internal surface, corresponding to the image, will be, if needed, automatically kept back and managed by this texture, so that it can be reloaded in an OpenGL context if necessary, in case it is lost.

Note:: sourceSurface cannot be 'const' since per-surface alpha setting has to be modified temporarily, even if this method has eventually no side-effect on this surface.

void upload( Surface & sourceSurface ) ; Sets up the internal surface of this texture from specified surface, which will then be deleted.

Definition at line 1218 of file OSDLGLTexture.cc.

References OSDL::Video::Surface::AlphaBlendingBlit, OSDL::Video::OpenGL::AlphaMask, OSDL::Video::Pixels::AlphaTransparent, OSDL::Video::Surface::blitTo(), OSDL::Video::OpenGL::BlueMask, OSDL::Video::Surface::getFlags(), OSDL::Video::Surface::getHeight(), OSDL::Video::Surface::getWidth(), OSDL::Video::OpenGL::GreenMask, OSDL::Video::OpenGL::RedMask, OSDL::Video::Surface::setAlpha(), and OSDL::Video::VideoModule::SoftwareSurface.

Referenced by GLTexture(), and load().

const string GLTexture::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Definition at line 785 of file OSDLGLTexture.cc.

References _id, getHeight(), and getWidth().

Referenced by OSDL::Rendering::Sprite::toString().

void GLTexture::UnbindCurrentTexture ( ) [static]

Ensures no (2D) texture is currently bound.

Useful when drawing solid shapes.

Definition at line 1072 of file OSDLGLTexture.cc.

bool GLTexture::unload ( ) [virtual]

Unloads the texture image that may be contained by this instance.

Returns:: true iff the image had to be actually unloaded (otherwise it was not already available and nothing was done).

Exceptions:

Ceylan::LoadableException

whenever the unloading fails.

Note:: Unloading (the internal texture image) does not imply removing it from the texture memory in the video card.

Definition at line 764 of file OSDLGLTexture.cc.

References _unloadable.

Referenced by ~GLTexture().

void GLTexture::upload ( ) [virtual]

Uploads the internal texture to the OpenGL context, i.e.

copies the internal surface to the video card.

Note:: The corresponding texture surface will be loaded is necessary. Thus in all cases after an upload, an unload can be performed.; A proper OpenGL context must be availabe before calling this method.

Exceptions:

GLTextureException

if the texture could not be uploaded.

Definition at line 294 of file OSDLGLTexture.cc.

References _flavour, _id, OSDL::getExistingCommonModule(), getHeight(), getWidth(), load(), SetTextureFlavour(), OSDL::Video::Pixels::toString(), and wasUploaded().

bool GLTexture::wasUploaded ( ) const [virtual]

Returns true iff the texture has already been uploaded to the video card.

Definition at line 277 of file OSDLGLTexture.cc.

References _id.

Referenced by upload().

Member Data Documentation

TextureFlavour OSDL::Video::OpenGL::GLTexture::_flavour [protected]

Stores the current texture flavour.

Note:: Needed, as a side-effect of uploading a texture is to create a new (blank) target texture, whose settings therefore need to be set specifically set.

Definition at line 546 of file OSDLGLTexture.h.

Referenced by upload().

GLTextureIdentifier OSDL::Video::OpenGL::GLTexture::_id [protected]

Identifier given by OpenGL to reference this texture.

Definition at line 534 of file OSDLGLTexture.h.

Referenced by isResident(), remove(), setAsCurrent(), toString(), upload(), and wasUploaded().

bool OSDL::Video::OpenGL::GLTexture::_unloadable [protected]

Some textures should not be unloaded, as their content cannot be loaded from file, this is notably the case when their source surface is generated (ex: rendered text from a font) rather than simply loaded from an image file.

Definition at line 558 of file OSDLGLTexture.h.

Referenced by unload(), and ~GLTexture().

GLTexture::TextureDimensionality GLTexture::CurrentTextureDimensionality [static]

Initial value:

 
    TwoDim

Stores the current texture dimensionality.

Default is 'TwoDim'.

Definition at line 394 of file OSDLGLTexture.h.

Referenced by GetTextureDimensionality(), and SetTextureDimensionality().

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

OSDL::Video::OpenGL::GLTexture Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation