Texture2D Class Reference

#include <texture.h>

Public Types
enum	EUsage { Static = 0, DynamicRead = 1, DynamicWrite = 2, Internal = 3 }

Public Member Functions
	Texture2D (Core &core)
virtual	~Texture2D () override
bool	init (const SurfaceDescriptor &descriptor, EUsage usage, int mipCount, const glm::vec4 &clearColor, VkImageUsageFlags requiredFlags, utility::ErrorState &errorState)
bool	init (const SurfaceDescriptor &descriptor, EUsage usage, int mipCount, 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)
bool	init (const SurfaceDescriptor &descriptor, EUsage usage, bool mipCount, const glm::vec4 &clearColor, VkImageUsageFlags requiredFlags, utility::ErrorState &errorState)=delete
bool	init (const SurfaceDescriptor &descriptor, EUsage usage, bool mipCount, void *initialData, VkImageUsageFlags requiredFlags, utility::ErrorState &errorState)=delete
Public Member Functions inherited from Texture
	Texture (Core &core)
virtual	~Texture ()
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

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

Protected Member Functions
virtual ImageData &	getHandle () override
bool	initInternal (const SurfaceDescriptor &descriptor, EUsage usage, int mipCount, 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...
EUsage	mUsage
	Intented texture usage. 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
Static Public Member Functions inherited from Object
static bool	isIDProperty (rtti::Instance &object, const rtti::Property &property)
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...

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

Member Enumeration Documentation

EUsage

enum EUsage

strong

Flag that determines how the 2D texture is used at runtime.

Enumerator
Static	Texture is uploaded to once and does not change.
DynamicRead	Texture is frequently read from GPU to CPU.
DynamicWrite	Texture is frequently updated from CPU to GPU.
Internal	Texture is never uploaded to or downloaded from.

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.

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/4]

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

delete

init() [2/4]

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

delete

init() [3/4]

bool init	(	const SurfaceDescriptor &	descriptor,
		EUsage	usage,
		int	mipCount,
		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.
usage	how the texture is intended to be used (static, internal only etc..)
mipCount	total number of mip-maps to generate upon upload, a value of 1 disables mip-mapping
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() [4/4]

bool init	(	const SurfaceDescriptor &	descriptor,
		EUsage	usage,
		int	mipCount,
		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.
usage	how the texture is intended to be used (static, internal only etc..)
mipCount	total number of mip-maps to generate upon upload, a value of 1 disables mip-mapping
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, EUsage  usage, int  mipCount, 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.
mipCount	total number of mip-maps to generate upon upload
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

protected

Intented texture usage.