A texture used for rendering, hosted on GPU. More...
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 |
System * | getSystem () 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< Texture > | create (System *system=nullptr) |
A texture used for rendering, hosted on GPU.
|
virtual |
Destructor.
TextureCpuDataDescriptor* nkGraphics::Texture::getCpuData | ( | ) | const |
unsigned int nkGraphics::Texture::getCpuSliceCount | ( | ) | const |
bool nkGraphics::Texture::isFromFile | ( | ) | const |
bool nkGraphics::Texture::isGammaCorrected | ( | ) | const |
bool nkGraphics::Texture::isBackBufferTex | ( | ) | const |
TEX_TYPE nkGraphics::Texture::getTexType | ( | ) | const |
TEX_RENDER_FLAG nkGraphics::Texture::getRenderFlag | ( | ) | const |
unsigned int nkGraphics::Texture::getNeededMipsForSize | ( | ) | const |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
|
pure virtual |
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 :
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.
data | The texture data to feed from the cpu to the texture. |
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 :
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.
data | The texture data to feed from the cpu to the texture. |
byteOffset | The offset, in bytes, at which slice data starts in buffer. |
rowByteSize | The 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. |
sliceByteSize | The size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height. |
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.
data | Data to provide to populate the slice. |
byteOffset | The offset, in bytes, at which slice data starts in buffer. |
rowByteSize | The 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. |
sliceByteSize | The size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height. |
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.
data | Data to provide to populate the slice. |
byteOffset | The offset, in bytes, at which slice data starts in buffer. |
rowByteSize | The 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. |
sliceByteSize | The size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height. |
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.
byteOffset | The 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. |
rowByteSize | The 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. |
sliceByteSize | The size of the slice, in bytes. Leave it to 0 to have it derived from the row size and the texture's height. |
void nkGraphics::Texture::setBackBufferTex | ( | bool | value | ) |
value | If the texture is the back buffer, aka the final texture, of a RenderContext. |
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 :
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.
image | The image to use as input. |
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().
image | The image to use as input. |
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().
image | The image to use as input. |
|
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.
|
virtual |
value | If the texture should be gamma corrected (true) or not (false). |
|
overridevirtual |
Sets the resource's path, relative to the working directory. See nkResources::ResourceManager for path naming conventions.
value | The path to use. |
Reimplemented from nkGraphics::Resource.
|
pure virtual |
width | The width of the texture, in pixels. |
|
pure virtual |
height | The height of the texture, in pixels. |
|
pure virtual |
depth | The depth or array size of the texture, in pixels / slices. |
|
pure virtual |
value | The number of mips wanted for the texture. Can be 0 to mean that all mips should be used. |
|
pure virtual |
format | The format to assign to the texture. |
|
pure virtual |
rights | The cpu access flag wanted. |
|
pure virtual |
usage | The texture usage. |
|
pure virtual |
binding | The binding flag to use. Can be or'ed. |
|
pure virtual |
value | If the missing mips should automatically be generated upon load (true) or not (false). |
|
pure virtual |
Copies the decription parameters (width, height, format...) from another texture.
other | The texture to copy the information from. |
void nkGraphics::Texture::setTextureFormatFromString | ( | nkMemory::StringView | str | ) |
str | The string defining the format to use. StructToString will be used for translation. |
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.
value | Whether the mip generation calls are to be expected (true) or not (false. |
|
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.
|
virtual |
Prepares the texture as a cubemap. Should be used to change the internal texture type, impacting the way the texture will be loaded.
|
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.
|
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.
value | The flag to set. |
|
pure virtual |
Request to generate the texture's mip chain, for available mip levels. This requires the texture to already be loaded.
fromMip | The mip level from which the mip chain generation should start. |
nkImages::Image nkGraphics::Texture::convertToImage | ( | int | mip, |
int | sliceOrArrayIndex | ||
) |
Allows to access the data of a texture in a practical way, through an image.
mip | The mip level from which the data should be accessed. |
sliceOrArrayIndex | The slice, or index in the array, to take the memory from. |
|
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.
requestDesc | The map request description. |
|
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.
requestDesc | The unmap request. |
|
pure virtual |
Copies memory from another texture, in the GPU context.
other | The texture to copy the data from. |
descriptor | The description of the data to copy. |
|
overridevirtual |
Exports an item into a tree describing its structure and its data.
rootNode | The node into which the object has to write its related information. |
Implements nkExport::Exportable.
|
overridevirtual |
Imports information from a tree which is supposed to describe its structure and data.
rootNode | The root node of the tree holding the information. |
Implements nkExport::Exportable.
|
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.
system | The system to create the resource into. If left to nullptr, then the Singleton instance will be used. |