Encapsulates the state attached to an OpenGL texture.

#include <Rendering/OpenGL/wsgltexture.h>

Inherits QOpenGLFunctions.

Public Types
enum	DepthTextureCompareFunction { Never = GL_NEVER , Less = GL_LESS , Equal = GL_EQUAL , LEqual = GL_LEQUAL , Greater = GL_GREATER , NotEqual = GL_NOTEQUAL , GEqual = GL_GEQUAL , Always = GL_ALWAYS }

enum	DepthTextureCompareMode { CompareRToTexture = GL_COMPARE_R_TO_TEXTURE , None = GL_NONE }

enum	Filtering { Nearest = GL_NEAREST , Linear = GL_LINEAR , NearestMipmapNearest = GL_NEAREST_MIPMAP_NEAREST , LinearMipmapNearest , NearestMipmapLinear , LinearMipmapLinear }

enum	Format { Red = GL_RED , Green , Blue , Alpha = GL_ALPHA , Rgb = GL_RGB , Rgba = GL_RGBA , Luminance , LuminanceAlpha , Bgr = GL_BGR , Bgra = GL_BGRA , Depth = GL_DEPTH_COMPONENT , Stencil = GL_STENCIL_INDEX , Rg = GL_RG }

enum	SlicePlane { XY , XZ , YZ }

enum	Wrap { Clamp = GL_CLAMP , ClampToBorder = GL_CLAMP_TO_BORDER , ClampToEdge = GL_CLAMP_TO_EDGE , MirroredRepeat = GL_MIRRORED_REPEAT , Repeat = GL_REPEAT }

Public Member Functions
	~WSGLTexture ()

bool	allocate (const ColorArray &data, QOpenGLBuffer::UsagePattern usage, bool generateMipmaps=false)

bool	allocate (const DataAnalysis::Image3d &data, Format format, QOpenGLBuffer::UsagePattern usage, bool generateMipmaps=false)

bool	allocate (const QImage &data, QOpenGLBuffer::UsagePattern usage, bool generateMipmaps=false)

bool	allocate (const TextureImage &image)

bool	allocate (int width, int height, Format format, GLuint internalFormat, GLuint componentDataType, QOpenGLBuffer::UsagePattern usage, bool generateMipmaps=false)

bool	allocate (int width, int height, Format format, GLuint internalFormat, GLuint componentDataType, QOpenGLBuffer::UsagePattern usage, void *data, GLsizeiptr dataSize, bool generateMipmaps=false)

bool	allocateSlice (const DataAnalysis::Image3d &data, QOpenGLBuffer::UsagePattern usage, SlicePlane plane, int sliceNum, int sampleDist=1, bool generateMipmaps=false)

bool	bind ()

WSGLBufferObjectCacheItemPtr	getBuffer ()

GLuint	getGlId () const

void	notifyBufferUpdated (int width, int height, int depth, Format format, GLuint internalFormat, GLuint componentDataType, bool generateMipmaps=false)

bool	release ()

void	setDepthTextureCompare (DepthTextureCompareMode compareMode, DepthTextureCompareFunction compareFunction, GLuint depthTextureMode)

void	setFiltering (bool interpolate)

void	setFiltering (Filtering minFilter, Filtering magFilter)

void	setMipmapLevels (int minLevel, int maxLevel)

void	setWrap (Texturizer::Wrapping wrap)

void	setWrap (Wrap wrapS)

void	setWrap (Wrap wrapS, Wrap wrapT)

void	setWrap (Wrap wrapS, Wrap wrapT, Wrap wrapR)

bool	updateTexture (const QImage &data, bool generateMipmaps=false)

Protected Member Functions
	WSGLTexture (WSGLBufferObjectCache &boCache)

Member Enumeration Documentation

◆ DepthTextureCompareFunction

enum DepthTextureCompareFunction

Defines the comparison function used for depth tests.

Enumerator
Never
Less
Equal
LEqual
Greater
NotEqual
GEqual
Always

◆ DepthTextureCompareMode

enum DepthTextureCompareMode

Used to set the comparison mode for depth textures.

Enumerator
CompareRToTexture
None

◆ Filtering

enum Filtering

Types of filters that can be used to control a texture's appearance when minified or magnified.

Enumerator
Nearest
Linear
NearestMipmapNearest
LinearMipmapNearest
NearestMipmapLinear
LinearMipmapLinear

◆ Format

enum Format

Specifies the format of the pixel data.

Enumerator
Red
Green
Blue
Alpha
Rgb
Rgba
Luminance
LuminanceAlpha
Bgr
Bgra
Depth
Stencil
Rg

◆ SlicePlane

enum SlicePlane

Enumerator
XY
XZ
YZ

◆ Wrap

enum Wrap

How to interpret texture coordinates outside the range [0.0, 1.0]

Enumerator
Clamp
ClampToBorder
ClampToEdge
MirroredRepeat
Repeat

Constructor & Destructor Documentation

◆ ~WSGLTexture()

~WSGLTexture ( )

◆ WSGLTexture()

WSGLTexture ( WSGLBufferObjectCache & boCache )

protected

Creates a new WSGLTexture, generating an OpenGL texture object for it.

Note: this must only be called while a valid OpenGL context is current.

Member Function Documentation

◆ allocate() [1/6]

bool allocate	(	const ColorArray &	data,
		QOpenGLBuffer::UsagePattern	usage,
		bool	generateMipmaps = `false`
	)

Parameters

data	The data to store in the texture when it is allocated.
usage	Hint to the GL as to how the texture data is going to be used.
generateMipmaps	Whether or not to automatically generate and store a mipmap chain with this texture.

Returns: true if the allocation is successful, false otherwise.

Allocates 1D texture data for our WSGLTexture, using the input color array as the data source. After this function is called, the WSGLTexture will be a 1D texture.

◆ allocate() [2/6]

bool allocate	(	const DataAnalysis::Image3d &	data,
		Format	format,
		QOpenGLBuffer::UsagePattern	usage,
		bool	generateMipmaps = `false`
	)

Parameters

data	The data to store in the texture when it is allocated.
format	The desired texture format
usage	Hint to the GL as to how the texture data is going to be used.
generateMipmaps	Whether or not to automatically generate and store a mipmap chain with this texture.

Returns: true if the allocation is successful, false otherwise.

Allocates the data for the WSGLTexture, specifying it to be a 3D texture with the input Image3d as data. After this function is called, the WSGLTexture will be a 3D texture.

◆ allocate() [3/6]

bool allocate	(	const QImage &	data,
		QOpenGLBuffer::UsagePattern	usage,
		bool	generateMipmaps = `false`
	)

Parameters

data	The data to store in the texture when it is allocated.
usage	Hint to the GL as to how the texture data is going to be used.
generateMipmaps	Whether or not to automatically generate and store a mipmap chain with this texture.

Returns: true if the allocation is successful, false otherwise.

Allocates 2D texture data for our WSGLTexture, using the input QImage as the data source. After this function is called, the WSGLTexture will be a 3D texture.

◆ allocate() [4/6]

bool allocate ( const TextureImage & image )

Parameters

image The texture image to use for data, dimensions and format when allocating the texture.

Returns: true if the allocation is successful, false otherwise.

Allocates the data associated with the texture in the GL, using the input texture image as a specification of what the format, size and data should be.

◆ allocate() [5/6]

bool allocate	(	int	width,
		int	height,
		Format	format,
		GLuint	internalFormat,
		GLuint	componentDataType,
		QOpenGLBuffer::UsagePattern	usage,
		bool	generateMipmaps = `false`
	)

Parameters

width	The desired width of the texture in texels.
height	The desired height of the texture in texels.
format	The desired format of the texture, as it will be used by the GL.
internalFormat	Specifies the number of color components in the texture. Must be 1, 2, 3, or 4, or one of the following symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, GL_DEPTH_COMPONENT32, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_R3_G3_B2, GL_RGB, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, GL_RGBA16, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA, GL_SLUMINANCE8_ALPHA8, GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, or GL_SRGB8_ALPHA8.
componentDataType	Specifies the data type of the pixel data, i.e. the format of a single color component. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and GL_UNSIGNED_INT_2_10_10_10_REV.
usage	Hint to the GL as to how the texture data is going to be used.
generateMipmaps	Whether or not to automatically generate and store a mipmap chain with this texture.

Returns: true if the allocation is successful, false otherwise.

Allocates the data for the WSGLTexture, specifying it to be a 2D texture with the desired format, internal format, component data type. It also provides facilities for suggesting to the GL how the texture data will be accessed, and generating mipmap data.

After this function is called, the WSGLTexture will be a 2D texture.

◆ allocate() [6/6]

bool allocate	(	int	width,
		int	height,
		Format	format,
		GLuint	internalFormat,
		GLuint	componentDataType,
		QOpenGLBuffer::UsagePattern	usage,
		void *	data,
		GLsizeiptr	dataSize,
		bool	generateMipmaps = `false`
	)

Parameters

width	The desired width of the texture in texels.
height	The desired height of the texture in texels.
format	The desired format of the texture, as it will be used by the GL.
internalFormat	Specifies the number of color components in the texture. Must be 1, 2, 3, or 4, or one of the following symbolic constants: GL_ALPHA, GL_ALPHA4, GL_ALPHA8, GL_ALPHA12, GL_ALPHA16, GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, GL_DEPTH_COMPONENT32, GL_LUMINANCE, GL_LUMINANCE4, GL_LUMINANCE8, GL_LUMINANCE12, GL_LUMINANCE16, GL_LUMINANCE_ALPHA, GL_LUMINANCE4_ALPHA4, GL_LUMINANCE6_ALPHA2, GL_LUMINANCE8_ALPHA8, GL_LUMINANCE12_ALPHA4, GL_LUMINANCE12_ALPHA12, GL_LUMINANCE16_ALPHA16, GL_INTENSITY, GL_INTENSITY4, GL_INTENSITY8, GL_INTENSITY12, GL_INTENSITY16, GL_R3_G3_B2, GL_RGB, GL_RGB4, GL_RGB5, GL_RGB8, GL_RGB10, GL_RGB12, GL_RGB16, GL_RGBA, GL_RGBA2, GL_RGBA4, GL_RGB5_A1, GL_RGBA8, GL_RGB10_A2, GL_RGBA12, GL_RGBA16, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA, GL_SLUMINANCE8_ALPHA8, GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, or GL_SRGB8_ALPHA8.
componentDataType	Specifies the data type of the pixel data, i.e. the format of a single color component. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_BYTE, GL_BITMAP, GL_UNSIGNED_SHORT, GL_SHORT, GL_UNSIGNED_INT, GL_INT, GL_FLOAT, GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, and GL_UNSIGNED_INT_2_10_10_10_REV.
usage	Hint to the GL as to how the texture data is going to be used.
data	A pointer to the raw data to upload to the pixel-buffer-object.
dataSize	The number of bytes of the buffer pointed to by data
generateMipmaps	Whether or not to automatically generate and store a mipmap chain with this texture.

Returns: true if the allocation is successful, false otherwise.

Allocates the data for the WSGLTexture, specifying it to be a 2D texture with the desired format, internal format, component data type. It also provides facilities for suggesting to the GL how the texture data will be accessed, and generating mipmap data.

After this function is called, the WSGLTexture will be a 2D texture.

◆ allocateSlice()

bool allocateSlice	(	const DataAnalysis::Image3d &	data,
		QOpenGLBuffer::UsagePattern	usage,
		SlicePlane	plane,
		int	sliceNum,
		int	sampleDist = `1`,
		bool	generateMipmaps = `false`
	)

◆ bind()

bool bind ( )

Binds the texture to the current context's active texture unit. Equivalent to glBindTexture(id)

Returns: true if the bind operation was successful, false otherwise. It should only fail if there is no active context, or if the texture hasn't yet been allocated. Client code can choose to ignore this in certain circumstances.

◆ getBuffer()

WSGLBufferObjectCacheItemPtr getBuffer ( )

Returns: The pixel buffer object (bufferobjectcacheitem) associated with this texture.

Returns the BufferObject associated with this texture, i.e. the buffer that its texture data is stored in.

Note: If the texture has not been allocated, this will return an invalid pointer.

◆ getGlId()

GLuint getGlId ( ) const

Returns: The GL identifier of this textur.

Returns the internal GL identifier for this texture, which can be used to manually bind the texture, or attach it to FBOs etc.

◆ notifyBufferUpdated()

void notifyBufferUpdated	(	int	width,
		int	height,
		int	depth,
		WSGLTexture::Format	format,
		GLuint	internalFormat,
		GLuint	componentDataType,
		bool	generateMipMaps = `false`
	)

Parameters

width	The width of the texture data stored in the buffer.
height	The height of the texture data stored in the buffer. Value greater than 1 will indicate a 2D or 3D texture.
depth	The depth of the texture data stored in the buffer. Value greater than 1 will indicate a 3D texture.
format	The desired format of the texture.
internalFormat	The format that the data has been stored inside the buffer
componentDataType	The data type of individual components of each texel; for example for RGBA, this is often GL_UNSIGNED_BYTE.
generateMipMaps	If true, mip maps will be generated for the texture.

If we directly modify the underlying pixel buffer object, we need to notify the texture that it's data has changed, and that it therefore needs to update the OpenGL texture information associated with it.

◆ release()

bool release ( )

Unbinds the texture from the current context's active texture unit. Equivalent to glBindTexture(0)

Returns: true if the unbind operation is successful, false otherwise.

◆ setDepthTextureCompare()

void setDepthTextureCompare	(	WSGLTexture::DepthTextureCompareMode	compareMode,
		WSGLTexture::DepthTextureCompareFunction	compareFunction,
		GLuint	depthTextureMode
	)

Indicates that this texture is a depth texture. This means we can use the texture in a shader using shadow2D(), which will perform a depth test for us, and provide us a result in a vector. To understand how this comparison works, see below:

If R is the currently interpolated texture coordinate clamped to [0, 1], and Dt is the depth value at that coordinate in the range [0, 1], then the value Lt, It, At is equal to:

(If compare func == GREATER) result = { 1.0, if R > Dt { { 0.0, if R <= Dt

The result is a vec4 in the shader, just like a normal texture sample, with the depth test result stored in the the location corresponding to our depth mode parameter.

To give an example, in the case of depth peeling, the R texture coordinate will be the pixel z window coord (depth) - see the wsgldepthpeeling.inc. Since pixel depth is in the range [0, 1] (0.0 being the closest to the eye, and 1.0 is the farthest), the results of our test can be summarized as:

If any pixel is further away than the pixel in the depth texture, add it to the color and depth buffers. Because depth testing is on, the end result is that the closest pixels that are further away than those in the last layer will be drawn.

◆ setFiltering() [1/2]

void setFiltering ( bool interpolate )

Parameters

interpolate Whether or not to "interpolate" the texture, which means to apply linear minification and linear magnification filters.

◆ setFiltering() [2/2]

void setFiltering	(	WSGLTexture::Filtering	minFilter,
		WSGLTexture::Filtering	magFilter
	)

Parameters

minFilter	Controls how the texture is filtered when it is minified. Allowed values are Nearest, Linear, NearestMipmapNearest, LinearMipmapNearest, NearestMipmapLinear, LinearMipmapLinear.
magFilter	Controls how the texture is filtered when it is magnified. Allowed values are Nearest, Linear.

Controls how the texture will be filtered when it is magnified or minified. See WSGLTexture::Filtering for more information.

◆ setMipmapLevels()

void setMipmapLevels	(	int	minLevel,
		int	maxLevel
	)

Parameters

minLevel	The base level of mipmap that can be used when maps are automatically selected.
maxLevel	The maximum mipmap level that will be used.

Controls the range of mipmaps available to the application for selection.

◆ setWrap() [1/4]

void setWrap ( Texturizer::Wrapping wrap )

Parameters

wrap	The type of wrapping to apply to the S, T (and potentially R) dimensions.

◆ setWrap() [2/4]

void setWrap ( WSGLTexture::Wrap wrapS )

Parameters

wrapS Controls how the texture will wrap in the S dimension.

Sets the wrap property of the texture in the S dimension. Can be invoked on 1D, 2D or 3D textures.

◆ setWrap() [3/4]

void setWrap	(	WSGLTexture::Wrap	wrapS,
		WSGLTexture::Wrap	wrapT
	)

Parameters

wrapS	Controls how the texture will wrap in the S dimension.
wrapT	Controls how the texture will wrap in the T dimension.

Sets the wrap property of the texture (if it's a 2D or 3D texture only).

◆ setWrap() [4/4]

void setWrap	(	WSGLTexture::Wrap	wrapS,
		WSGLTexture::Wrap	wrapT,
		WSGLTexture::Wrap	wrapR
	)

Parameters

wrapS	Controls how the texture will wrap in the S dimension.
wrapT	Controls how the texture will wrap in the T dimension.
wrapR	Controls how the texture will wrap in the R dimension.

Sets the wrap property of the texture (if it's a 3D texture only).

◆ updateTexture()

bool updateTexture	(	const QImage &	data,
		bool	generateMipmaps = `false`
	)

Parameters

data	The data to upload to the texture.
generateMipmaps	Whether or not to generate mipmaps for the updated texture data

Updates the texture to use the specified image.

Public Types

Public Member Functions

Protected Member Functions

Member Enumeration Documentation

◆ DepthTextureCompareFunction

◆ DepthTextureCompareMode

◆ Filtering

◆ Format

◆ SlicePlane

◆ Wrap

Constructor & Destructor Documentation

◆ ~WSGLTexture()

◆ WSGLTexture()

Member Function Documentation

◆ allocate() [1/6]

◆ allocate() [2/6]

◆ allocate() [3/6]

◆ allocate() [4/6]

◆ allocate() [5/6]

◆ allocate() [6/6]

◆ allocateSlice()

◆ bind()

◆ getBuffer()

◆ getGlId()

◆ notifyBufferUpdated()

◆ release()

◆ setDepthTextureCompare()

◆ setFiltering() [1/2]

◆ setFiltering() [2/2]

◆ setMipmapLevels()

◆ setWrap() [1/4]

◆ setWrap() [2/4]

◆ setWrap() [3/4]

◆ setWrap() [4/4]

◆ updateTexture()