API Documentation
Public Member Functions | Static Public Member Functions | List of all members
nkGraphics::Texture Class Referenceabstract

A texture used for rendering, hosted on GPU. More...

Inheritance diagram for nkGraphics::Texture:
nkGraphics::ShaderResource nkExport::Exportable nkGraphics::Resource

Public Member Functions

virtual ~Texture ()
 
TextureCpuDataDescriptor * getCpuData () const
 
unsigned int getCpuSliceCount () const
 
bool isFromFile () const
 
bool isGammaCorrected () const
 
bool isBackBufferTex () const
 
TEX_TYPE getTexType () const
 
TEX_RENDER_FLAG getRenderFlag () const
 
unsigned int getNeededMipsForSize () const
 
virtual int getWidth () const =0
 
virtual int getHeight () const =0
 
virtual int getDepthOrArraySize () const =0
 
virtual unsigned int getMipLevels () const =0
 
virtual FORMAT getTextureFormat () const =0
 
virtual BUFFER_CPU_ACCESS_FLAG getCpuAccessRights () const =0
 
virtual BUFFER_USAGE getTextureUsage () const =0
 
virtual BUFFER_BIND_FLAG getTextureBinding () const =0
 
virtual RESOURCE_MISC_FLAG getMiscFlag () const =0
 
virtual unsigned int getSampleCount () const =0
 
virtual unsigned int getSampleQuality () const =0
 
virtual bool getAutoMipGeneration () const =0
 
void setCpuData (const ResourceCpuDataDescriptor &data)
 
void addCpuDataSlice (const nkMemory::BufferView<> &data, unsigned int byteOffset=0u, unsigned int rowByteSize=0u, unsigned int sliceByteSize=0u)
 
void addCpuDataSliceCopy (const nkMemory::BufferView<> &data, unsigned int byteOffset=0u, unsigned int rowByteSize=0u, unsigned int sliceByteSize=0u)
 
void addCpuDataSliceForward (nkMemory::Buffer &&data, unsigned int byteOffset=0u, unsigned int rowByteSize=0u, unsigned int sliceByteSize=0u)
 
void addCpuDataSliceRelativeToLast (unsigned int byteOffset=0u, unsigned int rowByteSize=0u, unsigned int sliceByteSize=0u)
 
void setBackBufferTex (bool value)
 
void setFromImage (const nkImages::ImageView &image)
 
void setFromImageCopy (const nkImages::ImageView &image)
 
void setFromImageForward (nkImages::Image &&image)
 
virtual void freeCpuData ()
 
virtual void setGammaCorrected (bool value)
 
virtual void setPath (nkMemory::StringView value) override
 
virtual void setWidth (unsigned int width)=0
 
virtual void setHeight (unsigned int height)=0
 
virtual void setDepthOrArraySize (unsigned int depth)=0
 
virtual void setMipLevels (unsigned int value)=0
 
virtual void setTextureFormat (FORMAT format)=0
 
virtual void setCpuAccessRights (BUFFER_CPU_ACCESS_FLAG rights)=0
 
virtual void setTextureUsage (BUFFER_USAGE usage)=0
 
virtual void setTextureBinding (BUFFER_BIND_FLAG binding)=0
 
virtual void setAutoMipGeneration (bool value)=0
 
virtual void copyParams (const Texture &other)=0
 
void setTextureFormatFromString (nkMemory::StringView str)
 
void setMightManuallyGenerateMip (bool value)
 
virtual void prepareAsTexture2d ()
 
virtual void prepareAsCubemap ()
 
virtual void prepareAsTexture3d ()
 
virtual void setRenderFlag (TEX_RENDER_FLAG value)
 
virtual void generateMipChain (unsigned int fromMip=0)=0
 
nkImages::Image convertToImage (int mip, int sliceOrArrayIndex)
 
virtual MapResult map (const MapRequestDescriptor &requestDesc)=0
 
virtual void unmap (const UnmapRequestDescriptor &requestDesc)=0
 
virtual void gpuCopyFrom (Texture &other, const ResourceGpuCopyDescriptor &descriptor)=0
 
virtual void exportClassToTree (nkExport::Node *rootNode) override
 
virtual void importClassFromTree (nkExport::Node *rootNode) override
 
- Public Member Functions inherited from nkGraphics::ShaderResource
virtual ~ShaderResource ()
 
- Public Member Functions inherited from nkGraphics::Resource
virtual ~Resource ()
 
bool isReadyForRendering () const
 
bool isUnloaded () const
 
RESOURCE_LOAD_STATE getLoadState () const
 
nkMemory::StringView getPath () const
 
RESOURCE_TYPE getTypeName () const
 
nkMemory::StringView getName () const
 
SystemgetSystem () const
 
bool getHidden () const
 
bool getGpuUploadCanBeDeferred () const
 
void setName (nkMemory::StringView value)
 
void setHidden (bool value)
 
void setGpuUploadCanBeDeferred (bool value)
 
virtual bool load ()=0
 
virtual void unload ()=0
 
- Public Member Functions inherited from nkExport::Exportable
 Exportable () noexcept
 
virtual ~Exportable ()
 

Static Public Member Functions

static nkMemory::UniquePtr< Texturecreate (System *system=nullptr)
 

Detailed Description

A texture used for rendering, hosted on GPU.

Constructor & Destructor Documentation

◆ ~Texture()

virtual nkGraphics::Texture::~Texture ( )
virtual

Destructor.

Member Function Documentation

◆ getCpuData()

TextureCpuDataDescriptor* nkGraphics::Texture::getCpuData ( ) const
Returns
Currently set cpu data.

◆ getCpuSliceCount()

unsigned int nkGraphics::Texture::getCpuSliceCount ( ) const
Returns
The number of slices set within the CPU data, as recorded by the texture.

◆ isFromFile()

bool nkGraphics::Texture::isFromFile ( ) const
Returns
If the texture comes from an external file (true) or not (false).

◆ isGammaCorrected()

bool nkGraphics::Texture::isGammaCorrected ( ) const
Returns
If the texture is gamma corrected (true) or not (false). True by default.

◆ isBackBufferTex()

bool nkGraphics::Texture::isBackBufferTex ( ) const
Returns
If the texture is in fact the back buffer, aka the context final target (true), or not (false).

◆ getTexType()

TEX_TYPE nkGraphics::Texture::getTexType ( ) const
Returns
The texture type.

◆ getRenderFlag()

TEX_RENDER_FLAG nkGraphics::Texture::getRenderFlag ( ) const
Returns
The texture attached render flag.

◆ getNeededMipsForSize()

unsigned int nkGraphics::Texture::getNeededMipsForSize ( ) const
Returns
The number of mips the texture would need to generate a full chain.

◆ getWidth()

virtual int nkGraphics::Texture::getWidth ( ) const
pure virtual
Returns
The width of the texture, in pixels.

◆ getHeight()

virtual int nkGraphics::Texture::getHeight ( ) const
pure virtual
Returns
The height of the texture, in pixels.

◆ getDepthOrArraySize()

virtual int nkGraphics::Texture::getDepthOrArraySize ( ) const
pure virtual
Returns
The depth, or array size of the texture, in number of slices.

◆ getMipLevels()

virtual unsigned int nkGraphics::Texture::getMipLevels ( ) const
pure virtual
Returns
The number of active mips currently set in the texture.

◆ getTextureFormat()

virtual FORMAT nkGraphics::Texture::getTextureFormat ( ) const
pure virtual
Returns
The format of the texture.

◆ getCpuAccessRights()

virtual BUFFER_CPU_ACCESS_FLAG nkGraphics::Texture::getCpuAccessRights ( ) const
pure virtual
Returns
The cpu access flag linked.

◆ getTextureUsage()

virtual BUFFER_USAGE nkGraphics::Texture::getTextureUsage ( ) const
pure virtual
Returns
The usage attached to the texture.

◆ getTextureBinding()

virtual BUFFER_BIND_FLAG nkGraphics::Texture::getTextureBinding ( ) const
pure virtual
Returns
The binding flag attached to the texture.

◆ getMiscFlag()

virtual RESOURCE_MISC_FLAG nkGraphics::Texture::getMiscFlag ( ) const
pure virtual
Returns
The misc flag attached to the texture.

◆ getSampleCount()

virtual unsigned int nkGraphics::Texture::getSampleCount ( ) const
pure virtual
Returns
The sample count of the texture.

◆ getSampleQuality()

virtual unsigned int nkGraphics::Texture::getSampleQuality ( ) const
pure virtual
Returns
The sample quality of the texture.

◆ getAutoMipGeneration()

virtual bool nkGraphics::Texture::getAutoMipGeneration ( ) const
pure virtual
Returns
If the texture should auto generate missing mips on load (true) or not (false).

◆ setCpuData()

void nkGraphics::Texture::setCpuData ( const ResourceCpuDataDescriptor &  data)

Sets the CPU data from which the texture should load when the load() method is called. Data needs to be formatted for the format specified for the texture.

If multiple sub-resources are needed but left unspecified (_subresources member left empty), their location and size will be automatically determined. In such case, it is expected that they fit the DirectX ordering :

  • Each 2D texture entry is directly followed by their respective mip chain
  • For an array of textures, each entry fits the first rule and follows the last one
  • No padding is applied, data is considered tightly fitting

To give an idea of what is expected, the data for a 2D 2x2x6 texture array would be in this order :

Tex0 Mip0, Tex0 Mip1, Tex1 Mip0, Tex1 Mip1...

In case the sub resources are specified within the provided descriptor, the data description is entirely left to the user. This means that if there are holes in the description, they won't be filled automatically.

Parameters
dataThe texture data to feed from the cpu to the texture.
Remarks
Data needs to remain available while the data loads. For cleaning the memory, see the freeCpuData() function that will ensure data is available as long as required.

◆ addCpuDataSlice()

void nkGraphics::Texture::addCpuDataSlice ( const nkMemory::BufferView<> &  data,
unsigned int  byteOffset = 0u,
unsigned int  rowByteSize = 0u,
unsigned int  sliceByteSize = 0u 
)

Adds a CPU data slice from which the texture should load when the load() method is called. This method will only create a view over provided data.

A slice can be a mip, a texture array entry, or a 3D texture slice. Pixel data needs to be formatted for the format specified for the texture, each channel at their given position. For instance, R8G8B8 would need a char buffer with bytes interpreted as RGBRGBRGB...

Multiple slices (mips, entries...) can be provided with consecutive calls to any variant of the function. They should be made in the right order for the texture to interpret data correctly. The expected input order depends on the texture nature, but should fit the DirectX ordering :

  • Each 2D texture entry is directly followed by their respective mip chain
  • For an array of textures, each texture entry fits the first rule and follows the last given slice given

To give an idea of what is expected, data for a 2x2 texture would be in this order :

Mip0, Mip1

Data for a 2D 2x2x3 texture array would be in this order :

Tex0 Mip0, Tex0 Mip1, Tex1 Mip0, Tex1 Mip1, Tex2 Mip0, Tex2 Mip1

In the case a texture expects multiple slices, but only one is given through these functions, missing slices will be reconstructed within given buffer if its size allows it. Else, they will be set to black.
However, this behaviour is only true for 2D textures. Currently, texture arrays and 3D texture need to have all their slices declared upfront if data is provided.

Parameters
dataThe texture data to feed from the cpu to the texture.
byteOffsetThe offset, in bytes, at which slice data starts in buffer.
rowByteSizeThe size of a row, in bytes. Leave it to 0 to have it derived from the texture's width and its pixel format byte size.
sliceByteSizeThe size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height.
Remarks
Source data needs to remain available until the texture is fully loaded (getLoadState() returning RESOURCE_LOAD_STATE::LOADED).

◆ addCpuDataSliceCopy()

void nkGraphics::Texture::addCpuDataSliceCopy ( const nkMemory::BufferView<> &  data,
unsigned int  byteOffset = 0u,
unsigned int  rowByteSize = 0u,
unsigned int  sliceByteSize = 0u 
)

Adds a slice declaration, with data that will be copied to an internally managed buffer. See addCpuDataSlice() for more details.

Parameters
dataData to provide to populate the slice.
byteOffsetThe offset, in bytes, at which slice data starts in buffer.
rowByteSizeThe size of a row, in bytes. Leave it to 0 to have it derived from the texture's width and its pixel format byte size.
sliceByteSizeThe size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height.
Remarks
This variant will copy data into an internally managed buffer, making the memory footprint higher. As such, source data can be erased right after. Once unnecessary, it will be required to call freeCpuData() to free newly created internal data.

◆ addCpuDataSliceForward()

void nkGraphics::Texture::addCpuDataSliceForward ( nkMemory::Buffer &&  data,
unsigned int  byteOffset = 0u,
unsigned int  rowByteSize = 0u,
unsigned int  sliceByteSize = 0u 
)

Adds a slice declaration, with data that will be forwarded to an internally managed buffer. See addCpuDataSlice() for more details.

Parameters
dataData to provide to populate the slice.
byteOffsetThe offset, in bytes, at which slice data starts in buffer.
rowByteSizeThe size of a row, in bytes. Leave it to 0 to have it derived from the texture's width and its pixel format byte size.
sliceByteSizeThe size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height.
Remarks
This variant will invalidate input data as it is moved around into the internally managed buffer. Once unnecessary, it will be required to call freeCpuData() to free it.

◆ addCpuDataSliceRelativeToLast()

void nkGraphics::Texture::addCpuDataSliceRelativeToLast ( unsigned int  byteOffset = 0u,
unsigned int  rowByteSize = 0u,
unsigned int  sliceByteSize = 0u 
)

Adds a slice declaration, relative to last slice provided. This variant will reuse the last valid memory buffer provided and finds its spot inside depending on given parameters.

Parameters
byteOffsetThe offset, in bytes, at which slice data starts in buffer. Leave it to 0 to have it directly starting after last slice's byte size.
rowByteSizeThe size of a row, in bytes. Leave it to 0 to have it derived from the texture's width and its pixel format byte size.
sliceByteSizeThe size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height.
Remarks
This function requires another slice to have been set before, with a valid buffer, so that it can be expressed relatively to it. It is perfectly valid to define many slices in a row using it, as all parameters will be derived, if required, relative to the last.

◆ setBackBufferTex()

void nkGraphics::Texture::setBackBufferTex ( bool  value)
Parameters
valueIf the texture is the back buffer, aka the final texture, of a RenderContext.
Remarks
In theory, should not be called by external code. Used by the parent RenderContext.

◆ setFromImage()

void nkGraphics::Texture::setFromImage ( const nkImages::ImageView image)

Sets the texture to load from a given pre-decoded image. This will translate all required metadata and data to be interpreted by the texture during loading. For best performances, it is advised to provide images fulfilling these conditions :

  • RGB format that can be interpreted directly : R8G8B8A8, B8G8R8A8, R16G16B16A16, R32G32B32, R32G32B32A32
  • Or compressed format that can be interpreted directly : BC1, BC2, BC3, BC4, BC5
  • If image has a 1 byte per channel format (R8G8B8, B8G8R8, Y8U8V8_444) then one pixel needs to have a size of 4 bytes. This can be achieved at parsing time by either asking a pixel alignment of 4, or adding an alpha channel.

Failure in doing so will trigger an internal conversion, resulting in a copy and more processing, to make the image compatible.
Note that YUV formats will be re-interpreted as RGB formats, directly using the Y as R, the U as G, and the V as B. If you need it properly converted, it needs to be done upfront.

Parameters
imageThe image to use as input.
Remarks
The image data is not copied for the texture to use it, unless internal conversions or realignments have to happen. For safety, cpu data created internally will be pointing to the memory from the image view provided. Be sure to keep this data available until the texture is fully loaded (getLoadState() returning RESOURCE_LOAD_STATE::LOADED).

◆ setFromImageCopy()

void nkGraphics::Texture::setFromImageCopy ( const nkImages::ImageView image)

Sets the texture to load from a given pre-decoded image, by copying provided data. For more details, please refer to setFromImage().

Parameters
imageThe image to use as input.
Remarks
This variant copies the image provided into an internally managed image. As such, it is not necessary to keep source image around during texture loading. However, the memory footprint is higher. It might be beneficial to call freeCpuData() as soon as possible after the call to load(), if data won't be needed anymore.

◆ setFromImageForward()

void nkGraphics::Texture::setFromImageForward ( nkImages::Image &&  image)

Sets the texture to load from a given pre-decoded image, by forwarding provided data. For more details, please refer to setFromImage().

Parameters
imageThe image to use as input.
Remarks
This variant forwards provided image to an internally managed image. As such, input data will be emptied as memory is moved around. If necessary, to free internal data, a call to freeCpuData() will be needed after the call to load().

◆ freeCpuData()

virtual void nkGraphics::Texture::freeCpuData ( )
virtual

Frees the cpu data attached to the texture, possibly with the internal buffers if the texture owns them. This function has to be called after the load method has been called, for the process to know when the data can be fred.

◆ setGammaCorrected()

virtual void nkGraphics::Texture::setGammaCorrected ( bool  value)
virtual
Parameters
valueIf the texture should be gamma corrected (true) or not (false).
Remarks
Gamma correction acts on the format of the texture to leverage the GPU's automatic correction when available. To be sure this functionality will work when enabling the flag, a compatible format should be used. Compatible formats can be found within the nkGraphics::FORMAT enumeration, as compatible formats have an SRGB alternative. Other formats won't be able to be gamma corrected and will trigger a warning if it is requested or left to the default true value. In such case, you can turn off the flag to avoid the warning, and manually correct the colour within the nkGraphics::Program code. Another alternative would be to convert the texture to a supported format.

◆ setPath()

virtual void nkGraphics::Texture::setPath ( nkMemory::StringView  value)
overridevirtual

Sets the resource's path, relative to the working directory. See nkResources::ResourceManager for path naming conventions.

Parameters
valueThe path to use.

Reimplemented from nkGraphics::Resource.

◆ setWidth()

virtual void nkGraphics::Texture::setWidth ( unsigned int  width)
pure virtual
Parameters
widthThe width of the texture, in pixels.

◆ setHeight()

virtual void nkGraphics::Texture::setHeight ( unsigned int  height)
pure virtual
Parameters
heightThe height of the texture, in pixels.

◆ setDepthOrArraySize()

virtual void nkGraphics::Texture::setDepthOrArraySize ( unsigned int  depth)
pure virtual
Parameters
depthThe depth or array size of the texture, in pixels / slices.

◆ setMipLevels()

virtual void nkGraphics::Texture::setMipLevels ( unsigned int  value)
pure virtual
Parameters
valueThe number of mips wanted for the texture. Can be 0 to mean that all mips should be used.
Remarks
It is possible to specify a partial mip chain for a texture.

◆ setTextureFormat()

virtual void nkGraphics::Texture::setTextureFormat ( FORMAT  format)
pure virtual
Parameters
formatThe format to assign to the texture.

◆ setCpuAccessRights()

virtual void nkGraphics::Texture::setCpuAccessRights ( BUFFER_CPU_ACCESS_FLAG  rights)
pure virtual
Parameters
rightsThe cpu access flag wanted.
Remarks
Try to keep those rights at a minimum, as this will impact the memory used for allocating the texture, and this, the perfomances when rendering.

◆ setTextureUsage()

virtual void nkGraphics::Texture::setTextureUsage ( BUFFER_USAGE  usage)
pure virtual
Parameters
usageThe texture usage.

◆ setTextureBinding()

virtual void nkGraphics::Texture::setTextureBinding ( BUFFER_BIND_FLAG  binding)
pure virtual
Parameters
bindingThe binding flag to use. Can be or'ed.

◆ setAutoMipGeneration()

virtual void nkGraphics::Texture::setAutoMipGeneration ( bool  value)
pure virtual
Parameters
valueIf the missing mips should automatically be generated upon load (true) or not (false).

◆ copyParams()

virtual void nkGraphics::Texture::copyParams ( const Texture other)
pure virtual

Copies the decription parameters (width, height, format...) from another texture.

Parameters
otherThe texture to copy the information from.

◆ setTextureFormatFromString()

void nkGraphics::Texture::setTextureFormatFromString ( nkMemory::StringView  str)
Parameters
strThe string defining the format to use. StructToString will be used for translation.

◆ setMightManuallyGenerateMip()

void nkGraphics::Texture::setMightManuallyGenerateMip ( bool  value)

Sets whether the texture should expect to get requests to generate its mip chain during its lifetime, or not.

Parameters
valueWhether the mip generation calls are to be expected (true) or not (false.
Remarks
This flag is off by default For more details, see generateMipChain(). It is advised to turn this flag on only when necessary, as it forces the loading process to declare broader usages to the graphics API.

◆ prepareAsTexture2d()

virtual void nkGraphics::Texture::prepareAsTexture2d ( )
virtual

Prepares the texture as a 2d texture. Should be used to change the internal texture type, impacting the way the texture will be loaded.

◆ prepareAsCubemap()

virtual void nkGraphics::Texture::prepareAsCubemap ( )
virtual

Prepares the texture as a cubemap. Should be used to change the internal texture type, impacting the way the texture will be loaded.

◆ prepareAsTexture3d()

virtual void nkGraphics::Texture::prepareAsTexture3d ( )
virtual

Prepares the texture as a 3d texture. Should be used to change the internal texture type, impacting the way the texture will be loaded.

◆ setRenderFlag()

virtual void nkGraphics::Texture::setRenderFlag ( TEX_RENDER_FLAG  value)
virtual

Allows to change the render flag of the texture. It needs to be called for texture that will need to be used as targets.

Parameters
valueThe flag to set.

◆ generateMipChain()

virtual void nkGraphics::Texture::generateMipChain ( unsigned int  fromMip = 0)
pure virtual

Request to generate the texture's mip chain, for available mip levels. This requires the texture to already be loaded.

Parameters
fromMipThe mip level from which the mip chain generation should start.
Remarks
Calling this method requires the correspondig flag to be enabled before the texture is loaded (see setMightManuallyGenerateMip()).

◆ convertToImage()

nkImages::Image nkGraphics::Texture::convertToImage ( int  mip,
int  sliceOrArrayIndex 
)

Allows to access the data of a texture in a practical way, through an image.

Parameters
mipThe mip level from which the data should be accessed.
sliceOrArrayIndexThe slice, or index in the array, to take the memory from.
Returns
The data found in the texture for queried parameters, abstracted behind an image class.
Remarks
This will trigger a map of the image before copying the data into the user-friendly structure. If you need more performances or limit memory usage, it will probably be best to use the standard map() method, albeit more cumbersome to use.

◆ map()

virtual MapResult nkGraphics::Texture::map ( const MapRequestDescriptor requestDesc)
pure virtual

Maps the texture memory for CPU interaction. Be sure to select the smallest map type needed, as a map operation can cause a flush in the rendering pipeline.

Parameters
requestDescThe map request description.
Returns
The mapped data. Be sure to check if the data inside is not nullptr, unveiling an invalid map request.

◆ unmap()

virtual void nkGraphics::Texture::unmap ( const UnmapRequestDescriptor requestDesc)
pure virtual

Unmap the texture memory. This needs to be called the earliest possible after a map operation. This operation will potentially commit the changes made in mapped data, to the GPU.

Parameters
requestDescThe unmap request.

◆ gpuCopyFrom()

virtual void nkGraphics::Texture::gpuCopyFrom ( Texture other,
const ResourceGpuCopyDescriptor descriptor 
)
pure virtual

Copies memory from another texture, in the GPU context.

Parameters
otherThe texture to copy the data from.
descriptorThe description of the data to copy.
Remarks
This function copies GPU memory to GPU memory.

◆ exportClassToTree()

virtual void nkGraphics::Texture::exportClassToTree ( nkExport::Node rootNode)
overridevirtual

Exports an item into a tree describing its structure and its data.

Parameters
rootNodeThe node into which the object has to write its related information.

Implements nkExport::Exportable.

◆ importClassFromTree()

virtual void nkGraphics::Texture::importClassFromTree ( nkExport::Node rootNode)
overridevirtual

Imports information from a tree which is supposed to describe its structure and data.

Parameters
rootNodeThe root node of the tree holding the information.

Implements nkExport::Exportable.

◆ create()

static nkMemory::UniquePtr<Texture> nkGraphics::Texture::create ( System system = nullptr)
static

Creates a standalone resource, linking it to a system, but no manager. This method can be used to allocate a resource and manually manage its lifetime.

Parameters
systemThe system to create the resource into. If left to nullptr, then the Singleton instance will be used.
Returns
The created resource instance.

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