A 1D, 2D, or 3D array (e.g., an image) stored on the GPU, commonly used for mapping reflectance values (colors) over meshes. More...

Inherits G3D::ReferenceCountedObject.

Classes
struct	CubeMapInfo

class	Preprocess

class	Settings
	All parameters of a texture that are independent of the underlying image data. More...

class	Specification

class	Visualization

Public Types
enum	DepthReadMode { DEPTH_NORMAL = 0, DEPTH_LEQUAL = 1, DEPTH_GEQUAL = 2 }
	A m_depth texture can automatically perform the m_depth comparison used for shadow mapping on a texture lookup. More...

enum	Dimension { DIM_2D = 2, DIM_3D = 3, DIM_2D_RECT = 4, DIM_CUBE_MAP = 5, DIM_2D_NPOT = 6, DIM_CUBE_MAP_NPOT = 7, DIM_3D_NPOT = 8 }
	DIM_2D_NPOT and DIM_CUBE_MAP_NPOT attempt to use ARB_non_power_of_two texture support with POT fallback. More...

enum	InterpolateMode { TRILINEAR_MIPMAP = 3, BILINEAR_MIPMAP = 4, NEAREST_MIPMAP = 5, BILINEAR_NO_MIPMAP = 2, NEAREST_NO_MIPMAP = 6 }
	Trilinear mipmap is the best quality (and frequently fastest) mode. More...

typedef shared_ptr< class Texture >	Ref
	Reference counted pointer to a Texture.

Public Member Functions
virtual	~Texture ()
	Deallocates the OpenGL texture.

shared_ptr< Texture >	alphaOnlyVersion () const
	Creates another texture that is the same as this one but contains only an alpha channel.

void	clear (CubeFace face=CubeFace::POS_X, int mipLevel=0, class RenderDevice *rd=NULL)
	Clear the texture to empty (typically after creation, so that it does not contain unitialized data).

void	copyFromScreen (const Rect2D &rect, const ImageFormat *fmt=NULL)
	Copies data from screen into an existing texture (replacing whatever was previously there).

void	copyFromScreen (const Rect2D &rect, CubeFace face)
	Copies into the specified face of a cube map.

bool G3D_DEPRECATED	copyInto (shared_ptr< Texture > &dest, CubeFace cf=CubeFace::POS_X, int mipLevel=0, RenderDevice *rd=NULL) const
	Copies this texture over dest, allocating or resizing dest as needed.

int	depth () const

Dimension	dimension () const

const ImageFormat *	format () const

void	generateMipMaps ()
	For a texture with automipmap off that supports the FrameBufferObject extension, generate mipmaps from the level 0 mipmap immediately.

void G3D_DEPRECATED	getTexImage (void data, const ImageFormat desiredFormat, CubeFace face=CubeFace::POS_X, int mipLevel=0) const

int	height () const
	Number of horizontal texels in the level 0 mipmap.

bool	isCubeMap () const

Color4	max () const
	If this texture was loaded from an uncompressed format in memory or disk (and not rendered to), this is the largest value in the texture.

Color4	mean () const
	If this texture was loaded from an uncompressed format in memory or disk (and not rendered to), this is the average value in the texture.

Color4	min () const
	If this texture was loaded from an uncompressed format in memory or disk (and not rendered to), this is the smallest value in the texture.

const std::string &	name () const

bool	opaque () const
	True if this texture was created with an alpha channel.

unsigned int	openGLID () const

unsigned int	openGLTextureTarget () const
	The OpenGL texture target this binds (e.g.

Color4	readTexel (int ix, int iy, class RenderDevice *rd=NULL) const
	Reads back a single texel.

Rect2D	rect2DBounds () const
	Returns a rectangle whose m_width and m_height match the dimensions of the texture.

void	resize (int w, int h)
	Resize the underlying OpenGL texture memory buffer, without reallocating the OpenGL texture ID.

void	setAutoMipMap (bool b)
	Set the autoMipMap value, which only affects textures when they are rendered to or copied from the screen.

void	setDepthReadMode (Texture::DepthReadMode depthReadMode)
	Allows forcing a change to the depthReadMode of the texture currently bound to the target.

const Settings &	settings () const

int	sizeInMemory () const
	How much (texture) memory this texture occupies.

Image1unorm8Ref	toDepthImage1unorm8 () const
	Extracts the data as ImageFormat::DEPTH32F and converts to 8-bit.

Map2D< float >::Ref	toDepthMap () const
	Extracts the data as ImageFormat::DEPTH32F.

shared_ptr< Image >	toImage (const ImageFormat *outFormat=ImageFormat::AUTO(), int mipLevel=0, CubeFace face=CubeFace::POS_X) const

shared_ptr< GLPixelTransferBuffer >	toPixelTransferBuffer (const ImageFormat *outFormat=ImageFormat::AUTO(), int mipLevel=0, CubeFace face=CubeFace::POS_X) const

void	update (const shared_ptr< PixelTransferBuffer > &src, int mipLevel=0, CubeFace face=CubeFace::POS_X)
	Upload new data from the CPU to this texture.

Vector2	vector2Bounds () const

int	width () const
	Number of horizontal texels in the level 0 mipmap.

Static Public Member Functions
static void	copy (shared_ptr< Texture > src, shared_ptr< Texture > dst, int srcMipLevel=0, int dstMipLevel=0, CubeFace srcCubeFace=CubeFace::POS_X, CubeFace dstCubeFace=CubeFace::POS_X, RenderDevice *rd=NULL)
	Copies src to dst, resizing if needed.

static Ref	create (const Specification &s)

static shared_ptr< Texture >	createColor (const Color3unorm8 &c)
	Creates a new 1x1 texture in this color.

static shared_ptr< Texture >	createColor (const Color4unorm8 &c)
	Creates a new 1x1 texture in this color.

static shared_ptr< Texture >	createEmpty (const std::string &name, int width, int height, const ImageFormat *desiredFormat=ImageFormat::RGBA8(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), int depth=1)
	Creates an empty texture (useful for later reading from the screen).

static const CubeMapInfo &	cubeMapInfo (CubeMapConvention convention)
	Returns the mapping from [0, 5] to cube map faces and filename suffixes.

static Dimension	defaultDimension ()
	Returns the default Dimension for this machine, which is DIM_2D_NPOT if supported and DIM_2D if not.

static CubeMapConvention	determineCubeConvention (const std::string &filename)
	filename should contain a * wildcard

static shared_ptr< Texture >	fromFile (const std::string &filename, const ImageFormat *desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &process=Preprocess(), bool preferSRGBForAuto=false)
	Creates a texture from a single image.

static shared_ptr< Texture >	fromFile (const std::string filename[6], const ImageFormat *desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &process=Preprocess(), bool preferSRGBForAuto=false)
	Creates a cube map from six independently named files.

static shared_ptr< Texture >	fromGLTexture (const std::string &name, GLuint textureID, const ImageFormat *textureFormat, Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults())
	Wrap and interpolate will override the existing parameters on the GL texture.

static shared_ptr< Texture >	fromImage (const std::string &name, const Image3::Ref &image, const ImageFormat *desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &preprocess=Preprocess::defaults())

static shared_ptr< Texture > G3D_DEPRECATED	fromImageBuffer (const std::string &name, const PixelTransferBuffer::Ref &image, const ImageFormat *desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &preprocess=Preprocess::defaults())

static shared_ptr< Texture >	fromMemory (const std::string &name, const Array< Array< const void * > > &bytes, const ImageFormat bytesFormat, int m_width, int m_height, int m_depth, const ImageFormat desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &preprocess=Preprocess::defaults(), bool preferSRGBForAuto=false)
	Construct from an explicit set of (optional) mipmaps and (optional) cubemap faces.

static shared_ptr< Texture >	fromMemory (const std::string &name, const void bytes, const ImageFormat bytesFormat, int m_width, int m_height, int m_depth, const ImageFormat *desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &preprocess=Preprocess::defaults(), bool preferSRGBForAuto=false)
	Construct from a single packed 2D or 3D data set.

static shared_ptr< Texture >	fromPixelTransferBuffer (const std::string &name, const PixelTransferBuffer::Ref &image, const ImageFormat *desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &preprocess=Preprocess::defaults())

static shared_ptr< Texture >	fromTwoFiles (const std::string &filename, const std::string &alphaFilename, const ImageFormat *desiredFormat=ImageFormat::AUTO(), Dimension dimension=defaultDimension(), const Settings &settings=Settings::defaults(), const Preprocess &process=Preprocess())
	Creates a texture from the colors of filename and takes the alpha values from the red channel of alpha filename.

static void	getCubeMapRotation (CubeFace face, Matrix3 &outMatrix)
	Returns the rotation matrix that should be used for rendering the given cube map face.

static bool	isSupportedImage (const std::string &filename)
	Returns true if the specified filename exists and is an image that can be loaded as a Texture.

static unsigned int	newGLTextureID ()
	Helper method.

static shared_ptr< Texture >	one ()
	Returns a small all-white (1,1,1,1) texture. .

static shared_ptr< Texture >	opaqueBlack ()
	Returns a small opaque all-black (0,0,0,1) texture.

static shared_ptr< Texture >	opaqueBlackCube ()
	Returns a small opaque all-black (0,0,0,1) texture.

static shared_ptr< Texture >	opaqueBlackIfNull (const shared_ptr< Texture > &t)
	Returns t if it is non-NULL, or opaqueBlack() if t is NULL.

static shared_ptr< Texture >	opaqueGray ()
	Returns a small all-gray (0.5,0.5,0.5,1) texture.

static shared_ptr< Texture >	opaqueGrayIfNull (const shared_ptr< Texture > &t)
	Returns t if it is non-NULL, or gray() if t is NULL.

static int64	sizeOfAllTexturesInMemory ()
	Video memory occupied by all OpenGL textures allocated using Texture or maintained by pointers to a Texture.

static void	splitFilenameAtWildCard (const std::string &filename, std::string &filenameBeforeWildCard, std::string &filenameAfterWildCard)
	Splits a filename around the '*' character– used by cube maps to generate all filenames.

static bool	supportsWrapMode (WrapMode m)
	Returns true if this is a legal wrap mode for a G3D::Texture.

static DepthReadMode	toDepthReadMode (const std::string &s)

static Dimension	toDimension (const std::string &s)

static InterpolateMode	toInterpolateMode (const std::string &s)

static const char *	toString (InterpolateMode m)

static const char *	toString (DepthReadMode m)

static const char *	toString (Dimension m)

static shared_ptr< Texture >	white ()
	Returns a small all-white (1,1,1,1) texture.

static shared_ptr< Texture >	whiteCube ()
	Returns a small all-white (1,1,1,1) cube map texture.

static shared_ptr< Texture >	whiteCubeIfNull (const shared_ptr< Texture > &t)
	Returns t if it is non-NULL, or whiteCube() if t is NULL.

static shared_ptr< Texture >	whiteIfNull (const shared_ptr< Texture > &t)
	Returns t if it is non-NULL, or white() if t is NULL.

static shared_ptr< Texture >	zero ()
	Returns a small, all zero Color4(0,0,0,0) texture.

static shared_ptr< Texture >	zeroIfNull (const shared_ptr< Texture > &t)
	Returns t if it is non-NULL, or zero() if t is NULL.

Public Attributes
Visualization	visualization
	Used to display this Texture in a GuiTextureBox.

Friends
template<class C , class I >
class	Component

template<class I >
class	MapComponent

Detailed Description

A 1D, 2D, or 3D array (e.g., an image) stored on the GPU, commonly used for mapping reflectance values (colors) over meshes.

Abstraction of OpenGL textures. This class can be used with raw OpenGL, without RenderDevice. G3D::Texture supports all of the image formats that G3D::Image can load, and DDS (DirectX textures), and Quake-style cube maps.

If you enable texture compression, textures will be compressed on the fly. This can be slow (up to a second).

The special filename "<white>" generates an all-white Color4 texture (this works for both 2D and cube map texures; "<whiteCube>" can also be used explicitly for cube maps). You can use Preprocess::modulate to create other colors from this.

Unless DIM_2D_RECT, DIM_2D_NPOT, DIM_CUBE_MAP_NPOT are used, the texture is automatically scaled to the next power of 2 along each dimension to meet hardware requirements, if not already a power of 2. However, DIM_2D_NPOT and DIM_CUBE_MAP_NPOT will safely fallback to POT requirements if the ARB_non_power_of_two extension is not supported. Develoeprs can check if this will happen by calling GLCaps::supports_GL_ARB_texture_non_power_of_two(). Note that the texture does not have to be a square; the dimensions can be different powers of two. DIM_2D_RECT is provided primarily for older cards only and does not interact well with shaders.

Textures are loaded so that (0, 0) is the upper-left corner of the image.

DIM_2D_RECT requires the GL_EXT_texture_rectangle extension. Texture compression requires the EXT_texture_compression_s3tc extions. You can either query OpenGL for whether these are supported or use the G3D::GLCaps facility for doing so.

G3D::Texture can be used with straight OpenGL, without G3D::RenderDevice, as follows:

  shared_ptr<Texture> texture = new Texture("logo.jpg");

...

  GLint u = texture->getOpenGLTextureTarget();
  glEnable(u);
  glBindTexture(u, texture->getOpenGLID());

To use Texture with RenderDevice:

  shared_ptr<Texture> texture = new Texture("logo.jpg");
  ...
  renderDevice->setTexture(0, texture);
(to disable: renderDevice->setTexture(0, NULL);)

3D MIP Maps are not supported because gluBuild3DMipMaps is not in all GLU implementations.

See Also: G3D::RenderDevice::setBlendFunc for important information about turning on alpha blending when using textures with alpha.

Member Typedef Documentation

typedef shared_ptr<class Texture> G3D::Texture::Ref

Reference counted pointer to a Texture.

Member Enumeration Documentation

enum G3D::Texture::DepthReadMode

A m_depth texture can automatically perform the m_depth comparison used for shadow mapping on a texture lookup.

The result of a texture lookup is thus the shadowed amount (which will be percentage closer filtered on newer hardware) and not the actual m_depth from the light's point of view.

This combines GL_TEXTURE_COMPARE_MODE_ARB and GL_TEXTURE_COMPARE_FUNC_ARB from http://www.nvidia.com/dev_content/nvopenglspecs/GL_ARB_shadow.txt

For best results on percentage closer hardware (GeForceFX and Radeon9xxx or better), create shadow maps as m_depth textures with BILINEAR_NO_MIPMAP sampling.

See also G3D::RenderDevice::configureShadowMap and the Collision_Demo.

Enumerator:

DEPTH_NORMAL
DEPTH_LEQUAL
DEPTH_GEQUAL

enum G3D::Texture::Dimension

DIM_2D_NPOT and DIM_CUBE_MAP_NPOT attempt to use ARB_non_power_of_two texture support with POT fallback.

See Also: defaultDimension

Enumerator:

DIM_2D
DIM_3D
DIM_2D_RECT
DIM_CUBE_MAP
DIM_2D_NPOT
DIM_CUBE_MAP_NPOT
DIM_3D_NPOT

enum G3D::Texture::InterpolateMode

Trilinear mipmap is the best quality (and frequently fastest) mode.

The no-mipmap modes conserve memory. Non-interpolating ("Nearest") modes are generally useful only when packing lookup tables into textures for shaders.

3D textures do not support mipmap interpolation modes.

Enumerator:

TRILINEAR_MIPMAP
BILINEAR_MIPMAP
NEAREST_MIPMAP
BILINEAR_NO_MIPMAP
NEAREST_NO_MIPMAP

Constructor & Destructor Documentation

virtual G3D::Texture::~Texture ( )

virtual

Deallocates the OpenGL texture.

Member Function Documentation

shared_ptr<Texture> G3D::Texture::alphaOnlyVersion ( ) const

Creates another texture that is the same as this one but contains only an alpha channel.

Alpha-only textures are useful as mattes.

If the current texture is opaque(), returns NULL (since it is not useful to construct an alpha-only version of a texture without an alpha channel).

Like all texture construction methods, this is fairly slow and should not be called every frame during interactive rendering.

void G3D::Texture::clear	(	CubeFace	face = `CubeFace::POS_X`,
		int	mipLevel = `0`,
		class RenderDevice *	rd = `NULL`
	)

Clear the texture to empty (typically after creation, so that it does not contain unitialized data).

Requires the Framebuffer Object extension.

rd If NULL, set to RenderDevice::lastRenderDeviceCreated

BETA API Likely to receive incompatible changes in future releases.

static void G3D::Texture::copy	(	shared_ptr< Texture >	src,
		shared_ptr< Texture >	dst,
		int	srcMipLevel = `0`,
		int	dstMipLevel = `0`,
		CubeFace	srcCubeFace = `CubeFace::POS_X`,
		CubeFace	dstCubeFace = `CubeFace::POS_X`,
		RenderDevice *	rd = `NULL`
	)

static

Copies src to dst, resizing if needed.

Both src and dst image formats are preserved.

For now, at least one of the following must hold: either dstMipLevel == 0, or srcMipLevel == dstMipLevel.

Uses a shader and makes a draw call.

API subject to change

BETA API Likely to receive incompatible changes in future releases.

void G3D::Texture::copyFromScreen	(	const Rect2D &	rect,
		const ImageFormat *	fmt = `NULL`
	)

Copies data from screen into an existing texture (replacing whatever was previously there).

The dimensions must be powers of two or a texture rectangle will be created (not supported on some cards).

This call is provided for backwards compatibility on old cards. It is substantially slower than simply rendering to a G3D::Texture using a G3D::Framebuffer.

The (x, y) coordinates are in OpenGL coordinates. If a FrameBuffer is bound then (0, 0) is the top left of the screen. When rendering directly to a window, (0,0) is the lower left. Use RenderDevice::copyTextureFromScreen to obtain consistent coordinates.

The texture dimensions will be updated but all other properties will be preserved: The previous wrap mode will be preserved. The interpolation mode will be preserved (unless it required a mipmap, in which case it will be set to BILINEAR_NO_MIPMAP). The previous color m_depth and alpha m_depth will be preserved. Texture compression is not supported for textures copied from the screen.

To copy a depth texture, first create an empty depth texture then copy into it.

If you invoke this method on a texture that is currently set on RenderDevice, the texture will immediately be updated (there is no need to rebind).

Parameters

rect	The rectangle to copy (relative to the viewport)
fmt	If NULL, uses the existing texture format, otherwise forces this texture to use the specified format.

See Also: RenderDevice::screenShotPic; RenderDevice::setReadBuffer

Deprecated:

void G3D::Texture::copyFromScreen	(	const Rect2D &	rect,
		CubeFace	face
	)

Copies into the specified face of a cube map.

Because cube maps can't have the Y direction inverted (and still do anything useful), you should render the cube map faces upside-down before copying them into the map. This is an unfortunate side-effect of OpenGL's cube map convention.

Use G3D::Texture::getCubeMapRotation to generate the (upside-down) camera orientations.

bool G3D_DEPRECATED G3D::Texture::copyInto	(	shared_ptr< Texture > &	dest,
		CubeFace	cf = `CubeFace::POS_X`,
		int	mipLevel = `0`,
		RenderDevice *	rd = `NULL`
	)		const

Copies this texture over dest, allocating or resizing dest as needed.

(It reallocs if the internal formats mismatch or dest is null) Uses a shader and makes a draw call. If src is a depth texture, mipLevel must be 0.

DEPRECATED: To be replaced with a clearer API before G3D9 final release.

Returns: true if dest was allocated/reallocated

static Ref G3D::Texture::create ( const Specification & s )

static

static shared_ptr<Texture> G3D::Texture::createColor ( const Color3unorm8 & c )

static

Creates a new 1x1 texture in this color.

Colors are not cached.

static shared_ptr<Texture> G3D::Texture::createColor ( const Color4unorm8 & c )

static

Creates a new 1x1 texture in this color.

Colors are not cached.

static shared_ptr<Texture> G3D::Texture::createEmpty	(	const std::string &	name,
		int	width,
		int	height,
		const ImageFormat *	desiredFormat = `ImageFormat::RGBA8()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		int	depth = `1`
	)

static

Creates an empty texture (useful for later reading from the screen).

See Also: clear()

static const CubeMapInfo& G3D::Texture::cubeMapInfo ( CubeMapConvention convention )

static

Returns the mapping from [0, 5] to cube map faces and filename suffixes.

There are multiple filename conventions, so the suffixes specify each of the options.

static Dimension G3D::Texture::defaultDimension ( )

static

Returns the default Dimension for this machine, which is DIM_2D_NPOT if supported and DIM_2D if not.

int G3D::Texture::depth ( ) const

inline

static CubeMapConvention G3D::Texture::determineCubeConvention ( const std::string & filename )

static

filename should contain a * wildcard

Dimension G3D::Texture::dimension ( ) const

inline

Referenced by fromImage(), and fromImageBuffer().

const ImageFormat* G3D::Texture::format ( ) const

inline

static shared_ptr<Texture> G3D::Texture::fromFile	(	const std::string &	filename,
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	process = `Preprocess()`,
		bool	preferSRGBForAuto = `false`
	)

static

Creates a texture from a single image.

The image must have a format understood by G3D::Image or a DirectDraw Surface (DDS). If dimension is DIM_CUBE_MAP, this loads the 6 files with names _ft, _bk, ... following the G3D::Sky documentation.

static shared_ptr<Texture> G3D::Texture::fromFile	(	const std::string	filename[6],
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	process = `Preprocess()`,
		bool	preferSRGBForAuto = `false`
	)

static

Creates a cube map from six independently named files.

The first becomes the name of the texture.

static shared_ptr<Texture> G3D::Texture::fromGLTexture	(	const std::string &	name,
		GLuint	textureID,
		const ImageFormat *	textureFormat,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`
	)

static

Wrap and interpolate will override the existing parameters on the GL texture.

Parameters

name	Arbitrary name for this texture to identify it
textureID	Set to newGLTextureID() to create an empty texture.

static shared_ptr<Texture> G3D::Texture::fromImage	(	const std::string &	name,
		const Image3::Ref &	image,
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	preprocess = `Preprocess::defaults()`
	)

inlinestatic

See Also: Texture::fromMemory

static shared_ptr<Texture> G3D_DEPRECATED G3D::Texture::fromImageBuffer	(	const std::string &	name,
		const PixelTransferBuffer::Ref &	image,
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	preprocess = `Preprocess::defaults()`
	)

inlinestatic

static shared_ptr<Texture> G3D::Texture::fromMemory	(	const std::string &	name,
		const Array< Array< const void * > > &	bytes,
		const ImageFormat *	bytesFormat,
		int	m_width,
		int	m_height,
		int	m_depth,
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	preprocess = `Preprocess::defaults()`,
		bool	preferSRGBForAuto = `false`
	)

static

Construct from an explicit set of (optional) mipmaps and (optional) cubemap faces.

bytes[miplevel][cubeface] is a pointer to the bytes for that miplevel and cube face. If the outer array has only one element and the interpolation mode is TRILINEAR_MIPMAP, mip-maps are automatically generated from the level 0 mip-map.

There must be exactly 6 cube faces per mip-level if the dimensions are DIM_CUBE and and 1 per mip-level otherwise. You may specify compressed and uncompressed formats for both the bytesformat and the desiredformat.

3D Textures map not use mip-maps.

Data is converted between normalized fixed point and floating point as described in section 2.1.5 of the OpenGL 3.2 specification. Specifically, uint8 values are converted to floating point by v' = v / 255.0f. Note that this differs from how G3D::Color1uint8 converts to G3D::Color3.

Note: OpenGL stores values at texel centers. Thus element at integer position (x, y) in the input "image" is stored at texture coordinate ((x + 0.5) / width, (x + 0.5) / height).

Referenced by fromImage().

static shared_ptr<Texture> G3D::Texture::fromMemory	(	const std::string &	name,
		const void *	bytes,
		const ImageFormat *	bytesFormat,
		int	m_width,
		int	m_height,
		int	m_depth,
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	preprocess = `Preprocess::defaults()`,
		bool	preferSRGBForAuto = `false`
	)

static

Construct from a single packed 2D or 3D data set.

For 3D textures, the interpolation mode must be one that does not use MipMaps.

static shared_ptr<Texture> G3D::Texture::fromPixelTransferBuffer	(	const std::string &	name,
		const PixelTransferBuffer::Ref &	image,
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	preprocess = `Preprocess::defaults()`
	)

static

Referenced by fromImageBuffer().

static shared_ptr<Texture> G3D::Texture::fromTwoFiles	(	const std::string &	filename,
		const std::string &	alphaFilename,
		const ImageFormat *	desiredFormat = `ImageFormat::AUTO()`,
		Dimension	dimension = `defaultDimension()`,
		const Settings &	settings = `Settings::defaults()`,
		const Preprocess &	process = `Preprocess()`
	)

static

Creates a texture from the colors of filename and takes the alpha values from the red channel of alpha filename.

See G3D::RenderDevice::setBlendFunc for important information about turning on alpha blending.

void G3D::Texture::generateMipMaps ( )

For a texture with automipmap off that supports the FrameBufferObject extension, generate mipmaps from the level 0 mipmap immediately.

For other textures, does nothing. TODO: Make it actually do nothing for unsupported textures...

static void G3D::Texture::getCubeMapRotation	(	CubeFace	face,
		Matrix3 &	outMatrix
	)

static

Returns the rotation matrix that should be used for rendering the given cube map face.

The orientations will seem to have the camera "upside down" compared to what you might expect because OpenGL's cube map convention and texture convention are both inverted from how we usually visualize the data.

The resulting cube maps can be saved to disk by:

const Texture::CubeMapInfo::Face& faceInfo = cubeMapInfo.face[f];
Image temp;
renderTarget->getImage(temp, ImageFormat::RGB8());
temp.flipVertical();
temp.rotate90CW(-faceInfo.rotations);
if (faceInfo.flipY) temp.flipVertical();
if (faceInfo.flipX) temp.flipHorizontal();
temp.save(format("out-%s.png", faceInfo.suffix.c_str()));

void G3D_DEPRECATED G3D::Texture::getTexImage	(	void *	data,
		const ImageFormat *	desiredFormat,
		CubeFace	face = `CubeFace::POS_X`,
		int	mipLevel = `0`
	)		const

Deprecated:: Use toPixelTransferBuffer

Call glGetTexImage with appropriate target. 

    This will normally perform a synchronous read, which causes
    the CPU to stall while the GPU catches up, and then stalls the
    GPU while data is being read.  For higher performance, use an
    OpenGL PixelBufferObject to perform an asynchronous read.  PBO
    is not abstracted by G3D.  The basic operation is:

    <pre>
        GLuint pbo;
        glGenBuffersARB(1, &pbo);
        glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, pbo);
        glBufferData(GL_PIXEL_PACK_BUFFER_ARB, dataByteSize, NULL, GL_STREAM_READ);
        glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, 0);
        debugAssertGLOk();

Issue the read (does not stall the GPU): glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, pbo); texture->getTexImage((void*)0, dataFormat); glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, 0);

[[ Do some CPU processing while waiting for the data to transfer asynchronously ]] ...

Bind the buffer. This will block if the data is not yet available. glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, pbo); void* data = glMapBuffer(GL_PIXEL_PACK_BUFFER_ARB, GL_READ_ONLY);

[[ Process the data ]] ...

glUnmapBuffer(GL_PIXEL_PACK_BUFFER_ARB); glBindBuffer(GL_PIXEL_PACK_BUFFER_ARB, 0);

Parameters

face	specifies the face of the cubemap

int G3D::Texture::height ( ) const

inline

Number of horizontal texels in the level 0 mipmap.

bool G3D::Texture::isCubeMap ( ) const

inline

static bool G3D::Texture::isSupportedImage ( const std::string & filename )

static

Returns true if the specified filename exists and is an image that can be loaded as a Texture.

Color4 G3D::Texture::max ( ) const

inline

If this texture was loaded from an uncompressed format in memory or disk (and not rendered to), this is the largest value in the texture.

Color4 G3D::Texture::mean ( ) const

inline

If this texture was loaded from an uncompressed format in memory or disk (and not rendered to), this is the average value in the texture.

Color4 G3D::Texture::min ( ) const

inline

If this texture was loaded from an uncompressed format in memory or disk (and not rendered to), this is the smallest value in the texture.

const std::string& G3D::Texture::name ( ) const

inline

static unsigned int G3D::Texture::newGLTextureID ( )

static

Helper method.

Returns a new OpenGL texture ID that is not yet managed by a G3D Texture.

static shared_ptr<Texture> G3D::Texture::one ( )

inlinestatic

Returns a small all-white (1,1,1,1) texture. .

The result is memoized and shared. Do not mutate this texture or future calls will return the mutated texture as well. .

bool G3D::Texture::opaque ( ) const

inline

True if this texture was created with an alpha channel.

Note that a texture may have a format that is not opaque (e.g. RGBA8) yet still have a completely opaque alpha channel, causing texture->opaque to be true. This is just a flag set for the user's convenience– it does not affect rendering in any way. See G3D::RenderDevice::setBlendFunc for important information about turning on alpha blending.

static shared_ptr<Texture> G3D::Texture::opaqueBlack ( )

static

Returns a small opaque all-black (0,0,0,1) texture.

The result is memoized and shared. Do not mutate this texture or future calls will return the mutated texture as well.

Referenced by opaqueBlackIfNull().

static shared_ptr<Texture> G3D::Texture::opaqueBlackCube ( )

static

Returns a small opaque all-black (0,0,0,1) texture.

The result is memoized and shared. Do not mutate this texture or future calls will return the mutated texture as well.

static shared_ptr<Texture> G3D::Texture::opaqueBlackIfNull ( const shared_ptr< Texture > & t )

inlinestatic

Returns t if it is non-NULL, or opaqueBlack() if t is NULL.

static shared_ptr<Texture> G3D::Texture::opaqueGray ( )

static

Returns a small all-gray (0.5,0.5,0.5,1) texture.

The result is memoized and shared. Do not mutate this texture or future calls will return the mutated texture as well.

Referenced by opaqueGrayIfNull().

static shared_ptr<Texture> G3D::Texture::opaqueGrayIfNull ( const shared_ptr< Texture > & t )

inlinestatic

Returns t if it is non-NULL, or gray() if t is NULL.

unsigned int G3D::Texture::openGLID ( ) const

inline

unsigned int G3D::Texture::openGLTextureTarget ( ) const

The OpenGL texture target this binds (e.g.

GL_TEXTURE_2D)

Color4 G3D::Texture::readTexel	(	int	ix,
		int	iy,
		class RenderDevice *	rd = `NULL`
	)		const

Reads back a single texel.

This is slow because it stalls the CPU on the GPU. However, it requires less bandwidth than reading an entire image.

BETA API Likely to receive incompatible changes in future releases.

rd If NULL, set to RenderDevice::lastRenderDeviceCreated;

See Also: toPixelTransferBuffer

Rect2D G3D::Texture::rect2DBounds ( ) const

Returns a rectangle whose m_width and m_height match the dimensions of the texture.

void G3D::Texture::resize	(	int	w,
		int	h
	)

Resize the underlying OpenGL texture memory buffer, without reallocating the OpenGL texture ID.

This does not scale the contents; the contents are undefined after resizing. This is only useful for textures that are render targets.

void G3D::Texture::setAutoMipMap ( bool b )

Set the autoMipMap value, which only affects textures when they are rendered to or copied from the screen.

You can read the automipmap value from settings().autoMipMap.

void G3D::Texture::setDepthReadMode ( Texture::DepthReadMode depthReadMode )

Allows forcing a change to the depthReadMode of the texture currently bound to the target.

const Settings& G3D::Texture::settings ( ) const

Referenced by fromImage(), and fromImageBuffer().

int G3D::Texture::sizeInMemory ( ) const

How much (texture) memory this texture occupies.

OpenGL backs video memory textures with main memory, so the total memory is actually twice this number.

static int64 G3D::Texture::sizeOfAllTexturesInMemory ( )

inlinestatic

Video memory occupied by all OpenGL textures allocated using Texture or maintained by pointers to a Texture.

static void G3D::Texture::splitFilenameAtWildCard	(	const std::string &	filename,
		std::string &	filenameBeforeWildCard,
		std::string &	filenameAfterWildCard
	)

static

Splits a filename around the '*' character– used by cube maps to generate all filenames.

static bool G3D::Texture::supportsWrapMode ( WrapMode m )

inlinestatic

Returns true if this is a legal wrap mode for a G3D::Texture.

Image1unorm8Ref G3D::Texture::toDepthImage1unorm8 ( ) const

Extracts the data as ImageFormat::DEPTH32F and converts to 8-bit.

Note that you may want to call Image1unorm8::flipVertical if Texture::invertY is true.

Map2D<float>::Ref G3D::Texture::toDepthMap ( ) const

Extracts the data as ImageFormat::DEPTH32F.

static DepthReadMode G3D::Texture::toDepthReadMode ( const std::string & s )

static

static Dimension G3D::Texture::toDimension ( const std::string & s )

static

shared_ptr<Image> G3D::Texture::toImage	(	const ImageFormat *	outFormat = `ImageFormat::AUTO()`,
		int	mipLevel = `0`,
		CubeFace	face = `CubeFace::POS_X`
	)		const

static InterpolateMode G3D::Texture::toInterpolateMode ( const std::string & s )

static

shared_ptr<GLPixelTransferBuffer> G3D::Texture::toPixelTransferBuffer	(	const ImageFormat *	outFormat = `ImageFormat::AUTO()`,
		int	mipLevel = `0`,
		CubeFace	face = `CubeFace::POS_X`
	)		const

static const char* G3D::Texture::toString ( InterpolateMode m )

static

static const char* G3D::Texture::toString ( DepthReadMode m )

static

static const char* G3D::Texture::toString ( Dimension m )

static

void G3D::Texture::update	(	const shared_ptr< PixelTransferBuffer > &	src,
		int	mipLevel = `0`,
		CubeFace	face = `CubeFace::POS_X`
	)

Upload new data from the CPU to this texture.

Corresponds to glTexSubImage2D. If src is smaller than the current dimensions of this, only part of this is updated.

This routine does not provide the same protections as creating a new Texture from memory: you must handle scaling and ensure compatible formats yourself.

Parameters

face	If specified, determines the cubemap face to copy into
src	GLPixelTransferBuffer is handled specially to support updates when the buffer is not yet PixelTransferBuffer::readyToMap. All other PixelTransferBuffers are mapped for read. The upload to the GPU is asynchronous (assuming that the GPU driver is reasonable) and the buffer may be modified immediately on return.

Vector2 G3D::Texture::vector2Bounds ( ) const

inline

static shared_ptr<Texture> G3D::Texture::white ( )

static

Returns a small all-white (1,1,1,1) texture.

The result is memoized and shared. Do not mutate this texture or future calls will return the mutated texture as well.

Referenced by one(), and whiteIfNull().

static shared_ptr<Texture> G3D::Texture::whiteCube ( )

static

Returns a small all-white (1,1,1,1) cube map texture.

The result is memoized and shared. Do not mutate this texture or future calls will return the mutated texture as well.

Referenced by whiteCubeIfNull().

static shared_ptr<Texture> G3D::Texture::whiteCubeIfNull ( const shared_ptr< Texture > & t )

inlinestatic

Returns t if it is non-NULL, or whiteCube() if t is NULL.

static shared_ptr<Texture> G3D::Texture::whiteIfNull ( const shared_ptr< Texture > & t )

inlinestatic

Returns t if it is non-NULL, or white() if t is NULL.

int G3D::Texture::width ( ) const

inline

Number of horizontal texels in the level 0 mipmap.

static shared_ptr<Texture> G3D::Texture::zero ( )

static

Returns a small, all zero Color4(0,0,0,0) texture.

The result is memoized and shared. Do not mutate this texture or future calls will return the mutated texture as well.

Referenced by zeroIfNull().

static shared_ptr<Texture> G3D::Texture::zeroIfNull ( const shared_ptr< Texture > & t )

inlinestatic

Returns t if it is non-NULL, or zero() if t is NULL.

Friends And Related Function Documentation

template<class C , class I >

friend class Component

friend

template<class I >

friend class MapComponent

friend

Member Data Documentation

Visualization G3D::Texture::visualization

Used to display this Texture in a GuiTextureBox.

BETA API Likely to receive incompatible changes in future releases.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation