Texture Class Reference

Texture is a hardware-independent container for a pixel data. More...

Classes
class	ArrayIndex
	Helper class used in Texture::imageData() function. More...
class	ArraySize
	Helper class used in Texture constructors. More...
class	Size
	Helper class used in Texture constructors. More...

Public Types
enum	Side {   Side::PositiveX = 0, Side::NegativeX = 1, Side::PositiveY = 2, Side::NegativeY = 3,   Side::PositiveZ = 4, Side::NegativeZ = 5 }
enum	Alignment { Alignment::Byte = 1, Alignment::Word = 4 }
enum	IsCubemap { IsCubemap::No = 0, IsCubemap::Yes }
using	Data = gsl::span< uchar >
using	ConstData = gsl::span< const uchar >

Public Member Functions
	Texture () noexcept
	Constructs a null texture. More...
	Texture (const Texture &other)
	Constructs a shallow copy of the other texture.
	Texture (Texture &&other) noexcept
	Move-constructs a Texture instance with the given other Texture.
	Texture (const QString &file)
	Constructs a Texture instance with the contents of the file. More...
	Texture (QStringView file)
	Constructs a Texture instance with the contents of the file. More...
	Texture (const QImage &image)
	Constructs a Texture instance with the contents of the image. More...
	Texture (TextureFormat format, Size size, ArraySize dimensions={1, 1}, Alignment align=Alignment::Byte)
	Constructs a Texture instance with the given format, size, dimensions and align. More...
	Texture (Data data, TextureFormat format, Size size, ArraySize dimensions={1, 1}, Alignment align=Alignment::Byte)
	Constructs a Texture instance with the given data, format, size, dimensions and align. More...
	Texture (Data data, DataDeleter deleter, TextureFormat format, Size size, ArraySize dimensions={1, 1}, Alignment align=Alignment::Byte)
	Constructs a Texture instance with the given data, deleter, format, size, dimensions and align. More...
	~Texture ()
	Destroys the Texture instance.
Texture &	operator= (const Texture &other)
	Assigns a shallow copy of the given other texture to this texture and returns a reference to this texture.
Texture &	operator= (Texture &&other) noexcept
	Move-assigns other to this Texture instance.
bool	isNull () const
	Returns true if this instance is a null texture. More...
TextureFormat	format () const
	Returns the format of the texture.
Alignment	alignment () const
	Returns the alignment of the texture data. More...
bool	isCompressed () const
	Returns true if the texture has one of the compressed formats.
int	width () const
	Returns the width of the biggest mipmap.
int	width (int level) const
	Returns the width of the mipmap at the given level.
int	height () const
	Returns the height of the biggest mipmap.
int	height (int level) const
	Returns the height of the mipmap at the given level.
int	depth () const
	Returns the depth of the biggest mipmap.
int	depth (int level) const
	Returns the depth of the mipmap at the given level.
Size	size () const
	Returns the width, height and depth of the biggest mipmap packed in a Texture::Size object.
Size	size (int level) const
	Returns the width, height and depth of the mipmap at the given level packed in a Texture::Size object.
int	faces () const
	Returns the faces count.
int	levels () const
	Returns the levels count.
int	layers () const
	Returns the layers count.
ArraySize	arraySize () const
	Returns the texture dimensions.
qsizetype	bytes () const
	Returns the total size of the texture data in bytes.
qsizetype	bitsPerTexel () const
	Returns the amount of bits per one texel (texture pixel).
qsizetype	bytesPerLine (int level=0) const
	Returns the amount of bytes per line of the mipmap at the given level.
qsizetype	bytesPerSlice (int level=0) const
	Returns the amount of bytes per slice of the mipmap at the given level.
qsizetype	bytesPerImage (int level=0) const
	Returns the amount of bytes used by the whole mipmap at the given level.
Data	imageData (ArrayIndex index)
	Returns the data of the image at the given index.
ConstData	imageData (ArrayIndex index) const
	Returns the constant data of the image at the given index.
ConstData	constImageData (ArrayIndex index) const
	Returns the constant data of the image at the given index.
Texture	convert (Alignment align) const
	Converts this texture to a texture with the given alignment. More...
Texture	convert (TextureFormat format) const
	Converts this texture to a texture with the given format. More...
Texture	convert (TextureFormat format, Alignment align) const
	Converts this texture to a texture with the given format and align.
Texture	copy () const
	Performs a deep-copying of this texture.
QImage	toImage () const
	Converts this texture to a QImage.
TextureIOResult	save (const QString &file)
	Saves this texture to the given file.
TextureIOResult	load (const QString &file)
	Loads a texture from the given file.

Static Public Member Functions
static qsizetype	calculateBytesPerLine (TextureFormat format, int width, Alignment align=Alignment::Byte)
	Calculates an amount of bytes required for the line of the given format, width and align.
static qsizetype	calculateBytesPerSlice (TextureFormat format, int width, int height, Alignment align=Alignment::Byte)
	Calculates an amount of bytes required for the slice of the given format, width and align.

Detailed Description

Texture is a hardware-independent container for a pixel data.

Unlike QOpenGLTexture, Texture is a simple storage (an array of bytes) and is not tied to any specific API. However, it can be converted to QOpenGLTexture via Utils::makeOpenGLTexture() function.

Texture is a multi-dimentional array of "images" (which can be 1d, 2d or 3d). There are 3 dimentions - levels (for mimpamps), layers (for texture arrays) and faces (for faces of the cubemap).

Helper classes are used to simplify Texture construction - the sizes are packed in a Texture::Size (so you can create 1d, 2d or 3d Texture instances without 3 overloads for each type) and texture dimensions are packed in an Texture::ArraySize (so you can create mipmaped textures, texture array and/or cubemaps).

Texture provides access to the internal data via data() and imageData() functions.

Note

For cubemaps, width should be same as height and depth should be equal to 1.

For 3d textures, arrays are not supported as no format does so.

Member Typedef Documentation

ConstData

Texture::ConstData

Type alias for a gsl::span<const uchar>

A view to a constant data.

Data

Texture::Data

Type alias for a gsl::span<uchar>

A view to a mutable data.

Member Enumeration Documentation

Alignment

enum Texture::Alignment

strong

This enum describes texture data alignment

Enumerator
Byte	One byte alignment
Word	Four byte alignment

IsCubemap

enum Texture::IsCubemap

strong

This enum is a simply strict bool used to prevent using unnamed bools

Enumerator
No	Aka false
Yes	Aka true

Side

enum Texture::Side

strong

This enum describes possible sides of a cubemap.

Enumerator
PositiveX	Positive X side
NegativeX	Negative X side
PositiveY	Positive Y side
NegativeY	Negative Y side
PositiveZ	Positive Z side
NegativeZ	Negative Z side

Constructor & Destructor Documentation

Texture() [1/7]

Texture::Texture ( )

inlinenoexcept

Constructs a null texture.

See also

isNull()

Texture() [2/7]

Texture::Texture ( const QString &  file )

explicit

Constructs a Texture instance with the contents of the file.

In case of an error, a null texture is constructed and error is logged to the stderr.

See also

isNull()

Texture() [3/7]

Texture::Texture ( QStringView  file )

explicit

Constructs a Texture instance with the contents of the file.

In case of an error, a null texture is constructed and error is logged to the stderr.

See also

isNull()

Texture() [4/7]

Texture::Texture ( const QImage &  image )

explicit

Constructs a Texture instance with the contents of the image.

An image is converted to a single 2D texture with no mipmaps.

If image has aplha, the constucted texture will have TextureFormat::RGBA8_Unorm format.

If image has no aplha, the constucted texture will have TextureFormat::RGB8_Unorm format.

Note

Currently, only images with QImage::Format_ARGB32 or QImage::Format_RGB888 are supported. In other cases, null texture is constructed.

See also

isNull()

Texture() [5/7]

Texture::Texture	(	TextureFormat	format,
		Size	size,
		ArraySize	dimensions = {1, 1},
		Texture::Alignment	align = Alignment::Byte
	)

Constructs a Texture instance with the given format, size, dimensions and align.

Passing invalid parameters leads to construction of a null texture; an exact error is logged to stderr. Invalid parameters are sizes less than zero, or too big to fit whole texture in memory.

See also

isNull()

Texture() [6/7]

Texture::Texture	(	Data	data,
		TextureFormat	format,
		Size	size,
		ArraySize	dimensions = {1, 1},
		Texture::Alignment	align = Alignment::Byte
	)

Constructs a Texture instance with the given data, format, size, dimensions and align.

Passing invalid parameters leads to construction of a null texture; an exact error is logged to stderr. Invalid parameters are sizes less than zero, or too big to fit whole texture in memory.

This constructor doesn't allocate memory but instead uses the given data. Data must have the size matching given parameters.

The default destructor (i.e. delete [] data) is used for cleaning the data.

See also

isNull()

Texture() [7/7]

Texture::Texture	(	Data	data,
		Texture::DataDeleter	deleter,
		TextureFormat	format,
		Size	size,
		ArraySize	dimensions = {1, 1},
		Texture::Alignment	align = Alignment::Byte
	)

Constructs a Texture instance with the given data, deleter, format, size, dimensions and align.

Passing invalid parameters leads to construction of a null texture; an exact error is logged to stderr. Invalid parameters are sizes less than zero, or too big to fit whole texture in memory.

This constructor doesn't allocate memory but instead uses the given data. Data must have the size matching given parameters.

The deleter is used for cleaning the data. You can pass an empty function to prevent data from cleaning. This trick can be used to implement sharing of the data between different Texture instances.

See also

isNull()

Member Function Documentation

alignment()

Texture::Alignment Texture::alignment

(

)

const

Returns the alignment of the texture data.

The data can have different alignment meaning that each line of the data is aligned to a specific boundary.

convert() [1/2]

Texture Texture::convert

(

Texture::Alignment

align

)

const

Converts this texture to a texture with the given alignment.

The format of the resulting texture is the same as the format of this texture.

convert() [2/2]

Texture Texture::convert

(

TextureFormat

format

)

const

Converts this texture to a texture with the given format.

The alignment of the resulting texture is the same as the alignment of this texture.

isNull()

bool Texture::isNull

(

)

const

Returns true if this instance is a null texture.

Null texture has no allocated data and all properties are null