Kanzi  3.9.5
Kanzi Engine API
kanzi::Texture Class Reference

Textures provide images that can be used with image nodes, texture brushes and materials for use in 3D rendering or material brushes. More...

#include <kanzi/core.ui/platform/graphics_backend/gl/texture.hpp>

Inheritance diagram for kanzi::Texture:
[legend]

Classes

struct  CreateInfo
 Struct which contains all the parameters that are needed for texture creation. More...
 
struct  CreateInfo2D
 Texture creation parameters for two dimensional texture. More...
 
struct  CreateInfoCubemap
 Texture creation parameters for cubemap texture that is initialized from six images. More...
 
struct  CreateInfoHostCopy2D
 Texture creation parameters for two dimensional texture that is updated from the CPU. More...
 
struct  CreateInfoNode2DRenderTarget
 Texture creation parameters for texture that can be used as render target for 2D nodes. More...
 
struct  CreateInfoRenderpassRenderTarget
 Texture creation parameters for texture that can be used as render target for renderpasses. More...
 

Public Member Functions

void generateMipmaps ()
 Generates the mipmaps from the base level image. More...
 
GraphicsFormat getDepthStencilFormat () const
 Returns depth/stencil format of the texture. More...
 
RenderbufferSharedPtr getDepthStencilRenderbuffer () const
 Returns internal depth/stencil renderbuffer. More...
 
unsigned int getHeightDivisor () const
 Gets height divisor for automatic sizes. More...
 
BitmapImageSharedPtr getHostCopyImage (Face face, unsigned int slice) const
 Returns the host-side memory copy of texture data as an image, if available. More...
 
BitmapImageSharedPtr getHostCopyImage () const
 Returns the host-side memory copy of a non-cubemap texture, if available. More...
 
NativeDeploymentTarget getNativeDeploymentTarget () const
 Returns the native deployment target. More...
 
NativeFramebufferHandle getNativeFramebufferHandle () const
 Gets native framebuffer handle for the texture. More...
 
NativeTextureHandle getNativeHandle () const
 Gets native texture handle for the texture. More...
 
RenderTargetMode getRenderTargetMode () const
 Returns rendertarget mode of the texture. More...
 
const SamplergetSampler () const
 Returns the Sampler used by the texture. More...
 
TextureType getType () const
 Returns type of the texture. More...
 
unsigned int getWidthDivisor () const
 Gets width divisor for automatic sizes. More...
 
bool hasAutomaticHeight () const
 Indicates whether height is or should be automatically calculated. More...
 
bool hasAutomaticWidth () const
 Indicates whether width is or should be automatically calculated. More...
 
void reattachFramebuffer ()
 Reattaches the internal framebuffer object. More...
 
void reattachFramebuffer (RenderbufferSharedPtr colorRenderbuffer)
 Reattaches the internal framebuffer object and includes the renderbuffer given as parameter. More...
 
void reattachFramebuffer (TextureSharedPtr depthTexture)
 Reattaches the internal framebuffer object and includes the depth texture given as parameter. More...
 
void recreate (CreateInfo &createInfo)
 Validates the CreateInfo texture descriptor, creates a new texture and swaps it in place. More...
 
void resize (unsigned width, unsigned height)
 Changes the size of the texture. More...
 
void setData (Face face, unsigned int mipmapLevel, unsigned int x, unsigned int y, unsigned int width, unsigned int height, const kanzi::byte *data)
 Sets the texture data for the specified area in a texture. More...
 
void setData (unsigned int mipmapLevel, unsigned int x, unsigned int y, unsigned int width, unsigned int height, const kanzi::byte *data)
 Sets the texture data for the specified area in the texture. More...
 
void setData (const kanzi::byte *data)
 Sets the texture data for base level of a non-cubemap texture. More...
 
void setHeightDivisor (unsigned int divisor)
 Sets the height divisor. More...
 
void setWidthDivisor (unsigned int divisor)
 Sets the wight divisor. More...
 
- Public Member Functions inherited from kanzi::Surface
void attach (Usage usage, APIAttachment apiAttachment, Face face, unsigned int mipmapLevel)
 Attach surface to framebuffer. More...
 
unsigned int getFaceCount () const
 Get number of faces. This should be six for cubemaps and one for everything else. More...
 
unsigned int getFeatures () const
 Get features for Surface. More...
 
GraphicsFormat getFormat () const
 Get GraphicsFormat of Surface. More...
 
unsigned int getHeight () const
 Get height in pixels. More...
 
unsigned int getMipmapLevelCount () const
 Get number of mipmap levels. More...
 
unsigned int getRenderTargetSampleCount () const
 Get number of multisample samples for Surface. More...
 
unsigned int getSliceCount () const
 Get number of slices. More...
 
unsigned int getWidth () const
 Get width in pixels. More...
 
- Public Member Functions inherited from kanzi::GPUResource
unsigned int getGPUMemoryUsage () const
 
RenderergetRenderer () const
 
void invalidate ()
 Notify resource that graphics context was lost and all GPU resources are invalid. More...
 
bool isDeployed () const
 
 ~GPUResource () override
 
- Public Member Functions inherited from kanzi::Resource
virtual unsigned int getCPUMemoryUsage () const
 Function for getting the memory usage of a resource. More...
 
const string & getName () const
 Gets the resource name. More...
 
const string & getUrl () const
 Gets the resource URL. More...
 
bool isKeepAlive () const
 Tells if the resource has keep alive flag set. More...
 
void reload ()
 
void reloadFromFile (string_view filePath)
 
void reloadFromKzb (KzbFile &kzbFile, ReadOnlyMemoryFile &file, KzbMemoryParser &parser)
 
void setKeepAlive (bool keepAlive)
 Sets the keep alive flag. More...
 
void setUrl (string_view url)
 Sets the resource URL. More...
 
 ~Resource () override
 Destructor. More...
 
- Public Member Functions inherited from kanzi::Object
AppliedStyleEntrySharedPtr applyObjectStyle (kanzi::StyleSharedPtr style)
 Applies a style to an object. More...
 
void applyObjectStyles ()
 Apply all styles for an object node. More...
 
DomaingetDomain () const
 Returns the domain the object belongs to. More...
 
const MetaclassgetDynamicMetaclass () const override
 Returns the metaclass of the dynamic type of the object. More...
 
MainLoopSchedulergetMainLoopScheduler () const
 Returns the MainLoopScheduler instance of the associated Domain. More...
 
detail::MessageDispatcher * getMessageDispatcher () const
 Returns the message dispatcher of the object. More...
 
ResourceManagergetResourceManager () const
 Returns the resource manager of the object. More...
 
ScriptingContextSharedPtr getScriptingContext () const
 Gets the scripting context of the object. More...
 
 Object (Domain *domain)
 
void setScriptingContext (ScriptingContextSharedPtr context)
 Sets the scripting context of the object. More...
 
void unapplyObjectStyle (AppliedStyleEntrySharedPtr appliedStyleEntry)
 
void unapplyObjectStyles ()
 Unapplies and removes all applied styles. More...
 
 ~Object () override
 
- Public Member Functions inherited from kanzi::MetaObject
bool isTypeOf (const Metaclass *objectType) const
 Determines if the type of this object is the given type or derived from it. More...
 
virtual ~MetaObject ()
 
- Public Member Functions inherited from kanzi::PropertyObject
template<typename DataType >
void addPropertyModifier (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner)
 
template<typename DataType >
void addPropertyNotificationHandler (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::NotificationCallback callback, void *owner)
 
template<typename DataType >
void addPropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, PropertyValuePrecedence precedence, void *ownerPointer)
 
template<typename DataType >
void addPropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, PropertyValuePrecedence precedence, AbstractPropertyTypeDescriptor::ValueSourceOwner *owner)
 
PropertyStorageContainer::iterator beginPropertyStorage ()
 Returns the begin iterator to the internal property storage container. More...
 
PropertyStorageContainer::const_iterator beginPropertyStorage () const
 Returns the begin iterator to the internal property storage container. More...
 
void clearPropertyFlag (AbstractPropertyType propertyType, uint32_t flag)
 
void copyLocalValue (const PropertyObject &other, AbstractPropertyType propertyType)
 Copies local value of single property from another object. More...
 
void copyLocalValues (const PropertyObject &other)
 Copies all local values from another object. More...
 
PropertyStorageContainer::iterator endPropertyStorage ()
 Returns the end iterator to the internal property storage container. More...
 
PropertyStorageContainer::const_iterator endPropertyStorage () const
 Returns the end iterator to the internal property storage container. More...
 
template<typename DataType >
PropertyType< DataType >::Traits::ReturnType getAbstractProperty (AbstractPropertyType abstractPropertyType) const
 
template<typename DataType >
PropertyType< DataType >::Traits::ReturnType getAbstractPropertyBase (AbstractPropertyType abstractPropertyType) const
 
template<typename DataType >
optional< typename PropertyType< DataType >::Traits::ReturnType > getOptionalAbstractProperty (AbstractPropertyType abstractPropertyType) const
 
template<typename DataType >
optional< typename PropertyType< DataType >::Traits::ReturnType > getOptionalProperty (const PropertyType< DataType > &propertyType) const
 Evaluates the property value in the same way as the overload above but does not default to the value in property metadata if there are no inputs to the property value. More...
 
template<typename DataType >
optional< typename PropertyType< DataType >::Traits::ReturnType > getOptionalPropertyBase (const PropertyType< DataType > &propertyType) const
 Returns the current value of a property disregarding modifiers, but does not default to the value in property metadata if there are no inputs to the property value. More...
 
template<typename DataType >
PropertyType< DataType >::Traits::ReturnType getProperty (const PropertyType< DataType > &propertyType) const
 Returns the current value of a property type. More...
 
template<typename DataType >
PropertyType< DataType >::Traits::ReturnType getPropertyBase (const PropertyType< DataType > &propertyType) const
 Returns the current value of a property disregarding modifiers. More...
 
template<typename DataType >
size_t getPropertyNotificationHandlerCount (const PropertyType< DataType > &propertyType) const
 Gets number of current notification handlers for given property type. More...
 
bool hasBaseValue (AbstractPropertyType propertyType) const
 Evaluates whether there are any inputs into the property value, disregarding modifiers. More...
 
bool hasLocalValue (AbstractPropertyType propertyType) const
 Evaluates whether there is a local value set for the property. More...
 
bool hasNonClassValue (AbstractPropertyType propertyType) const
 Evaluates whether there is a value of any precedence higher than class default value set for the property. More...
 
bool hasValue (AbstractPropertyType propertyType) const
 Evaluates whether there are any inputs into the property value. More...
 
bool isPropertyFlagSet (AbstractPropertyType propertyType, uint32_t flag) const
 
virtual void onPropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason)
 Virtual function to handle property change notifications. More...
 
 PropertyObject ()
 
void removeKzbProperties (flat_set< AbstractPropertyType > *keepProperties)
 Remove all KZB properties that are not included in a given set. More...
 
void removeKzbProperties ()
 Remove all KZB properties. More...
 
template<typename DataType >
void removeLocalPropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, void *ownerPointer)
 
void removeLocalValue (AbstractPropertyType propertyType)
 Removes the local value associated with the property. More...
 
template<typename DataType >
void removePropertyModifier (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner)
 
template<typename DataType >
void removePropertyNotificationHandler (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::NotificationCallback callback, void *owner)
 
template<typename DataType >
void removePropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource *valueSource, void *ownerPointer)
 
template<typename DataType >
void setAbstractProperty (AbstractPropertyType abstractPropertyType, typename PropertyType< DataType >::Traits::ParameterType value)
 
template<typename DataType >
void setProperty (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Traits::ParameterType value)
 Sets the local value of a property type. More...
 
void setPropertyFlag (AbstractPropertyType propertyType, uint32_t flag)
 
void validatePropertyModifiers (AbstractPropertyType propertyType)
 
virtual ~PropertyObject ()
 

Static Public Member Functions

static TextureSharedPtr create (Domain *domain, const CreateInfo &createInfo, string_view name)
 Creates a texture with specified texture creation parameters. More...
 
static TextureSharedPtr create (Domain *domain, TextureType type, int nativeHandle, bool takeOwnership, GraphicsFormat format, unsigned int mipmapLevelCount, unsigned int width, unsigned int height, string_view name)
 Creates texture from a pre-existing GL texture object. More...
 
static ResourceManager::LoadTaskSharedPtr createGenericFileLoadTask (string_view name, unique_ptr< File > file, Domain *domain)
 Create a task used to create a Texture from generic file. More...
 
static ResourceManager::LoadTaskSharedPtr createLoadTask (string_view name, KzbFile *kzbFile, ReadOnlyMemoryFilePtr file)
 Create a task used to create a Texture from KZB File. More...
 
- Static Public Member Functions inherited from kanzi::Object
static const MetaclassgetStaticMetaclass ()
 Returns the metaclass of Object class. More...
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 Default implementation that returns empty editor info. More...
 
- Static Public Member Functions inherited from kanzi::MetaObject
static const MetaclassgetStaticMetaclass ()
 Returns the metaclass of Object class. More...
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 Default implementation that returns empty editor info. More...
 

Protected Member Functions

void attachOverride (Usage usage, APIAttachment apiAttachment, Face face, unsigned int mipmapLevel) override
 Surface::attachOverride() implementation. More...
 
void deployImages (Renderer &renderer, const vector< BitmapImageSharedPtr > &images)
 Helper function to setup GL texture object state and initial data. More...
 
void deployInternalFramebuffers (Renderer &renderer, RenderbufferSharedPtr colorRenderbuffer, TextureSharedPtr depthTexture)
 Helper function to setup GL framebuffer and renderbuffer state Called as part of texture construction. More...
 
unsigned int getCPUMemoryUsageOverride () const override
 Resource::getCPUMemoryUsageOverride() implementation. More...
 
unsigned int getFaceCountOverride () const override
 Surface::getFaceCountOverride() implementation. More...
 
unsigned int getFeaturesOverride () const override
 Surface::getFeaturesOverride() implementation. More...
 
GraphicsFormat getFormatOverride () const override
 Surface::getFormatOverride() implementation. More...
 
unsigned int getGPUMemoryUsageOverride () const override
 GpuResource::getGPUMemoryUsageOverride() implementation. More...
 
unsigned int getHeightOverride () const override
 Surface::getHeightOverride() implementation. More...
 
unsigned int getMipmapLevelCountOverride () const override
 Surface::getMipmapLevelCountOverride() implementation. More...
 
unsigned int getRenderTargetSampleCountOverride () const override
 Surface::getRenderTargetSampleCountOverride() implementation. More...
 
unsigned int getSliceCountOverride () const override
 Surface::getSliceCountOverride() implementation. More...
 
unsigned int getWidthOverride () const override
 Surface::getWidthOverride() implementation. More...
 
void invalidateOverride () override
 GPUResource::invalidateOverride() implementation. More...
 
bool isDeployedOverride () const override
 GpuResource::isDeployed() implementation. More...
 
void reloadFromFileOverride (string_view filePath) override
 Resource::reloadFromFileOverride() implementation. More...
 
void reloadFromKzbOverride (KzbFile &kzbFile, ReadOnlyMemoryFile &file, KzbMemoryParser &parser) override
 Resource::reloadFromKzbOverride() implementation. More...
 
void reloadOverride () override
 Resource::reloadOverride() implementation. More...
 
 Texture (Domain *domain, const CreateInfo &createInfo, string_view name)
 Creates texture from CreateInfo. More...
 
 Texture (Domain *domain, TextureType type, int glHandle, bool takeOwnership, GraphicsFormat format, unsigned int mipmapLevelCount, unsigned int width, unsigned int height, string_view name)
 Creates texture from an existing GL object handle. More...
 
- Protected Member Functions inherited from kanzi::Surface
 Surface (Domain *domain, string_view name)
 
- Protected Member Functions inherited from kanzi::GPUResource
 GPUResource (Domain *domain, string_view name="")
 Constructor. More...
 
- Protected Member Functions inherited from kanzi::Resource
 Resource (Domain *domain, string_view name)
 Constructor. More...
 
- Protected Member Functions inherited from kanzi::Object
void initialize ()
 
void onCopy (const Object &other)
 
- Protected Member Functions inherited from kanzi::MetaObject
void initialize ()
 
 MetaObject ()
 
- Protected Member Functions inherited from kanzi::PropertyObject
AbstractPropertyTypeDescriptor::ValueSourceEntryacquireLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, PropertyStoragePtr &propertyStorage)
 Acquires a local value source entry that is free for the assignment of a value. More...
 
AbstractPropertyTypeDescriptor::ModifierStorageacquireModifierStorage (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
 
AbstractPropertyTypeDescriptor::NotificationStorageacquireNotificationStorage (AbstractPropertyTypeDescriptor &descriptor)
 
PropertyStoragePtr acquirePropertyStorage (AbstractPropertyTypeDescriptor &descriptor)
 
void addPropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource *valueSource, PropertyValuePrecedence precedence, void *ownerPointer)
 Internally adds a property value source. More...
 
void addPropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource *valueSource, PropertyValuePrecedence precedence, AbstractPropertyTypeDescriptor::ValueSourceOwner *owner)
 Internally adds a property value source. More...
 
AbstractPropertyTypeDescriptor::ValueSourceEntryconstructLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
 
PropertyStoragePtr constructPropertyStorage (AbstractPropertyTypeDescriptor &descriptor)
 
void copyLocalValue (const AbstractPropertyTypeDescriptor::PropertyStorage &otherPropertyStorage)
 Copy local value from property storage. More...
 
AbstractPropertyTypeDescriptor::ModifierStoragefindModifierStorage (AbstractPropertyTypeDescriptor &descriptor)
 
AbstractPropertyTypeDescriptor::NotificationStoragefindNotificationStorage (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::PropertyStoragefindPropertyStorage (AbstractPropertyTypeDescriptor &descriptor) const
 Gets the property storage for given property type descriptor. More...
 
PropertyStoragePtr findPropertyStoragePtr (AbstractPropertyTypeDescriptor &descriptor) const
 Gets property storage intrusive pointer which you can use to hold a reference until the end of the operation. More...
 
AbstractPropertyTypeDescriptorfindPropertyTypeDescriptorByNameAndDataType (string_view name, PropertyDataType dataType) const
 Finds a property type descriptor by name and data type. More...
 
AbstractPropertyTypeDescriptorfindPropertyTypeDescriptorByQualifiedNameAndDataType (string_view qualifiedName, PropertyDataType dataType) const
 Like findPropertyTypeDescriptorByNameAndDataType, but only searches by matching with qualified names. More...
 
AbstractPropertyTypeDescriptorfindPropertyTypeDescriptorByUnqualifiedNameAndDataType (string_view unqualifiedName, PropertyDataType dataType) const
 Like findPropertyTypeDescriptorByNameAndDataType, but only searches by matching with unqualified names. More...
 
AbstractPropertyTypeDescriptor::ValueSourcegetClassValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourcegetFinalValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourcegetNonClassValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourcegetTopValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 Gets the top-level value source for a given property descriptor. More...
 
virtual void notifyPropertyHandlers (PropertyStoragePtr &propertyStorage, PropertyNotificationReason reason)
 
void onCopy (const PropertyObject &other)
 
void removeLocalValue (AbstractPropertyTypeDescriptor &descriptor, PropertyStoragePtr &propertyStorage)
 Removes a local value from the given property storage. More...
 
void removePropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource *valueSource, void *owner)
 Removes a property value source. More...
 
void validatePropertyModifiersAndNotifyHandlers (PropertyStoragePtr &propertyStorage)
 

Static Protected Member Functions

static GLFramebufferHandle makeFramebuffer (Renderer *renderer, const CreateInfo &createInfo)
 Helper function to create GL framebuffer object. More...
 
static vector< BitmapImageSharedPtrmakeHostCopyImages (const CreateInfo &createInfo)
 Helper function to allocate host images. More...
 
static GLTextureHandle makeTexture (Renderer *renderer, const CreateInfo &createInfo)
 Helper function to create GL texture object. More...
 

Friends

class ResourceManager
 
void swap (Texture &texture1, Texture &texture2)
 

Additional Inherited Members

- Public Types inherited from kanzi::Surface
enum  APIAttachment {
  APIAttachmentColor0, APIAttachmentColor1, APIAttachmentColor2, APIAttachmentColor3,
  APIAttachmentDepth, APIAttachmentStencil, APIAttachmentCount, APIAttachmentInvalid
}
 
enum  Face {
  FacePositiveX, FaceNegativeX, FacePositiveY, FaceNegativeY,
  FacePositiveZ, FaceNegativeZ, FaceDefault
}
 Texture face enumeration. More...
 
enum  Usage { UsageRenderTarget, UsageMultisampleResolveBlitDestination }
 
- Public Types inherited from kanzi::GPUResource
enum  MemoryType { GpuOnly, GpuAndRam, RamOnly }
 Memory upload and RAM preservation strategy for GPU resources. More...
 
- Public Types inherited from kanzi::PropertyObject
typedef PropertyStorageContainer::const_iterator PropertyStorageConstIterator
 
typedef vector< PropertyStoragePtrPropertyStorageContainer
 
typedef PropertyStorageContainer::iterator PropertyStorageIterator
 
typedef intrusive_ptr< AbstractPropertyTypeDescriptor::PropertyStoragePropertyStoragePtr
 
typedef PropertyStorageContainer::reverse_iterator PropertyStorageReverseIterator
 
- Protected Types inherited from kanzi::Object
typedef vector< AppliedStyleEntrySharedPtrAppliedStyleContainer
 Applied style container. More...
 
- Protected Attributes inherited from kanzi::Object
AppliedStyleContainer m_appliedStyles
 Listing of applied styles applied to this object. More...
 

Detailed Description

Textures provide images that can be used with image nodes, texture brushes and materials for use in 3D rendering or material brushes.

Textures can be set as render target. Texture can be set to as render target for either 2d node or render pass, but not both.

For details on the render target texture, see RenderTargetMode, CreateInfoNode2DRenderTarget, and CreateInfoRenderpassRenderTarget. Note that the CreateInfoRenderpassRenderTarget is intended for use with the deprecated LegacyRenderPass. For all other render passes, use CreateInfoNode2DRenderTarget, or to acquire the composition targets use the CompositionManager.

Texture can optionally maintain CPU accessible copy of texture data. See CreateInfoHostCopy2D. for CPU accessible texture data details.

In order to create a texture, you must prepare Texture::CreateInfo structure and make sure it is valid using CreateInfo::validate(), then create the texture with Texture::create(). If texture creation parameters are not valid, Texture::create() will throw an exception, which can stop program execution.

Two dimensional textures can be created from Image or by specifying size, format and features. Cubemap textures can be created from six Images or by specifying size, format and features.

You must specify texture filtering, addressing mode (also known as wrap mode), and mipmap settings in Texture::CreateInfo before you create the texture. Two dimensional textures which are shown without scaling can be created with default texture creation parameters, which improve performance and reduce memory usage. If you show texture content with scaling, consider using linear filtering and prefiltered mipmaps to reduce aliasing, with some performance and memory cost.

Examples - Creating Textures with Kanzi C++ API

To create a two dimensional texture from image:

// This example shows how to create a texture from an image for use
// where texture content is shown without scaling. Texture will be
// created with default CreateInfo2D settings.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Texture::create()
// \see Texture::CreateInfo2D
BitmapImageUniquePtr image = generateImage(512, 512, 0, false);
TextureSharedPtr texture = Texture::create(domain, Texture::CreateInfo2D(kanzi::move(image)), "Texture");

To load image from file and create texture:

// Load an image file and create a texture out of it.
TextureSharedPtr texture = domain->getResourceManager()->acquireResource<Texture>(string("file://") + filePath);

To access the image data after you create a texture:

// Fill image data with opaque red.
unique_ptr<uint8_t[]> sourceData(new uint8_t[512 * 512 * 4]);
for (unsigned it = 0; it < 512 * 512 * 4; it += 4)
{
sourceData[it + 0] = 255u;
sourceData[it + 1] = 0u;
sourceData[it + 2] = 0u;
sourceData[it + 3] = 255u;
}
// Create an image.
BitmapImage* imagePtr = image.get();
// Create a texture from the image. This texture keeps the ownership of the image.
// This means that the image is also automatically destroyed when the texture is destroyed.
Texture::CreateInfo2D createInfo(kanzi::move(image));
createInfo.memoryType = GPUResource::GpuAndRam;
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
// Get the host copy of the image you created. In this case the getHostCopyImage() returns a
// pointer that is identical to the variable imagePtr you created above.
BitmapImageSharedPtr hostCopyImage = texture->getHostCopyImage();

To create a two dimensional texture from image with custom sampler settings:

// This example shows how to create a texture from an image image for use
// where texture content is potentially shown with scaling.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Texture::create()
// \see Texture::CreateInfo2D
Texture::CreateInfo2D createInfo(kanzi::move(image));
// Adjust filter and mipmap settings to minimize aliasing.
createInfo.minificationFilter = Sampler::FilterLinear;
createInfo.magnificationFilter = Sampler::FilterLinear;
createInfo.mipmapMode = Sampler::MipmapModeLinear;
// Get size and format from the image
createInfo.updateShapeAndFormatFromImages();
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");

To create a cubemap texture from 6 face images:

// This example shows how to create a cube map texture from six images.
// This texture could be used in materials for 3D rendering.
// \see Image
// \see Texture::CreateInfoCubemap
// \see Texture::create()
Texture::CreateInfoCubemap createInfo(kanzi::move(images));
// Adjust filter and mipmap settings to minimize aliasing.
createInfo.minificationFilter = Sampler::FilterLinear;
createInfo.magnificationFilter = Sampler::FilterLinear;
createInfo.mipmapMode = Sampler::MipmapModeLinear;
// Get size and format from the images.
createInfo.updateShapeAndFormatFromImages();
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");

Examples - Loading textures with Kanzi C++ API using ResourceManager

To load texture with ResourceManager using file URL:

TextureSharedPtr texture = resourceManager->acquireResource<Texture>("file://./upTestImage.jpg");

To load texture with ResourceManager:

TextureSharedPtr texture = resourceManager->acquireResource<Texture>(textureUrl);

Examples - Updating texture data with Kanzi C++ API

To update texture data of two dimensional texture base level image:

// Use Texture::setData() to update texture contents on two dimensional texture without host copy.
unsigned int width = 512;
unsigned int height = 512;
TextureSharedPtr texture = Texture::create(domain, Texture::CreateInfoHostCopy2D(width, height, GraphicsFormatR8G8B8_UNORM), "Texture");
// Set all texture data
{
vector<byte> data = generateTextureData(width, height, 0);
texture->setData(data.data());
}
// Set subrectangle
{
unsigned int updateWidth = width / 2;
unsigned int updateHeight = height / 2;
vector<byte> data = generateTextureData(updateWidth, updateHeight, 0);
unsigned int mipmapLevel = 0;
texture->setData(mipmapLevel, width - updateWidth, 0, updateWidth, updateHeight, data.data());
}

To update texture data of cubemap texture all mipmap level images:

// Use setData() to update texture contents on cubemap texture with host copy and mipmaps.
// All mipmap levels of all cubemap faces are set.
Texture::CreateInfo createInfo;
createInfo.type = TextureTypeCubeMap;
createInfo.width = 512;
createInfo.height = 512;
createInfo.format = GraphicsFormatR8G8B8_UNORM;
createInfo.features = GraphicsFormatFeatureSampledImage;
createInfo.memoryType = Texture::GpuAndRam;
createInfo.mipmapMode = Sampler::MipmapModeLinear;
createInfo.mipmapLevelCount = calculateMipmapLevelCount(createInfo.width, createInfo.height);
TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
unsigned int width = texture->getWidth();
unsigned int height = texture->getHeight();
for (unsigned int mipmapLevel = 0; mipmapLevel < createInfo.mipmapLevelCount; ++mipmapLevel)
{
for (unsigned int faceIndex = 0; faceIndex < 6; ++faceIndex)
{
Surface::Face face = static_cast<Surface::Face>(faceIndex);
vector<byte> data = generateTextureData(width, height, faceIndex);
texture->setData(face, mipmapLevel, 0, 0, width, height, data.data());
}
width /= 2;
height /= 2;
}

Examples - Use texture as render target for node 2D or renderpass using Kanzi C++ API

To use texture as render target for 2D node:

// This example shows how to create a Texture and use it as a render target for a 2D node.
//
// Kanzi renders the node to the texture as specified with Node2D::setRenderTarget().
// Kanzi renders the node only to the texture as specified with Node2D::setOffscreenRendering().
//
// \see Node2D::RenderTargetProperty
// \see Node2D::OffscreenRenderingProperty
// \see Texture::CreateInfoNode2DRenderTarget
// \see Texture::create()
// Create a node tree.
ScreenSharedPtr screen = Screen::create(domain, "screen");
screen->attach();
// Create a node.
EmptyNode2DSharedPtr node = EmptyNode2D::create(domain, "node");
screen->addChild(node);
// Create a background brush for the node.
ColorBrushSharedPtr brush = ColorBrush::create(domain, "brush", ColorRGBA(0.4f, 0.4f, 0.9f, 1.0f));
node->setBackgroundBrush(brush);
// Create a render target texture for the node.
Texture::CreateInfoNode2DRenderTarget textureCreateInfo(width, height, GraphicsFormatR8G8B8A8_UNORM);
TextureSharedPtr renderTarget = Texture::create(domain, textureCreateInfo, "texture");
node->setRenderTarget(renderTarget);
// Render only to the render target texture.
node->setOffscreenRendering(true);
// Render the node tree.
{
CompositionStack& compositionStack = renderer->getCompositionStack();
screen->setAllocatedSize(Vector2(static_cast<float>(width), static_cast<float>(height)));
screen->setArrangeTransform(Matrix3x3());
screen->layout();
compositionStack.pushComposition(0, screen->getAllocatedSize());
screen->render(*renderer, compositionStack);
compositionStack.popComposition();
}
screen->detach();

To use texture as render target for renderpass:

// This example shows how to create a Texture and use it as a render target
// for a render pass as used by a Viewport2D node.
//
// This texture could be used as content in Image2D nodes or texture brushes.
// This texture could also be used in materials for 3D rendering or material brushes.
//
// Renderpass will render a scene to the texture as specified with Renderpass::setRenderPassRenderTargetColor0().
// \see Renderpass
// \see Viewport2D
// \see Scene
// \see Texture::CreateInfoRenderpassRenderTarget
// \see Texture::create()
ScreenSharedPtr screen = Screen::create(domain, "screen");
screen->attach();
// Create Viewport2D node.
screen->addChild(viewport);
// Create Scene.
SceneSharedPtr scene = Scene::create(domain, "test scene");
viewport->setScene(scene);
// All scenes require a camera.
CameraSharedPtr camera = Camera::create(domain, "camera");
scene->addChild(camera);
scene->setCamera(camera);
// Create rendertarget texture.
Texture::CreateInfoRenderpassRenderTarget textureCreateInfo(width, height, GraphicsFormatR8G8B8A8_UNORM);
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Create renderpass prefab.
// There is no other content in the scene, but we do apply clear color.
ColorRGBA lightBlue(0.4f, 0.4f, 0.9f, 1.0f);
clearTemplate->addPropertyValue(ClearRenderPass::ClearColor0Property, Variant(lightBlue));
// Set texture to the composition target render pass.
rootTemplate->addPropertyValue(CompositionTargetRenderPass::CompositionTarget0Property, Variant(static_pointer_cast<Resource>(texture)));
rootTemplate->addChild(clearTemplate);
rootTemplate->addChild(drawTemplate);
RenderPassPrefabSharedPtr rootPrefab = RenderPassPrefab::create(domain, "test render pass prefab", rootTemplate);
viewport->setRenderPassPrefab(rootPrefab);
// Render the node tree.
{
CompositionStack& compositionStack = renderer3D->getCompositionStack();
screen->setAllocatedSize(Vector2(static_cast<float>(width), static_cast<float>(height)));
screen->setArrangeTransform(Matrix3x3());
screen->layout();
compositionStack.pushComposition(0, screen->getAllocatedSize());
screen->render(*renderer3D, compositionStack);
compositionStack.popComposition();
}
screen->detach();

Examples - Render to texture with framebuffer (OpenGL and OpenGL ES only) using Kanzi C++ API

To create a two dimensional texture and render to it through framebuffer:

// This example shows how to create a two dimensional texture without mipmaps and render to it with framebuffer.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Framebuffer
// \see Texture::CreateInfo2D
// \see Texture::create()
Texture::CreateInfoNode2DRenderTarget textureCreateInfo(512, 512, GraphicsFormatR8G8B8A8_UNORM);
// Adjust filter settings to reduce aliasing
textureCreateInfo.minificationFilter = Sampler::FilterLinear;
textureCreateInfo.magnificationFilter = Sampler::FilterLinear;
// Add depthStencil renderbuffer, for depth test to work. In this example
textureCreateInfo.depthStencilFormat = renderer->getDepthStencilFormatForRenderbuffer(true, false);
// Create the texture
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Render something to framebuffer. Here we just clear the texture.
renderer->bindFramebuffer(texture->getNativeFramebufferHandle());
renderer->setViewport(ViewportRectangle(0, 0, texture->getWidth(), texture->getHeight()));
// Fill texture with a color
renderer->resetClearTarget();
renderer->addClearColor(0, 0.5f, 0.6f, 0.7f, 1.0f);
renderer->clear();
renderer->resetClearTarget();
renderer->resetActiveFramebuffer();

To create a two dimensional texture with mipmaps and render to it through framebuffer:

// This example shows how to create a two dimensional texture with mipmaps
// and render to it with a framebuffer.
// The texture could be used as content in Image2D nodes or texture brushes.
// The texture could also be used in materials for 3D rendering or material brushes.
// \see Framebuffer
// \see Texture::CreateInfo2D
Texture::CreateInfoNode2DRenderTarget textureCreateInfo(512, 512, GraphicsFormatR8G8B8A8_UNORM);
// Adjust filter settings to reduce aliasing
textureCreateInfo.minificationFilter = Sampler::FilterLinear;
textureCreateInfo.magnificationFilter = Sampler::FilterNearest;
// Specify that texture needs to be created with mipmaps
textureCreateInfo.mipmapMode = Sampler::MipmapModeLinear;
textureCreateInfo.mipmapLevelCount = calculateMipmapLevelCount(textureCreateInfo.width, textureCreateInfo.height);
// Create the texture
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Render something to framebuffer. Here we just clear the base level image of the texture.
renderer->bindFramebuffer(texture->getNativeFramebufferHandle());
renderer->setViewport(ViewportRectangle(0, 0, texture->getWidth(), texture->getHeight()));
renderer->resetClearTarget();
renderer->addClearColor(0, 0.5f, 0.6f, 0.7f, 1.0f);
renderer->clear();
renderer->resetClearTarget();
renderer->resetActiveFramebuffer();
// Generate mipmaps for texture. Without this, remaining mipmap level images would have undefined content.
texture->generateMipmaps();

To create a cubemap texture with mipmaps and render to it through framebuffers:

// This example shows how to create a cubemap texture with mipmpas and render to it with a set of framebuffers.
// This texture could be used in materials for 3D rendering.
// Create texture create info.
Texture::CreateInfo textureCreateInfo;
// Set the texture settings.
textureCreateInfo.width = 512;
textureCreateInfo.height = 512;
textureCreateInfo.format = GraphicsFormatR8G8B8A8_UNORM;
// Specify that a cubemap texture is to be created
textureCreateInfo.type = TextureTypeCubeMap;
// Specify render target mode for the cube map texture.
textureCreateInfo.renderTargetMode = RenderTargetModeInternal;
// Adjust filter settings to reduce aliasing
textureCreateInfo.minificationFilter = Sampler::FilterLinear;
textureCreateInfo.magnificationFilter = Sampler::FilterLinear;
// Specify that texture has mipmaps
textureCreateInfo.mipmapMode = Sampler::MipmapModeLinear;
textureCreateInfo.mipmapLevelCount = calculateMipmapLevelCount(textureCreateInfo.width, textureCreateInfo.height);
// Create the texture
TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
// Render to all cubemap faces
renderer->bindFramebuffer(texture->getNativeFramebufferHandle());
renderer->setViewport(ViewportRectangle(0, 0, texture->getWidth(), texture->getHeight()));
for (unsigned int faceIndex = 0; faceIndex < 6; ++faceIndex)
{
// Bind the current side of the texture for rendering.
{
const auto targetImage = getGLTextureImageTarget(texture->getType(), faceIndex);
renderer->framebufferTexture2D(targetImage, Surface::APIAttachmentColor0, texture->getNativeHandle(), 0, 1);
}
// Come up with content for each face; Fill with six shades of gray.
float relativeFace = static_cast<float>(faceIndex) / 5.0f;
renderer->resetClearTarget();
renderer->addClearColor(0, relativeFace, relativeFace, relativeFace, 1.0f);
renderer->clear();
renderer->resetClearTarget();
}
renderer->resetActiveFramebuffer();
// Generate mipmaps for texture. Without this, remaining mipmap level images would have undefined content.
texture->generateMipmaps();

Constructor & Destructor Documentation

◆ Texture() [1/2]

kanzi::Texture::Texture ( Domain domain,
const CreateInfo createInfo,
string_view  name 
)
explicitprotected

Creates texture from CreateInfo.

Texture will be deployed, if createInfo memory type includes Gpu.

Parameters
domainDomain for texture.
createInfoTexture creation parameters.
nameName for texture.

◆ Texture() [2/2]

kanzi::Texture::Texture ( Domain domain,
TextureType  type,
int  glHandle,
bool  takeOwnership,
GraphicsFormat  format,
unsigned int  mipmapLevelCount,
unsigned int  width,
unsigned int  height,
string_view  name 
)
explicitprotected

Creates texture from an existing GL object handle.

Caller must also provide texture format, and size. glHandle should be a valid GL texture object. Optionally, kanzi::Texture can take ownership of the provided GL texture object, in which case destroying kanzi::Texture will also destroy the GL texture object. If ownership is not passed to kanzi::Texture, then GL texture must be deleted after kanzi::Texture. Do not delete GL texture object while kanzi::Texture exists.

Note
Caller should always provide accurate information in format, mipmapLevelCount, width and height.
Parameters
domainDomain for texture.
typeTexture type.
glHandlePre-existing valid GL texture object name.
formatFormat of the texture.
mipmapLevelCountMipmap level count of the texture.
widthWidth of the texture.
heightHeight of the texture.
takeOwnershipShould kanzi::Texture take ownership of provided GL texture object
nameName

Member Function Documentation

◆ create() [1/2]

static TextureSharedPtr kanzi::Texture::create ( Domain domain,
const CreateInfo createInfo,
string_view  name 
)
static

Creates a texture with specified texture creation parameters.

In order to create a texture, you will need a CreateInfo structure that is filled with valid combination of texture creation parameters. You can use CreateInfo, CreateInfo2D, CreateInfoHostCopy2D, CreateInfoNode2DRenderTarget, CreateInfoRenderpassRenderTarget and CreateInfoCubemap constructors to create and initialize a texture creation parameter structure. After calling the constructor you can fine tune texture creation parameters.

You can check that parameters are valid by calling CreateInfo::validate().

If you pass CreateInfo that is not valid, Texture::create() will throw an exception and program execution may will terminate. To avoid exceptions for recoverable errors, use Renderer::adjust() on the create info prior to calling this function.

If createInfo memory type includes Gpu, texture will be deployed.

If createInfo memory type includes Ram, host copy of texture data will be made accessible. Otherwise, texture host copy will not be accessible.

Note
create() takes ownership of images you pass in the create info. You must not delete images that you pass to Texture::create() in createInfos. You must immediately discard any CreateInfo which contains images after first call to create(). The images in createInfo are no longer valid, and such CreateInfo cannot be reused.
Parameters
domainDomain for the texture.
createInfoTexture creation parameters.
nameName for the texture.
Returns
Texture shared pointer.

◆ create() [2/2]

static TextureSharedPtr kanzi::Texture::create ( Domain domain,
TextureType  type,
int  nativeHandle,
bool  takeOwnership,
GraphicsFormat  format,
unsigned int  mipmapLevelCount,
unsigned int  width,
unsigned int  height,
string_view  name 
)
static

Creates texture from a pre-existing GL texture object.

Optionally, kanzi::Texture can take ownership of the provided GL texture object, in which case destroying kanzi::Texture will also destroy the GL texture object. If ownership is not passed to kanzi::Texture, then GL texture must be deleted after kanzi::Texture. Do not delete GL texture object while kanzi::Texture exists.

Note
Caller should always provide accurate information in format, mipmapLevelCount, width and height.
Parameters
domainDomain.
typeTexture type.
nativeHandlePre-existing native handle that identifies a valid GL texture object.
takeOwnershipIf true, texture will take ownership of the native resource (GL texture object).
formatFormat of the texture.
mipmapLevelCountNumber of mipmap levels in the texture.
widthWidth of the texture.
heightHeight of the texture.
nameName.
Returns
Texture shared pointer.

◆ getSampler()

const Sampler& kanzi::Texture::getSampler ( ) const

Returns the Sampler used by the texture.

◆ getType()

TextureType kanzi::Texture::getType ( ) const

Returns type of the texture.

◆ getNativeDeploymentTarget()

NativeDeploymentTarget kanzi::Texture::getNativeDeploymentTarget ( ) const

Returns the native deployment target.

◆ reattachFramebuffer() [1/3]

void kanzi::Texture::reattachFramebuffer ( )

Reattaches the internal framebuffer object.

Only renderbuffers and the color texture within the texture object will be used.

◆ reattachFramebuffer() [2/3]

void kanzi::Texture::reattachFramebuffer ( RenderbufferSharedPtr  colorRenderbuffer)

Reattaches the internal framebuffer object and includes the renderbuffer given as parameter.

The texture does not take ownership of the renderbuffer. The texture must not have an internal color texture.

Parameters
colorRenderbufferRenderbuffer to use as the color target in the framebuffer.

◆ reattachFramebuffer() [3/3]

void kanzi::Texture::reattachFramebuffer ( TextureSharedPtr  depthTexture)

Reattaches the internal framebuffer object and includes the depth texture given as parameter.

The texture does not take ownership of the depth texture. The texture must not have an internal depth render buffer.

Parameters
depthTextureDepth texture to use as the depth target in the framebuffer.

◆ generateMipmaps()

void kanzi::Texture::generateMipmaps ( )

Generates the mipmaps from the base level image.

This reads from Gpu texture data from the base level images, and only updates Gpu texture data of the remaining mipmap images. If texture has host copy data, it remains unchanged.

◆ setData() [1/3]

void kanzi::Texture::setData ( Face  face,
unsigned int  mipmapLevel,
unsigned int  x,
unsigned int  y,
unsigned int  width,
unsigned int  height,
const kanzi::byte data 
)

Sets the texture data for the specified area in a texture.

The texture data is updated to the GPU memory, and to the CPU accessible copy of the texture, if the texture is created with such storage.

Note
The format of the data must match the format of the texture.
Parameters
faceWhich texture face to update.
mipmapLevelWhich mipmap level to update.
x,y,width,heightSpecifies the rectangle to update.
dataTexture data.

◆ setData() [2/3]

void kanzi::Texture::setData ( unsigned int  mipmapLevel,
unsigned int  x,
unsigned int  y,
unsigned int  width,
unsigned int  height,
const kanzi::byte data 
)

Sets the texture data for the specified area in the texture.

The texture data is updated to the GPU memory, and to the CPU accessible copy of the texture, if the texture is created with such storage.

Note
The format of the data must match the format of the texture.
Parameters
mipmapLevelWhich mip level to update.
x,y,width,heightSpecifies the rectangle to update.
dataTexture data.

◆ setData() [3/3]

void kanzi::Texture::setData ( const kanzi::byte data)

Sets the texture data for base level of a non-cubemap texture.

Parameters
dataTexture data.

◆ getNativeHandle()

NativeTextureHandle kanzi::Texture::getNativeHandle ( ) const

Gets native texture handle for the texture.

Returns
Native texture handle.

◆ getNativeFramebufferHandle()

NativeFramebufferHandle kanzi::Texture::getNativeFramebufferHandle ( ) const

Gets native framebuffer handle for the texture.

Note
Only textures created with RenderTargetMode set to RenderTargetInternal will have native framebuffer handle.
Returns
Native framebuffer handle, or 0 if texture was created with rendertarget mode other than RenderTargetInternal.

◆ getDepthStencilFormat()

GraphicsFormat kanzi::Texture::getDepthStencilFormat ( ) const
inline

Returns depth/stencil format of the texture.

Note
Only textures created with RenderTargetMode set to RenderTargetInternal will have depth stencil buffer.
Returns
Graphics format of depth stencil buffer, or GraphicsFormatNone if texture does not have depth stencil buffer.

◆ getDepthStencilRenderbuffer()

RenderbufferSharedPtr kanzi::Texture::getDepthStencilRenderbuffer ( ) const
inline

Returns internal depth/stencil renderbuffer.

Returns
Renderbuffer created internally for the texture, or nullptr.

◆ getHostCopyImage() [1/2]

BitmapImageSharedPtr kanzi::Texture::getHostCopyImage ( Face  face,
unsigned int  slice 
) const

Returns the host-side memory copy of texture data as an image, if available.

Returns as an image the copy of the host-side memory of the texture data, but does not create a copy of that image. Use this function only to retrieve data that was sent to the GPU from the CPU memory. To retrieve data rendered to a texture by the GPU use captureScreenToImage().

Parameters
faceThe texture face for which you want to get the data. For single textures, this value is FaceDefault. For cube-map textures use a valid face for the texture. For example, FacePositiveX, or FaceNegativeZ. If you try to access an invalid texture face, the function throws an exception.
sliceThe texture slice for which you want to get the data. Slice applies to array and 3D textures. Currently this parameter must always be 0. If you access an invalid texture slice, the function throws an exception.
Returns
When you create a texture with the MemoryType property set to GpuAndRam or RamOnly, returns the host-side image uploaded to to the GPU. If you create a texture with the MemoryType property set to GpuOnly, or try to retrieve a composition target texture, returns a null pointer.

◆ getHostCopyImage() [2/2]

BitmapImageSharedPtr kanzi::Texture::getHostCopyImage ( ) const

Returns the host-side memory copy of a non-cubemap texture, if available.

Returns as an image the copy of the host-side memory of the default face of a single texture data, but it does not create a copy of that image.

Returns
When you create a texture with the MemoryType property set to GpuAndRam or RamOnly, returns the host-side image uploaded to to the GPU. If you create a texture with the MemoryType property set to GpuOnly, try to retrieve a composition target texture, or a face from a cube-map texture, returns a null pointer.

◆ getRenderTargetMode()

RenderTargetMode kanzi::Texture::getRenderTargetMode ( ) const
inline

Returns rendertarget mode of the texture.

Returns
Rendertarget mode.
See also
RenderTargetMode.

◆ resize()

void kanzi::Texture::resize ( unsigned  width,
unsigned  height 
)

Changes the size of the texture.

Texture contents are undefined after resizing, user should assume they are destroyed. Specifying size identical to current size will cause resizing not to happen.

NOTE: Internal API and subject to change or removal.

Parameters
widthNew width.
heightNew height.

◆ getWidthDivisor()

unsigned int kanzi::Texture::getWidthDivisor ( ) const
inline

Gets width divisor for automatic sizes.

Returns
Width divisor.

◆ setWidthDivisor()

void kanzi::Texture::setWidthDivisor ( unsigned int  divisor)
inline

Sets the wight divisor.

Parameters
divisorNew width divisor.

◆ hasAutomaticWidth()

bool kanzi::Texture::hasAutomaticWidth ( ) const
inline

Indicates whether width is or should be automatically calculated.

Returns
If width should be automatically calculated true, otherwise false.

◆ getHeightDivisor()

unsigned int kanzi::Texture::getHeightDivisor ( ) const
inline

Gets height divisor for automatic sizes.

Returns
Height divisor.

◆ setHeightDivisor()

void kanzi::Texture::setHeightDivisor ( unsigned int  divisor)
inline

Sets the height divisor.

Parameters
divisorNew height divisor.

◆ hasAutomaticHeight()

bool kanzi::Texture::hasAutomaticHeight ( ) const
inline

Indicates whether height is or should be automatically calculated.

Returns
If height should be automatically calculated true, otherwise false.

◆ createLoadTask()

static ResourceManager::LoadTaskSharedPtr kanzi::Texture::createLoadTask ( string_view  name,
KzbFile kzbFile,
ReadOnlyMemoryFilePtr  file 
)
static

Create a task used to create a Texture from KZB File.

Parameters
nameThe name of the Texture.
kzbFileThe KzbFile containing the texture.
fileThe file containing the Texture data.
Returns
The resource task used to create the Texture.

◆ createGenericFileLoadTask()

static ResourceManager::LoadTaskSharedPtr kanzi::Texture::createGenericFileLoadTask ( string_view  name,
unique_ptr< File file,
Domain domain 
)
static

Create a task used to create a Texture from generic file.

Parameters
nameThe name of the Texture.
fileThe file containing the Texture data.
domainThe application domain.
Returns
The resource task used to create the Texture.

◆ recreate()

void kanzi::Texture::recreate ( CreateInfo createInfo)

Validates the CreateInfo texture descriptor, creates a new texture and swaps it in place.

Parameters
createInfoThe texture descriptor.

◆ reloadOverride()

void kanzi::Texture::reloadOverride ( )
overrideprotectedvirtual

Resource::reloadOverride() implementation.

Reimplemented from kanzi::Resource.

◆ reloadFromKzbOverride()

void kanzi::Texture::reloadFromKzbOverride ( KzbFile kzbFile,
ReadOnlyMemoryFile file,
KzbMemoryParser parser 
)
overrideprotectedvirtual

Resource::reloadFromKzbOverride() implementation.

Reimplemented from kanzi::Resource.

◆ reloadFromFileOverride()

void kanzi::Texture::reloadFromFileOverride ( string_view  filePath)
overrideprotectedvirtual

Resource::reloadFromFileOverride() implementation.

Reimplemented from kanzi::Resource.

◆ getCPUMemoryUsageOverride()

unsigned int kanzi::Texture::getCPUMemoryUsageOverride ( ) const
overrideprotectedvirtual

Resource::getCPUMemoryUsageOverride() implementation.

Reimplemented from kanzi::Resource.

◆ invalidateOverride()

void kanzi::Texture::invalidateOverride ( )
overrideprotectedvirtual

GPUResource::invalidateOverride() implementation.

Reimplemented from kanzi::GPUResource.

◆ isDeployedOverride()

bool kanzi::Texture::isDeployedOverride ( ) const
overrideprotectedvirtual

GpuResource::isDeployed() implementation.

Implements kanzi::GPUResource.

◆ getGPUMemoryUsageOverride()

unsigned int kanzi::Texture::getGPUMemoryUsageOverride ( ) const
overrideprotectedvirtual

GpuResource::getGPUMemoryUsageOverride() implementation.

Reimplemented from kanzi::GPUResource.

◆ attachOverride()

void kanzi::Texture::attachOverride ( Usage  usage,
APIAttachment  apiAttachment,
Face  face,
unsigned int  mipmapLevel 
)
overrideprotectedvirtual

Surface::attachOverride() implementation.

Implements kanzi::Surface.

◆ getFormatOverride()

GraphicsFormat kanzi::Texture::getFormatOverride ( ) const
overrideprotectedvirtual

Surface::getFormatOverride() implementation.

Implements kanzi::Surface.

◆ getFeaturesOverride()

unsigned int kanzi::Texture::getFeaturesOverride ( ) const
overrideprotectedvirtual

Surface::getFeaturesOverride() implementation.

Implements kanzi::Surface.

◆ getRenderTargetSampleCountOverride()

unsigned int kanzi::Texture::getRenderTargetSampleCountOverride ( ) const
overrideprotectedvirtual

◆ getWidthOverride()

unsigned int kanzi::Texture::getWidthOverride ( ) const
overrideprotectedvirtual

Surface::getWidthOverride() implementation.

Implements kanzi::Surface.

◆ getHeightOverride()

unsigned int kanzi::Texture::getHeightOverride ( ) const
overrideprotectedvirtual

Surface::getHeightOverride() implementation.

Implements kanzi::Surface.

◆ getSliceCountOverride()

unsigned int kanzi::Texture::getSliceCountOverride ( ) const
overrideprotectedvirtual

Surface::getSliceCountOverride() implementation.

Implements kanzi::Surface.

◆ getFaceCountOverride()

unsigned int kanzi::Texture::getFaceCountOverride ( ) const
overrideprotectedvirtual

Surface::getFaceCountOverride() implementation.

Implements kanzi::Surface.

◆ getMipmapLevelCountOverride()

unsigned int kanzi::Texture::getMipmapLevelCountOverride ( ) const
overrideprotectedvirtual

◆ makeHostCopyImages()

static vector<BitmapImageSharedPtr> kanzi::Texture::makeHostCopyImages ( const CreateInfo createInfo)
staticprotected

Helper function to allocate host images.

There are three cases:

  1. Texture is created with GpuOnly memory type, empty vector will be returned.
  2. Texture is created with RamOnly or GpuAndRam memory type, and create info contains images. A vector containing those images from create info will be returned.
  3. Texture is created with RamOnly or GpuAndRam memory type, create info did not contain images. Returns a vector that contains newly allocated images.
    Parameters
    createInfoTexture create info.
    Returns
    Vector of images. It will be empty if texture memory type is GpuOnly, otherwise it will have images from createInfo if it has images, and if not, it will return newly allocated images.

◆ makeTexture()

static GLTextureHandle kanzi::Texture::makeTexture ( Renderer renderer,
const CreateInfo createInfo 
)
staticprotected

Helper function to create GL texture object.

Only dummy handle will be created if create info specifies RamOnly texture in memoryType.

Parameters
rendererRenderer.
createInfoTexture create info.
Returns
Texture handle.

◆ makeFramebuffer()

static GLFramebufferHandle kanzi::Texture::makeFramebuffer ( Renderer renderer,
const CreateInfo createInfo 
)
staticprotected

Helper function to create GL framebuffer object.

Only dummy handle will be created if create info specifies RamOnly texture, or if texture rendertarget mode is not RenderTargetModeInternal.

Parameters
rendererRenderer.
createInfoTexture create info.
Returns
Framebuffer handle.

◆ deployImages()

void kanzi::Texture::deployImages ( Renderer renderer,
const vector< BitmapImageSharedPtr > &  images 
)
protected

Helper function to setup GL texture object state and initial data.

Called as part of texture construction. Texture internal variables must already be initialized.

Parameters
imagesImages to deploy.
rendererRenderer.

◆ deployInternalFramebuffers()

void kanzi::Texture::deployInternalFramebuffers ( Renderer renderer,
RenderbufferSharedPtr  colorRenderbuffer,
TextureSharedPtr  depthTexture 
)
protected

Helper function to setup GL framebuffer and renderbuffer state Called as part of texture construction.

Texture internal variables must already be initialized.

Parameters
rendererRenderer.
colorRenderbufferColor renderbuffer not owned by the texture to attach.
depthTextureDepth texture not owned by this texture to attach.

Friends And Related Function Documentation

◆ ResourceManager

friend class ResourceManager
friend

◆ swap

void swap ( Texture texture1,
Texture texture2 
)
friend

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