PLRenderer::TextureBuffer Class Reference

Abstract renderer texture buffer resource base class. More...

#include <TextureBuffer.h>

Inheritance diagram for PLRenderer::TextureBuffer:

List of all members.

Public Types
enum	EFlags { Mipmaps = 1<<0, Compression = 1<<1, RenderTarget = 1<<2 }
	Texture buffer flags. More...
enum	EPixelFormat {   L8 = 0, L16 = 1, A8 = 2, L4A4 = 3,   L8A8 = 4, D16 = 5, D24 = 6, D32 = 7,   R3G3B2 = 8, R5G6B5 = 9, R5G5B5A1 = 10, R4G4B4A4 = 11,   R8G8B8 = 12, R8G8B8A8 = 13, R10G10B10A2 = 14, R16G16B16A16 = 15,   DXT1 = 16, DXT3 = 17, DXT5 = 18, LATC1 = 19,   LATC2 = 20, L16F = 21, L32F = 22, R16G16B16A16F = 23,   R32G32B32A32F = 24, Unknown = 25 }
	Texture buffer pixel formats. More...
Public Member Functions
virtual PLRENDERER_API	~TextureBuffer ()
	Destructor.
PLCore::uint32	GetFlags () const
	Returns the texture buffer flags.
EPixelFormat	GetFormat () const
	Returns the texture buffer pixel format.
bool	IsCompressedFormat () const
	Returns whether or not the used texture buffer format is compressed.
bool	IsDepthFormat () const
	Returns whether or not the used texture buffer format is a depth buffer format.
EPixelFormat	GetUncompressedFormat () const
	If the used texture buffer format is compressed, a proper uncompressed texture buffer format will be returned.
bool	IsFloatingPointFormat () const
	Returns whether or not the used texture buffer format is a floating point format.
PLCore::uint32	GetComponentsPerPixel () const
	Returns the number of components per pixel.
PLCore::uint32	GetBytesPerPixelComponent () const
	Returns the number of bytes per pixel component.
PLCore::uint32	GetBytesPerPixel () const
	Returns the number of bytes per pixel.
PLCore::uint32	GetNumOfMipmaps () const
	Returns the number of mipmap levels.
PLCore::uint8	GetNumOfFaces () const
	Returns the number of faces.
PLRENDERER_API PLCore::uint32	GetTotalNumOfPixels () const
	Returns the total number of pixels including all mipmaps.
PLCore::uint32	GetTotalNumOfBytes () const
	Returns the total number of bytes required for the texture buffer data including all mipmaps.
PLRENDERER_API bool	GetFormatForImage (PLGraphics::EDataFormat &nDataFormat, PLGraphics::EColorFormat &nColorFormat, PLGraphics::ECompression &nCompression, EPixelFormat &nTextureBufferFomat) const
	Returns the image (PLGraphics::Image) settings required to be able to store the texture buffer data within an image.
PLRENDERER_API bool	DownloadAsImage (PLGraphics::Image &cImage) const
	Returns the texture buffer data as image.
PLRENDERER_API PLCore::uint32	GetNumOfNANValues (PLCore::uint32 nMipmap=0, PLCore::uint8 nFace=0) const
	Downloads the texture buffer content and returns the number of NAN values in it.
PLRENDERER_API PLCore::uint32	FixNANValues (const PLGraphics::Color4 &cColor, PLCore::uint32 nMipmap=0, PLCore::uint8 nFace=0)
	Downloads the texture buffer content, replaces pixels containing a NAN value by a given color, and uploads the fixed texture buffer.
virtual bool	IsPowerOfTwo () const =0
	Returns whether or not the texture has a power of two dimension (POT)
virtual PLCore::uint32	GetNumOfPixels (PLCore::uint32 nMipmap=0) const =0
	Returns the number of pixels of a certain mipmap level.
virtual PLCore::uint32	GetNumOfBytes (PLCore::uint32 nMipmap=0, EPixelFormat nFormat=Unknown) const =0
	Returns the number of bytes required to hold certain mipmap level texture buffer data.
virtual bool	Upload (PLCore::uint32 nMipmap, EPixelFormat nFormat, const void *pData, PLCore::uint8 nFace=0)=0
	Uploads data to the GPU.
virtual bool	Download (PLCore::uint32 nMipmap, EPixelFormat nFormat, void *pData, PLCore::uint8 nFace=0) const =0
	Downloads data from the GPU.
Static Public Member Functions
static PLRENDERER_API EPixelFormat	GetFormatFromImage (const PLGraphics::Image &cImage, bool bNoCompression=false)
	Returns the texture buffer pixel format of a given image (PLGraphics::Image)
static PLRENDERER_API bool	IsCompressedFormat (EPixelFormat nFormat)
	Returns whether or not the given texture buffer format is compressed.
static PLRENDERER_API bool	IsDepthFormat (EPixelFormat nFormat)
	Returns whether or not the given texture buffer format is a depth buffer format.
static PLRENDERER_API EPixelFormat	GetUncompressedFormat (EPixelFormat nFormat)
	If the given texture buffer format is compressed, a proper uncompressed texture buffer format will be returned.
static PLRENDERER_API bool	IsFloatingPointFormat (EPixelFormat nFormat)
	Returns whether or not the given texture buffer format is a floating point format.
static PLRENDERER_API PLCore::uint32	GetComponentsPerPixel (EPixelFormat nFormat)
	Returns the number of components per pixel.
static PLRENDERER_API PLCore::uint32	GetBytesPerPixelComponent (EPixelFormat nFormat)
	Returns the number of bytes per pixel component.
static PLRENDERER_API PLCore::uint32	GetBytesPerPixel (EPixelFormat nFormat)
	Returns the number of bytes per pixel.
Static Public Attributes
static const PLCore::uint32	NumOfPixelFormats = 25
Protected Member Functions
PLRENDERER_API	TextureBuffer (Renderer &cRenderer, EType nType, PLCore::uint32 nFlags)
	Constructor.
virtual bool	MakeCurrent (PLCore::uint32 nStage)=0
	Makes this texture buffer to the renderers current texture buffer.
Protected Attributes
PLCore::uint32	m_nFlags
EPixelFormat	m_nFormat
PLCore::uint32	m_nNumOfElements
PLCore::uint32	m_nNumOfMipmaps
PLCore::uint32	m_nTotalNumOfBytes

---

Detailed Description

Abstract renderer texture buffer resource base class.

Remarks:

In the literature, for a volume an element is called voxel, and a texture element is called texel. To stay name compatible with PLGraphics::ImageBuffer, we will just use the term pixel.

---

Member Enumeration Documentation

enum PLRenderer::TextureBuffer::EFlags

Texture buffer flags.

Enumerator:

Mipmaps	Use mipmaps (see GetNumOfMipmaps() for more information)
Compression	Use texture buffer compression if possible (is ignored if a certain internal format is forced)
RenderTarget	This texture buffer can be used as render target

enum PLRenderer::TextureBuffer::EPixelFormat

Texture buffer pixel formats.

Enumerator:

L8	8-bit pixel format, all bits luminance
L16	16-bit pixel format, all bits luminance
A8	8-bit pixel format, all bits alpha
L4A4	8-bit pixel format, 4 bits for luminance and alpha
L8A8	16-bit pixel format, 8 bits for luminance and alpha
D16	16-bit z-buffer bit depth
D24	32-bit z-buffer bit depth using 24 bits for the depth channel
D32	32-bit z-buffer bit depth
R3G3B2	8-bit pixel format, 3 bits red, 3 bits green and 2 bits blue
R5G6B5	16-bit pixel format, 5 bits red, 6 bits green and 5 bits blue
R5G5B5A1	16-bit pixel format, 5 bits red, 5 bits green, 5 bits blue and 1 bits alpha
R4G4B4A4	16-bit pixel format, 4 bits for red, green, blue and alpha
R8G8B8	24-bit (or 32-bit if 24-bits are not supported by the hardware) pixel format, 8 bits for red, green and blue
R8G8B8A8	32-bit pixel format, 8 bits for red, green, blue and alpha
R10G10B10A2	32-bit pixel format, 10 bits for red, green, blue and 2 bits for alpha
R16G16B16A16	64-bit pixel format, 16 bits for red, green, blue and alpha
DXT1	DXT1 compression (known as BC1 in DirectX 10, RGB compression: 8:1, 8 bytes per block)
DXT3	DXT3 compression (known as BC2 in DirectX 10, RGBA compression: 4:1, 16 bytes per block)
DXT5	DXT5 compression (known as BC3 in DirectX 10, RGBA compression: 4:1, 16 bytes per block)
LATC1	1 component texture compression (also known as 3DC+/ATI1N, known as BC4 in DirectX 10, 8 bytes per block)
LATC2	2 component texture compression (luminance & alpha compression 4:1 -> normal map compression, also known as 3DC/ATI2N, known as BC5 in DirectX 10, 16 bytes per block)
L16F	16-bit float format using 16 bits for luminance
L32F	32-bit float format using 32 bits for luminance
R16G16B16A16F	64-bit float format using 16 bits for the each channel (red, green, blue, alpha)
R32G32B32A32F	128-bit float format using 32 bits for the each channel (red, green, blue, alpha)
Unknown	Unknown texture buffer pixel format

---

Constructor & Destructor Documentation

virtual PLRENDERER_API PLRenderer::TextureBuffer::~TextureBuffer

(

)

[virtual]

Destructor.

PLRENDERER_API PLRenderer::TextureBuffer::TextureBuffer	(	Renderer &	cRenderer,
		EType	nType,
		PLCore::uint32	nFlags
	)		[protected]

Constructor.

Parameters:

[in]	cRenderer	Owner renderer
[in]	nType	Resource type
[in]	nFlags	Texture buffer flags (see EFlags)

---

Member Function Documentation

static PLRENDERER_API EPixelFormat PLRenderer::TextureBuffer::GetFormatFromImage	(	const PLGraphics::Image &	cImage,
		bool	bNoCompression = false
	)		[static]

Returns the texture buffer pixel format of a given image (PLGraphics::Image)

Parameters:

[in]	cImage	Image to get the texture buffer pixel format from
[in]	bNoCompression	Do NOT use texture buffer compression?

Returns:

The texture buffer pixel format of the given image

static PLRENDERER_API bool PLRenderer::TextureBuffer::IsCompressedFormat

(

EPixelFormat

nFormat

)

[static]

Returns whether or not the given texture buffer format is compressed.

Parameters:

[in]

nFormat

Texture buffer pixel format

Returns:

'true' if the texture buffer format is compressed, else 'false'

static PLRENDERER_API bool PLRenderer::TextureBuffer::IsDepthFormat

(

EPixelFormat

nFormat

)

[static]

Returns whether or not the given texture buffer format is a depth buffer format.

Parameters:

[in]

nFormat

Texture buffer pixel format

Returns:

'true' if the texture buffer format is a depth buffer format, else 'false'

static PLRENDERER_API EPixelFormat PLRenderer::TextureBuffer::GetUncompressedFormat

(

EPixelFormat

nFormat

)

[static]

If the given texture buffer format is compressed, a proper uncompressed texture buffer format will be returned.

Parameters:

[in]

nFormat

Texture buffer pixel format

Returns:

Uncompressed texture buffer format, if the given format was not compressed, the given format will be returned

static PLRENDERER_API bool PLRenderer::TextureBuffer::IsFloatingPointFormat

(

EPixelFormat

nFormat

)

[static]

Returns whether or not the given texture buffer format is a floating point format.

Parameters:

[in]

nFormat

Texture buffer pixel format

Returns:

'true' if the texture buffer format is a floating point format, else 'false'

static PLRENDERER_API PLCore::uint32 PLRenderer::TextureBuffer::GetComponentsPerPixel

(

EPixelFormat

nFormat

)

[static]

Returns the number of components per pixel.

Parameters:

[in]

nFormat

Texture buffer pixel format

Returns:

The number of components per pixel, 0 if unknown format

static PLRENDERER_API PLCore::uint32 PLRenderer::TextureBuffer::GetBytesPerPixelComponent

(

EPixelFormat

nFormat

)

[static]

Returns the number of bytes per pixel component.

Parameters:

[in]

nFormat

Texture buffer pixel format

Returns:

The number of bytes per pixel component, 0 if unknown format or no full byte per component

static PLRENDERER_API PLCore::uint32 PLRenderer::TextureBuffer::GetBytesPerPixel

(

EPixelFormat

nFormat

)

[static]

Returns the number of bytes per pixel.

Parameters:

[in]

nFormat

Texture buffer pixel format

Returns:

The number of bytes per pixel, 0 if unknown format or no full byte per pixel (compressed format)

PLCore::uint32 PLRenderer::TextureBuffer::GetFlags

(

)

const [inline]

Returns the texture buffer flags.

Returns:

The texture buffer flags (see EFlags)

TextureBuffer::EPixelFormat PLRenderer::TextureBuffer::GetFormat

(

)

const [inline]

Returns the texture buffer pixel format.

Returns:

The texture buffer pixel format

bool PLRenderer::TextureBuffer::IsCompressedFormat

(

)

const [inline]

Returns whether or not the used texture buffer format is compressed.

Returns:

'true' if the used texture buffer format is compressed, else 'false'

bool PLRenderer::TextureBuffer::IsDepthFormat

(

)

const [inline]

Returns whether or not the used texture buffer format is a depth buffer format.

Returns:

'true' if the used texture buffer format is a depth buffer format, else 'false'

TextureBuffer::EPixelFormat PLRenderer::TextureBuffer::GetUncompressedFormat

(

)

const [inline]

If the used texture buffer format is compressed, a proper uncompressed texture buffer format will be returned.

Returns:

Uncompressed texture buffer format, if the used format was not compressed, the used format will be returned

bool PLRenderer::TextureBuffer::IsFloatingPointFormat

(

)

const [inline]

Returns whether or not the used texture buffer format is a floating point format.

Returns:

'true' if the texture buffer format is a floating point format, else 'false'

PLCore::uint32 PLRenderer::TextureBuffer::GetComponentsPerPixel

(

)

const [inline]

Returns the number of components per pixel.

Returns:

The number of components per pixel, 0 if unknown format

PLCore::uint32 PLRenderer::TextureBuffer::GetBytesPerPixelComponent

(

)

const [inline]

Returns the number of bytes per pixel component.

Returns:

The number of bytes per pixel component, 0 if unknown format or no full byte per component

PLCore::uint32 PLRenderer::TextureBuffer::GetBytesPerPixel

(

)

const [inline]

Returns the number of bytes per pixel.

Returns:

The number of bytes per pixel, 0 if unknown format or no full byte per pixel (compressed format)

PLCore::uint32 PLRenderer::TextureBuffer::GetNumOfMipmaps

(

)

const [inline]

Returns the number of mipmap levels.

Returns:

The number of mipmap levels, 0 if there are no mipmaps (maybe not supported or not desired for this texture buffer)

Remarks:

Level 0 is the 'original' base image and GetNumOfMipmaps() is the version with the lowest resolution which is normally 1x1. For a 2D texture buffer, the number of mipmaps down to 1x1 is calculated by log2(max(width, height)). For a 32x16 texture buffer, this will result in the following additional mipmaps: 16x8, 8x4, 4x2, 2x1, 1x1

Note that mipmaps are only created/used from a given image if the flag 'Mipmaps' is set.

PLCore::uint8 PLRenderer::TextureBuffer::GetNumOfFaces

(

)

const [inline]

Returns the number of faces.

Returns:

The number of faces, always >0!

PLRENDERER_API PLCore::uint32 PLRenderer::TextureBuffer::GetTotalNumOfPixels

(

)

const

Returns the total number of pixels including all mipmaps.

Returns:

The total number of pixels including all mipmaps

PLCore::uint32 PLRenderer::TextureBuffer::GetTotalNumOfBytes

(

)

const [inline]

Returns the total number of bytes required for the texture buffer data including all mipmaps.

Returns:

The number of bytes required for the texture buffer data including all mipmaps

Note:

• If the texture buffer is using a compressed format, compression is also taken into account

PLRENDERER_API bool PLRenderer::TextureBuffer::GetFormatForImage	(	PLGraphics::EDataFormat &	nDataFormat,
		PLGraphics::EColorFormat &	nColorFormat,
		PLGraphics::ECompression &	nCompression,
		EPixelFormat &	nTextureBufferFomat
	)		const

Returns the image (PLGraphics::Image) settings required to be able to store the texture buffer data within an image.

Parameters:

[out]	nDataFormat	Receives the required image data format
[out]	nColorFormat	Receives the required image color format
[out]	nCompression	Receives the required image compression
[out]	nTextureBufferFomat	Receives the required texture buffer format to use within "TextureBuffer::Download()" in order to ask the GPU for the texture buffer data

Returns:

'true' if all went fine, else 'false'

Remarks:

This method maps the internal texture buffer format as close as possible to image data format and image color format. -> We may also need to choose another texture buffer format for the GPU texture buffer data request -> We can't e.g. just change PLGraphics in order to use the same pixel format scheme as the texture buffer because PLGraphics has to be generic, while texture buffer has to support special GPU formats usually not used in generic image processing

PLRENDERER_API bool PLRenderer::TextureBuffer::DownloadAsImage

(

PLGraphics::Image &

cImage

)

const

Returns the texture buffer data as image.

Parameters:

[out]

cImage

Receives the texture buffer data (no need to allocated the image, this is done automatically, just pass in any image instance)

Returns:

'true' if all went fine, else 'false'

PLRENDERER_API PLCore::uint32 PLRenderer::TextureBuffer::GetNumOfNANValues	(	PLCore::uint32	nMipmap = 0,
		PLCore::uint8	nFace = 0
	)		const

Downloads the texture buffer content and returns the number of NAN values in it.

Parameters:

[in]	nMipmap	Mipmap level (0 - GetNumOfMipmaps())
[in]	nFace	ID of the texture buffer face which should be downloaded if this is a cube texture buffer

Returns:

Number of NAN values (pixel components are counted individually)

Remarks:

If there are NAN values inside a texture buffer used for rendering, nasty "black boxes" (NVIDIA) or "white boxes" (ATI) may appear. This function may help you to pinpoint the place were the NANs are produces.

Note:

• This function can only be used if the texture buffer format is a floating point one
• This function should only be used for debugging

PLRENDERER_API PLCore::uint32 PLRenderer::TextureBuffer::FixNANValues	(	const PLGraphics::Color4 &	cColor,
		PLCore::uint32	nMipmap = 0,
		PLCore::uint8	nFace = 0
	)

Downloads the texture buffer content, replaces pixels containing a NAN value by a given color, and uploads the fixed texture buffer.

Parameters:

[in]	cColor	Color for pixels containing a NAN value
[in]	nMipmap	Mipmap level (0 - GetNumOfMipmaps())
[in]	nFace	ID of the texture buffer face which should be fixed if this is a cube texture buffer

Returns:

Number of fixed NAN pixels

See also:

• GetNumOfNANValues()

virtual bool PLRenderer::TextureBuffer::IsPowerOfTwo

(

)

const [pure virtual]

Returns whether or not the texture has a power of two dimension (POT)

Returns:

'true' if the texture has a power of two dimension, else 'false'

Remarks:

Although modern graphics APIs and graphics hardware is often capable to deal with non power of two dimension, there might be certain restrictions up to unexpected driver crashes within certain situations. This methods exists to make it easier to check for this sort of texture dimension. A texture is only power of two when it's power of two along each axis - except array textures which are considered to be a stack of 2D textures.

Implemented in PLRenderer::TextureBufferCube, PLRenderer::TextureBufferRectangle, PLRenderer::TextureBuffer2D, PLRenderer::TextureBuffer2DArray, PLRenderer::TextureBuffer3D, and PLRenderer::TextureBuffer1D.

virtual PLCore::uint32 PLRenderer::TextureBuffer::GetNumOfPixels

(

PLCore::uint32

nMipmap = 0

)

const [pure virtual]

Returns the number of pixels of a certain mipmap level.

Parameters:

[in]

nMipmap

Mipmap level (0 - GetNumOfMipmaps())

Returns:

The number of pixels of a certain mipmap level

Note:

• If this is a cube texture, the number of pixels of all faces together will be returned

Implemented in PLRenderer::TextureBufferCube, PLRenderer::TextureBufferRectangle, PLRenderer::TextureBuffer2D, PLRenderer::TextureBuffer2DArray, PLRenderer::TextureBuffer3D, and PLRenderer::TextureBuffer1D.

virtual PLCore::uint32 PLRenderer::TextureBuffer::GetNumOfBytes	(	PLCore::uint32	nMipmap = 0,
		EPixelFormat	nFormat = Unknown
	)		const [pure virtual]

Returns the number of bytes required to hold certain mipmap level texture buffer data.

Parameters:

[in]	nMipmap	Mipmap level (0 - GetNumOfMipmaps())
[in]	nFormat	Target texture buffer pixel format, if Unknown, the format of THIS texture buffer is chosen automatically

Returns:

The number of bytes required to hold certain mipmap level texture buffer data

Note:

• If 'nFormat' is a compressed format, compression is also taken into account
• If this is a cube texture, the number of bytes of all faces together will be returned

Implemented in PLRenderer::TextureBufferCube, PLRenderer::TextureBufferRectangle, PLRenderer::TextureBuffer2D, PLRenderer::TextureBuffer2DArray, PLRenderer::TextureBuffer3D, and PLRenderer::TextureBuffer1D.

virtual bool PLRenderer::TextureBuffer::Upload	(	PLCore::uint32	nMipmap,
		EPixelFormat	nFormat,
		const void *	pData,
		PLCore::uint8	nFace = 0
	)		[pure virtual]

Uploads data to the GPU.

Parameters:

[in]	nMipmap	Mipmap level (0 - GetNumOfMipmaps())
[in]	nFormat	Texture buffer pixel format of 'pData', can not be 'Unknown'. If this is a compressed format, it MUST be the same format this texture buffer has.
[in]	pData	Pointer to the data to upload, MUST have at least GetNumOfBytes(nMipmap, nFormat) bytes!
[in]	nFace	ID of the texture buffer face which should be uploaded if this is a cube texture buffer

Returns:

'true' if all went fine, else 'false' (invalid mipmap level? invalid data?)

virtual bool PLRenderer::TextureBuffer::Download	(	PLCore::uint32	nMipmap,
		EPixelFormat	nFormat,
		void *	pData,
		PLCore::uint8	nFace = 0
	)		const [pure virtual]

Downloads data from the GPU.

Parameters:

[in]	nMipmap	Mipmap level (0 - GetNumOfMipmaps())
[in]	nFormat	Texture buffer pixel format of 'pData', can not be 'Unknown'. If this is a compressed format, it MUST be the same format this texture buffer has.
[out]	pData	Will receive the downloaded data, MUST have at least GetNumOfBytes(nMipmap, nFormat) bytes!
[in]	nFace	ID of the texture buffer face which should be downloaded if this is a cube texture buffer

Returns:

'true' if all went fine, else 'false' (invalid mipmap level? invalid data?)

virtual bool PLRenderer::TextureBuffer::MakeCurrent

(

PLCore::uint32

nStage

)

[protected, pure virtual]

Makes this texture buffer to the renderers current texture buffer.

Parameters:

[in]

nStage

Texture stage

Returns:

'true' if all went fine, else 'false'

---

Member Data Documentation

const PLCore::uint32 PLRenderer::TextureBuffer::NumOfPixelFormats = 25 [static]

Number of pixel formats

PLCore::uint32 PLRenderer::TextureBuffer::m_nFlags [protected]

Texture buffer flags (see EFlags)

EPixelFormat PLRenderer::TextureBuffer::m_nFormat [protected]

Texture buffer pixel format

PLCore::uint32 PLRenderer::TextureBuffer::m_nNumOfElements [protected]

The number of elements

PLCore::uint32 PLRenderer::TextureBuffer::m_nNumOfMipmaps [protected]

Number of mipmap levels (the base level is 0)

PLCore::uint32 PLRenderer::TextureBuffer::m_nTotalNumOfBytes [protected]

Total number of bytes required to the texture buffer data including all mipmaps

---

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

• TextureBuffer.h
• TextureBuffer.inl