Texture2D Class Reference

#include <texture.h>

Public Member Functions
	Texture2D (Core &core)
virtual	~Texture2D () override
bool	init (const SurfaceDescriptor &descriptor, bool generateMipMaps, const glm::vec4 &clearColor, VkImageUsageFlags requiredFlags, utility::ErrorState &errorState)
bool	init (const SurfaceDescriptor &descriptor, bool generateMipMaps, VkImageUsageFlags requiredFlags, utility::ErrorState &errorState)
bool	init (const SurfaceDescriptor &descriptor, bool generateMipMaps, void *initialData, VkImageUsageFlags requiredFlags, utility::ErrorState &errorState)
const glm::vec2	getSize () const
int	getWidth () const
int	getHeight () const
void	update (const void *data, int width, int height, int pitch, ESurfaceChannels channels)
void	update (const void *data, const SurfaceDescriptor &surfaceDescriptor)
virtual uint	getLayerCount () const override
virtual uint	getMipLevels () const override
virtual const ImageData &	getHandle () const override
void	asyncGetData (Bitmap &bitmap)
void	asyncGetData (std::function< void(const void *, size_t)> copyFunction)
Public Member Functions inherited from Texture
	Texture (Core &core)
virtual	~Texture ()
virtual VkImageLayout	getTargetLayout () const
VkFormat	getFormat () const
const SurfaceDescriptor &	getDescriptor () const
RenderService &	getRenderService ()
const RenderService &	getRenderService () const
virtual void	onDestroy () override
Public Member Functions inherited from Resource
	Resource ()
Public Member Functions inherited from Object
	Object ()
virtual	~Object ()
virtual bool	init (utility::ErrorState &errorState)
	Object (Object &)=delete
Object &	operator= (const Object &)=delete
	Object (Object &&)=delete
Object &	operator= (Object &&)=delete

Public Attributes
EUsage	mUsage = EUsage::Static
	Property: 'Usage' If this texture is updated frequently or considered static. More...
Public Attributes inherited from Texture
nap::Signal	textureDestroyed
	Signal that is triggered before texture is destroyed. More...
Public Attributes inherited from Object
std::string	mID
	Property: 'mID' unique name of the object. Used as an identifier by the system. More...

Protected Types
using	TextureReadCallback = std::function< void(void *data, size_t sizeInBytes)>

Protected Member Functions
virtual ImageData &	getHandle () override
bool	initInternal (const SurfaceDescriptor &descriptor, bool generateMipMaps, VkImageUsageFlags requiredFlags, utility::ErrorState &errorState)
void	upload (VkCommandBuffer commandBuffer)
void	download (VkCommandBuffer commandBuffer)
void	notifyDownloadReady (int frameIndex)
void	clearDownloads ()
Protected Member Functions inherited from Texture
virtual void	clear (VkCommandBuffer commandBuffer)
void	requestClear ()

Protected Attributes
ImageData	mImageData
	2D Texture vulkan image buffers More...
std::vector< BufferData >	mStagingBuffers
	All vulkan staging buffers, 1 when static or using dynamic read, no. of frames in flight when dynamic write. More...
int	mCurrentStagingBufferIndex = -1
	Currently used staging buffer. More...
size_t	mImageSizeInBytes = -1
	Size in bytes of texture. More...
std::vector< TextureReadCallback >	mReadCallbacks
	Number of callbacks based on number of frames in flight. More...
std::vector< int >	mDownloadStagingBufferIndices
	Staging buffer indices associated with a frameindex. More...
uint32	mMipLevels = 1
	Total number of generated mip-maps. More...
Protected Attributes inherited from Texture
RenderService &	mRenderService
	Reference to the render service. More...
SurfaceDescriptor	mDescriptor
	Texture description. More...
VkFormat	mFormat = VK_FORMAT_UNDEFINED
	Vulkan texture format. More...
VkClearColorValue	mClearColor = { 0.0f, 0.0f, 0.0f, 0.0f }
	Color used for clearing the texture. More...

Additional Inherited Members
Public Types inherited from Texture
enum	EUsage { Static, DynamicRead, DynamicWrite }
Static Public Member Functions inherited from Object
static bool	isIDProperty (rtti::Instance &object, const rtti::Property &property)

Description

GPU representation of a 2D image. This class does not own any CPU data. It offers the user an interface to upload & download texture data, from and to a bitmap. When usage is set to 'Static' (default) or 'DynamicRead' data can be uploaded only once. When usage is set to 'DynamicWrite' the texture be updated frequently from CPU to GPU.

Inheritance diagram for Texture2D:

Collaboration diagram for Texture2D:

Member Typedef Documentation

TextureReadCallback

using TextureReadCallback = std::function<void(void* data, size_t sizeInBytes)>

protected

Constructor & Destructor Documentation

Texture2D()

Texture2D

(

Core &

core

)

~Texture2D()

virtual ~Texture2D ( )

overridevirtual

Member Function Documentation

asyncGetData() [1/2]

void asyncGetData

(

Bitmap &

bitmap

)

Starts a transfer of texture data from GPU to CPU. This is a non blocking call. When the transfer completes, the bitmap will be filled with the texture data.

Parameters

bitmap

the bitmap to download texture data into.

asyncGetData() [2/2]

void asyncGetData

(

std::function< void(const void *, size_t)>

copyFunction

)

Starts a transfer of texture data from GPU to CPU. Use this overload to pass your own copy function. This is a non blocking call. When the transfer completes, the bitmap will be filled with the texture data.

Parameters

copyFunction

the copy function to call when the texture data is available for download.

clearDownloads()

void clearDownloads ( )

protected

Clears queued texture downloads

download()

void download ( VkCommandBuffer  commandBuffer )

protected

Downloads texture data

getHandle() [1/2]

virtual const ImageData& getHandle ( ) const

overridevirtual

Returns

Vulkan GPU data handle, including image and view.

Implements Texture.

Reimplemented in DepthRenderTexture2D, and RenderTexture2D.

getHandle() [2/2]

virtual ImageData& getHandle ( )

overrideprotectedvirtual

Returns

Vulkan GPU data handle, including image and view.

Implements Texture.

getHeight()

int getHeight

(

)

const

Returns

height of the texture in texels

getLayerCount()

virtual uint getLayerCount ( ) const

overridevirtual

Returns

the number of texture layers

Implements Texture.

getMipLevels()

virtual uint getMipLevels ( ) const

overridevirtual

Returns

the number of texture mip-map levels

Implements Texture.

getSize()

const glm::vec2 getSize

(

)

const

Returns

size of the texture in texels.

getWidth()

int getWidth

(

)

const

Returns

width of the texture in texels

init() [1/3]

bool init	(	const SurfaceDescriptor &	descriptor,
		bool	generateMipMaps,
		const glm::vec4 &	clearColor,
		VkImageUsageFlags	requiredFlags,
		utility::ErrorState &	errorState
	)

Creates the texture on the GPU using the provided settings. The texture is cleared to 'ClearColor'. The Vulkan image usage flags are derived from texture usage.

Parameters

descriptor	texture description.
generateMipMaps	if mip maps are generated when data is uploaded.
clearColor	the color to clear the texture with.
requiredFlags	image usage flags that are required, 0 = no additional usage flags.
errorState	contains the error if the texture can't be initialized.

Returns

if the texture initialized successfully.

init() [2/3]

bool init	(	const SurfaceDescriptor &	descriptor,
		bool	generateMipMaps,
		VkImageUsageFlags	requiredFlags,
		utility::ErrorState &	errorState
	)

Creates the texture on the GPU using the provided settings. The texture is cleared to 'ClearColor'. Otherwise the layout of the texture on the GPU will be undefined until upload. The Vulkan image usage flags are derived from texture usage.

Parameters

descriptor	texture description.
generateMipMaps	if mip maps are generated when data is uploaded.
requiredFlags	image usage flags that are required, 0 = no additional usage flags.
errorState	contains the error if the texture can't be initialized.

Returns

if the texture initialized successfully.

init() [3/3]

bool init	(	const SurfaceDescriptor &	descriptor,
		bool	generateMipMaps,
		void *	initialData,
		VkImageUsageFlags	requiredFlags,
		utility::ErrorState &	errorState
	)

Creates the texture on the GPU using the provided settings and immediately requests a content upload. The Vulkan image usage flags are derived from texture usage.

Parameters

descriptor	texture description.
generateMipMaps	if mip maps are generated when data is uploaded.
initialData	the data to upload, must be of size SurfaceDescriptor::getSizeInBytes().
requiredFlags	image usage flags that are required, 0 = no additional usage flags
errorState	contains the error if the texture can't be initialized.

Returns

if the texture initialized successfully.

initInternal()

bool initInternal ( const SurfaceDescriptor &  descriptor, bool  generateMipMaps, VkImageUsageFlags  requiredFlags, utility::ErrorState &  errorState  )

protected

Creates the texture on the GPU using the provided settings. The Vulkan image usage flags are derived from texture usage.

Parameters

descriptor	texture description.
generateMipMaps	if mip maps are generated when data is uploaded.
requiredFlags	image usage flags that are required, 0 = no additional usage flags
errorState	contains the error if the texture can't be initialized.

Returns

if the texture initialized successfully.

notifyDownloadReady()

void notifyDownloadReady ( int  frameIndex )

protected

Called by the render service when download is ready

update() [1/2]

void update	(	const void *	data,
		const SurfaceDescriptor &	surfaceDescriptor
	)

Uploads CPU data to the texture on the GPU. Note that you can only update the contents of a texture once if 'Usage' is 'DynamicRead' or 'Static'.

Parameters

data	pointer to the CPU data.
surfaceDescriptor	texture description.

update() [2/2]

void update	(	const void *	data,
		int	width,
		int	height,
		int	pitch,
		ESurfaceChannels	channels
	)

Uploads CPU data to the texture on the GPU. Note that you can only update the contents of a texture once if 'Usage' is 'DynamicRead' or 'Static'.

Parameters

data	pointer to the CPU data.
width	width of the image in pixels
height	height of the image in pixels
pitch	size in bytes of a single row of pixel data.
channels	total number of channels: 3 for RGB, 4 for RGBA etc.

upload()

void upload ( VkCommandBuffer  commandBuffer )

protected

Called by the render service when data can be uploaded

Member Data Documentation

mCurrentStagingBufferIndex

int mCurrentStagingBufferIndex = -1

protected

Currently used staging buffer.

mDownloadStagingBufferIndices

std::vector<int> mDownloadStagingBufferIndices

protected

Staging buffer indices associated with a frameindex.

mImageData

ImageData mImageData

protected

2D Texture vulkan image buffers

mImageSizeInBytes

size_t mImageSizeInBytes = -1

protected

Size in bytes of texture.

mMipLevels

uint32 mMipLevels = 1

protected

Total number of generated mip-maps.

mReadCallbacks

std::vector<TextureReadCallback> mReadCallbacks

protected

Number of callbacks based on number of frames in flight.

mStagingBuffers

std::vector<BufferData> mStagingBuffers

protected

All vulkan staging buffers, 1 when static or using dynamic read, no. of frames in flight when dynamic write.

mUsage

EUsage mUsage = EUsage::Static

Property: 'Usage' If this texture is updated frequently or considered static.