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/graphics2d/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	CreateInfo3D
	Texture creation parameters for 3D textures. More...

struct	CreateInfoCubemap
	Texture creation parameters for cubemap texture that is initialized from six images. More...

struct	CreateInfoCubemapRenderTarget
	Use Texture::CreateInfoCubemapRenderTarget to create a Cubemap Render Target Texture resource. More...

struct	CreateInfoHostCopy2D
	Texture creation parameters for two dimensional texture that is updated from the CPU. More...

struct	CreateInfoRenderTarget
	Texture creation parameters for texture that can be used as render target for 2D nodes. More...

Public Member Functions
void	connectToFramebufferColor (Framebuffer &framebuffer, size_t attachmentIndex)
	Connects the texture into color attachment of a framebuffer.

void	connectToFramebufferDepthStencil (Framebuffer &framebuffer)
	Connects the texture into a depth attachments of a framebuffer.

void	connectToFramebufferResolveColor (Framebuffer &framebuffer, size_t attachmentIndex)
	Connects the texture into color resolve attachment of a framebuffer.

void	connectToFramebufferResolveDepthStencil (Framebuffer &framebuffer)
	Connects the texture into a resolve depth attachments of a framebuffer.

void	generateMipmaps () const
	Generates the mipmaps from the base level image.

RenderbufferSharedPtr	getColorRenderbuffer () const
	Returns internal color renderbuffer used for rendering, if one exists.

Sampler::CreateInfo	getCurrentSamplerCreateInfo () const
	Gets the current sampler create information.

GraphicsFormat	getDepthStencilFormat () const
	Returns depth/stencil format of the texture.

RenderbufferSharedPtr	getDepthStencilRenderbuffer () const
	Returns internal depth/stencil renderbuffer used for rendering, if one exists.

Framebuffer *	getFramebuffer () const
	Gets the framebuffer used for rendering.

gfx::ImageHandleGuard	getHandle () const
	Gets Kanzi graphics image handle for the texture.

unsigned int	getHeightDivisor () const
	Gets height divisor for automatic sizes.

BitmapImageSharedPtr	getHostCopyImage () const
	Returns the host-side memory copy of a non-cubemap texture, if available.

BitmapImageSharedPtr	getHostCopyImage (Face face, size_t slice) const
	Returns the host-side memory copy of texture data as an image, if available.

NativeDeploymentTarget	getNativeDeploymentTarget () const
	Gets the native deployment target.

size_t	getOverrideSamplerCreateInfoCount () const
	Gets the number of overrides in the sampler create info stack.

const Sampler &	getSampler () const
	Returns the Sampler used by the texture.

gfx::SamplerHandleGuard	getSamplerHandle (Renderer &renderer)
	Gets the current sampler handle guard for the texture.

TextureType	getType () const
	Gets type of the texture.

gfx::ImageUsageFlag	getUsageFlags () const
	Returns texture usage flags.

unsigned int	getWidthDivisor () const
	Gets width divisor for automatic sizes.

bool	hasAutomaticHeight () const
	Indicates whether height is or should be automatically calculated.

bool	hasAutomaticWidth () const
	Indicates whether width is or should be automatically calculated.

bool	isRenderTargetTransient () const
	Indicates whether render target buffers are transient.

void	popOverrideSamplerCreateInfo ()
	Pups the topmost sampler create info into the override stack.

void	pushOverrideSamplerCreateInfo (Sampler::CreateInfo createInfo)
	Pushes an overriding sampler create info into the override stack.

void	reattachFramebuffer ()
	Reattaches the internal framebuffer object.

void	reattachFramebuffer (RenderbufferSharedPtr colorRenderbuffer)
	Reattaches the internal framebuffer object and includes the renderbuffer given as parameter.

void	reattachFramebuffer (TextureSharedPtr depthTexture)
	Reattaches the internal framebuffer object and includes the depth texture given as parameter.

void	recreate (CreateInfo &createInfo)
	Validates the CreateInfo texture descriptor, creates a new texture and swaps it in place.

void	resize (size_t width, size_t height)
	Changes the size of the texture.

void	resolveMSAA (Renderer &renderer) const
	Resolves the internal multisample anti-aliasing renderbuffer to a single sample texture, if necessary.

void	setData (const kanzi::byte *data)
	Sets the texture data for base level of a non-cubemap texture.

void	setData (Face face, size_t mipmapLevel, size_t x, size_t y, size_t width, size_t height, const kanzi::byte *data)
	Sets the texture data for the specified area in a texture.

void	setData (size_t mipmapLevel, size_t x, size_t y, size_t width, size_t height, const kanzi::byte *data)
	Sets the texture data for the specified area in the texture.

void	setHeightDivisor (unsigned int divisor)
	Sets the height divisor.

void	setWidthDivisor (unsigned int divisor)
	Sets the wight divisor.

Public Member Functions inherited from kanzi::Surface
size_t	getFaceCount () const
	Get number of faces. This should be six for cubemaps and one for everything else.

GraphicsFormat	getFormat () const
	Get GraphicsFormat of Surface.

size_t	getHeight () const
	Get height in pixels.

size_t	getMipmapLevelCount () const
	Get number of mipmap levels.

size_t	getRenderTargetSampleCount () const
	Get number of multisample samples for Surface.

size_t	getSliceCount () const
	Get number of slices.

size_t	getWidth () const
	Get width in pixels.

Public Member Functions inherited from kanzi::GPUResource
void	destroy ()
	Destroys a GPU resource.

size_t	getGPUMemoryUsage () const
	Gets the amount of GPU memory used by the resource.

Renderer *	getRenderer () const

void	invalidate ()
	Notify resource that graphics context was lost and all GPU resources are invalid.

bool	isDeployed () const

	~GPUResource () override

Public Member Functions inherited from kanzi::Resource
size_t	getCPUMemoryUsage () const
	Gets the amount of CPU memory used by the resource.

const string &	getName () const
	Gets the resource name.

const string &	getUrl () const
	Gets the resource URL.

bool	isKeepAlive () const
	Tells if the resource has keep alive flag set.

void	reload ()

void	reloadFromFile (string_view filePath)

void	reloadFromKzb (KzbFile &kzbFile, ReadOnlyMemoryFile &file, KzbMemoryParser &parser)

void	setKeepAlive (bool keepAlive)
	Sets the keep alive flag.

void	setUrl (string_view url)
	Sets the resource URL.

	~Resource () override
	Destructor.

Public Member Functions inherited from kanzi::Object
AppliedStyleEntrySharedPtr	applyObjectStyle (kanzi::StyleSharedPtr style)
	Applies a style to an object.

void	applyObjectStyles ()
	Apply all styles for an object node.

Domain *	getDomain () const
	Returns the domain the object belongs to.

const Metaclass *	getDynamicMetaclass () const override
	Returns the metaclass of the dynamic type of the object.

MainLoopScheduler *	getMainLoopScheduler () const
	Returns the MainLoopScheduler instance of the associated Domain.

detail::MessageDispatcher *	getMessageDispatcher () const
	Returns the message dispatcher of the object.

ResourceManager *	getResourceManager () const
	Returns the resource manager of the object.

ScriptingContextSharedPtr	getScriptingContext () const
	Gets the scripting context of the object.

	Object (Domain *domain)

void	setScriptingContext (ScriptingContextSharedPtr context)
	Sets the scripting context of the object.

void	unapplyObjectStyle (AppliedStyleEntrySharedPtr appliedStyleEntry)

void	unapplyObjectStyles ()
	Unapplies and removes all applied styles.

	~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.

virtual	~MetaObject ()

Public Member Functions inherited from kanzi::PropertyObject
void	addDestroyCallback (PropertyObjectDestroyCallback cb)
	Adds a destroy callback that is called when the object is being destroyed.

void	addDestroyCallback (PropertyObjectDestroyCallback cb, const void *owner)
	Adds a destroy callback that is called when the object is being destroyed.

template<typename DataType >
void	addPropertyModifier (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner)
	Adds a property modifier.

template<typename DataType >
void	addPropertyModifierWithoutNotifyingHandlers (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner)
	Adds a property modifier without notifying handlers.

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, AbstractPropertyTypeDescriptor::ValueSourceOwner owner)

template<typename DataType >
void	addPropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource valueSource, PropertyValuePrecedence precedence, void ownerPointer)

PropertyStorageContainer::iterator	beginPropertyStorage ()
	Returns the begin iterator to the internal property storage container.

PropertyStorageContainer::const_iterator	beginPropertyStorage () const
	Returns the begin iterator to the internal property storage container.

void	clearPropertyFlag (AbstractPropertyType propertyType, uint32_t flag)

void	copyLocalValue (const PropertyObject &other, AbstractPropertyType propertyType)
	Copies local value of single property from another object.

void	copyLocalValues (const PropertyObject &other)
	Copies all local values from another object.

PropertyStorageContainer::iterator	endPropertyStorage ()
	Returns the end iterator to the internal property storage container.

PropertyStorageContainer::const_iterator	endPropertyStorage () const
	Returns the end iterator to the internal property storage container.

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.

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.

template<typename DataType >
PropertyType< DataType >::Traits::ReturnType	getProperty (const PropertyType< DataType > &propertyType) const
	Returns the current value of a property type.

template<typename DataType >
PropertyType< DataType >::Traits::ReturnType	getPropertyBase (const PropertyType< DataType > &propertyType) const
	Returns the current value of a property disregarding modifiers.

template<typename DataType >
size_t	getPropertyNotificationHandlerCount (const PropertyType< DataType > &propertyType) const
	Gets number of current notification handlers for given property type.

bool	hasBaseValue (AbstractPropertyType propertyType) const
	Evaluates whether there are any inputs into the property value, disregarding modifiers.

bool	hasLocalValue (AbstractPropertyType propertyType) const
	Evaluates whether there is a local value set for the property.

bool	hasNonClassValue (AbstractPropertyType propertyType) const
	Evaluates whether there is a value of any precedence higher than class default value set for the property.

bool	hasValue (AbstractPropertyType propertyType) const
	Evaluates whether there are any inputs into the property value.

bool	isPropertyFlagSet (AbstractPropertyType propertyType, uint32_t flag) const

virtual void	onPropertyChanged (AbstractPropertyType propertyType, PropertyNotificationReason reason)
	Virtual function to handle property change notifications.

	PropertyObject ()

void	removeDestroyCallback (const void *owner)
	Removes the destroy callbacks that you added with the given owner.

void	removeKzbProperties ()
	Remove all KZB properties.

void	removeKzbProperties (flat_set< AbstractPropertyType > *keepProperties)
	Remove all KZB properties that are not included in a given set.

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.

template<typename DataType >
void	removePropertyModifier (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner)
	Removes a property modifier.

template<typename DataType >
void	removePropertyModifierWithoutNotifyingHandlers (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner)
	Removes a property modifier without notifying handlers.

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.

void	setPropertyFlag (AbstractPropertyType propertyType, uint32_t flag)

void	validatePropertyModifiersAndNotifyHandlers (AbstractPropertyType propertyType)
	Validates property modifiers and notifies handlers.

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.

static TextureSharedPtr	create (Domain *domain, TextureType type, const gfx::NativeTextureHandle &nativeHandle, bool takeOwnership, GraphicsFormat format, unsigned int mipmapLevelCount, unsigned int width, unsigned int height, string_view name)
	Creates texture from a pre-existing image object.

static ResourceManager::LoadTaskSharedPtr	createGenericFileLoadTask (string_view name, unique_ptr< File > file, Domain *domain)
	Create a task used to create a Texture from generic file.

static ResourceManager::LoadTaskSharedPtr	createLoadTask (string_view name, KzbFile *kzbFile, ReadOnlyMemoryFilePtr file)
	Create a task used to create a Texture from KZB File.

static TextureSharedPtr	getDefaultTexture (Domain *domain, gfx::ImageType type)
	Returns the built-in fallback texture for the given type.

Static Public Member Functions inherited from kanzi::Object
static const Metaclass *	getStaticMetaclass ()
	Returns the metaclass of Object class.

static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()
	Default implementation that returns empty editor info.

Static Public Member Functions inherited from kanzi::MetaObject
static const Metaclass *	getStaticMetaclass ()
	Returns the metaclass of Object class.

static PropertyTypeEditorInfoSharedPtr	makeEditorInfo ()
	Default implementation that returns empty editor info.

Protected Member Functions
void	createFramebuffers (Renderer &renderer)
	Create internal framebuffers.

void	destroyOverride () override
	GPUResource::destroyOverride() implementation.

CreateInfo	generateCreateInfo (bool includeImages)
	Generate a create info for the texture based on current properties.

size_t	getCPUMemoryUsageOverride () const override
	Resource::getCPUMemoryUsageOverride() implementation.

size_t	getFaceCountOverride () const override
	Surface::getFaceCountOverride() implementation.

GraphicsFormat	getFormatOverride () const override
	Surface::getFormatOverride() implementation.

size_t	getGPUMemoryUsageOverride () const override
	GpuResource::getGPUMemoryUsageOverride() implementation.

size_t	getHeightOverride () const override
	Surface::getHeightOverride() implementation.

size_t	getMipmapLevelCountOverride () const override
	Surface::getMipmapLevelCountOverride() implementation.

size_t	getRenderTargetSampleCountOverride () const override
	Surface::getRenderTargetSampleCountOverride() implementation.

size_t	getSliceCountOverride () const override
	Surface::getSliceCountOverride() implementation.

size_t	getWidthOverride () const override
	Surface::getWidthOverride() implementation.

void	initialize ()
	Initialize the texture.

void	invalidateOverride () override
	GPUResource::invalidateOverride() implementation.

bool	isDeployedOverride () const override
	GpuResource::isDeployed() implementation.

void	reloadFromFileOverride (string_view filePath) override
	Resource::reloadFromFileOverride() implementation.

void	reloadFromKzbOverride (KzbFile &kzbFile, ReadOnlyMemoryFile &file, KzbMemoryParser &parser) override
	Resource::reloadFromKzbOverride() implementation.

void	reloadOverride () override
	Resource::reloadOverride() implementation.

bool	shouldBeDeployedDuringConstruction () const
	Checks if the texture is deployable during construction.

	Texture (Domain *domain, const CreateInfo &createInfo, string_view name)
	Creates texture from CreateInfo.

	Texture (Domain *domain, TextureType type, const gfx::NativeTextureHandle &nativeHandle, bool takeOwnership, GraphicsFormat format, unsigned int mipmapLevelCount, unsigned int width, unsigned int height, string_view name)
	Creates texture from an existing GL object handle.

Protected Member Functions inherited from kanzi::Surface
	Surface (Domain *domain, string_view name)
	Constructor.

Protected Member Functions inherited from kanzi::GPUResource
	GPUResource (Domain *domain, string_view name="")
	Constructor.

Protected Member Functions inherited from kanzi::Resource
	Resource (Domain *domain, string_view name)
	Constructor.

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::ValueSourceEntry *	acquireLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
	Acquires a local value source entry that is free for the assignment of a value.

AbstractPropertyTypeDescriptor::ModifierStorage *	acquireModifierStorage (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)

AbstractPropertyTypeDescriptor::NotificationStorage *	acquireNotificationStorage (AbstractPropertyTypeDescriptor &descriptor)

PropertyStoragePtr	acquirePropertyStorage (AbstractPropertyTypeDescriptor &descriptor)
	Acquires a property storage.

template<typename DataType >
void	addPropertyModifierBase (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner, bool notify)
	Adds a property modifier entry to the property modifier stack and validates the modifiers.

void	addPropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource valueSource, PropertyValuePrecedence precedence, AbstractPropertyTypeDescriptor::ValueSourceOwner owner)
	Internally adds a property value source.

void	addPropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource valueSource, PropertyValuePrecedence precedence, void ownerPointer)
	Internally adds a property value source.

AbstractPropertyTypeDescriptor::ValueSourceEntry *	constructLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
	Constructs a new local value source entry.

void	copyLocalValue (const AbstractPropertyTypeDescriptor::PropertyStorage &otherPropertyStorage)
	Copy local value from property storage.

AbstractPropertyTypeDescriptor::ModifierStorage *	findModifierStorage (AbstractPropertyTypeDescriptor &descriptor)

AbstractPropertyTypeDescriptor::NotificationStorage *	findNotificationStorage (AbstractPropertyTypeDescriptor &descriptor) const

AbstractPropertyTypeDescriptor::PropertyStorage *	findPropertyStorage (AbstractPropertyTypeDescriptor &descriptor) const
	Gets the property storage for given property type descriptor.

PropertyStoragePtr	findPropertyStoragePtr (AbstractPropertyTypeDescriptor &descriptor) const
	Gets property storage intrusive pointer which you can use to hold a reference until the end of the operation.

AbstractPropertyTypeDescriptor *	findPropertyTypeDescriptorByNameAndDataType (string_view name, PropertyDataType dataType) const
	Finds a property type descriptor by name and data type.

AbstractPropertyTypeDescriptor *	findPropertyTypeDescriptorByQualifiedNameAndDataType (string_view qualifiedName, PropertyDataType dataType) const
	Like findPropertyTypeDescriptorByNameAndDataType, but only searches by matching with qualified names.

AbstractPropertyTypeDescriptor *	findPropertyTypeDescriptorByUnqualifiedNameAndDataType (string_view unqualifiedName, PropertyDataType dataType) const
	Like findPropertyTypeDescriptorByNameAndDataType, but only searches by matching with unqualified names.

AbstractPropertyTypeDescriptor::ValueSource *	getClassValueSource (AbstractPropertyTypeDescriptor &descriptor) const

AbstractPropertyTypeDescriptor::ValueSource *	getFinalValueSource (AbstractPropertyTypeDescriptor &descriptor) const

AbstractPropertyTypeDescriptor::ValueSource *	getNonClassValueSource (AbstractPropertyTypeDescriptor &descriptor) const

AbstractPropertyTypeDescriptor::ValueSource *	getTopValueSource (AbstractPropertyTypeDescriptor &descriptor) const
	Gets the top-level value source for a given property descriptor.

virtual void	notifyPropertyHandlers (PropertyStoragePtr &propertyStorage, PropertyNotificationReason reason)
	Notifies all property handlers on a property storage.

void	onCopy (const PropertyObject &other)

void	removeLocalValue (AbstractPropertyTypeDescriptor &descriptor, PropertyStoragePtr &propertyStorage)
	Removes a local value from the given property storage.

template<typename DataType >
void	removePropertyModifierBase (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner, bool notify)
	Removes a property modifier entry from the property modifier stack and validates the remaining modifiers.

void	removePropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource valueSource, void owner)
	Removes a property value source.

void	validatePropertyModifiers (AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
	Validates property modifiers without notifying handlers.

void	validatePropertyModifiersAndNotifyHandlers (PropertyStoragePtr &propertyStorage)
	Validates property modifiers and notifies handlers.

Static Protected Member Functions
static vector< BitmapImageSharedPtr >	makeHostCopyImages (const CreateInfo &createInfo)
	Helper function to allocate host images.

Protected Attributes
GraphicsFormat	m_depthStencilFormat
	Depth/Stencil format.

size_t	m_faceCount
	Number of texture faces.

GraphicsFormat	m_format
	Format of the texture handle.

FramebufferPtr	m_framebuffer
	Framebuffer necessary for compositing into the texture.

size_t	m_height
	Texture height.

unsigned int	m_heightDivisor
	Divisor for automatic height determination, 0 for no automatic height.

gfx::ImageHandleGuard	m_imageHandle
	Kanzi graphics image handle.

vector< BitmapImageSharedPtr >	m_images
	Copy of texture data, provides host CPU access without reading back from GPU.

MemoryType	m_memoryType
	Memory type for texture.

size_t	m_mipmapLevelCount
	Number of mipmap levels in the texture.

NativeDeploymentTarget	m_nativeDeploymentTarget
	Native memory storage for the texture.

vector< Sampler::CreateInfo >	m_overrideSamplerSettings
	Overriding sampler create info.

size_t	m_rendertargetSampleCount
	Number of implicit multisample samples.

bool	m_renderTargetTransient
	Transient flag for renderbuffers generated for off-screen rendering.

Sampler	m_sampler
	Sampler configuration.

string	m_samplerName
	Name to use with the sampler(s) for this texture.

size_t	m_sliceCount
	Reserved for future use.

TextureType	m_type
	Texture type.

gfx::ImageUsageFlag	m_usageFlags
	Image usage flags.

size_t	m_width
	Texture width.

unsigned int	m_widthDivisor
	Divisor for automatic width determination, 0 for no automatic height.

Protected Attributes inherited from kanzi::Object
AppliedStyleContainer	m_appliedStyles
	Listing of applied styles applied to this object.

Friends
class	GlyphCacheManager

class	ResourceManager

void	swap (Texture &texture1, Texture &texture2)
	Swaps two textures.

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...

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
using	PropertyObjectDestroyCallback
	Callback that a property object calls when it is being destroyed.

using	PropertyStorageConstIterator

using	PropertyStorageContainer

using	PropertyStorageIterator

using	PropertyStoragePtr

using	PropertyStorageReverseIterator

Protected Types inherited from kanzi::Object
typedef vector< AppliedStyleEntrySharedPtr >	AppliedStyleContainer
	Applied style container.

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 CreateInfoRenderTarget.

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.
            BitmapImageUniquePtr image = BitmapImage::createFromMemory(512, 512, GraphicsFormatR8G8B8A8_UNORM, reinterpret_cast<const byte*>(sourceData.get()), "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:

To load texture with ResourceManager:

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, GraphicsFormatR8G8B8A8_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 = GraphicsFormatR8G8B8A8_UNORM;
            createInfo.memoryType = Texture::GpuAndRam;
            createInfo.mipmapMode = Sampler::MipmapModeLinear;
            createInfo.mipmapLevelCount = calculateMipmapLevelCount(createInfo.width, createInfo.height);
            TextureSharedPtr texture = Texture::create(domain, createInfo, "Texture");
            auto width = texture->getWidth();
            auto height = texture->getHeight();
            for (size_t mipmapLevel = 0; mipmapLevel < createInfo.mipmapLevelCount; ++mipmapLevel)
            {
                for (size_t 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::CreateInfoRenderTarget
        // \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::CreateInfoRenderTarget 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.pushCompositionActiveGraphicsOutput(screen->getAllocatedSize());
            screen->render(*renderer);
            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::setCompositionTarget0().
            // \see Renderpass
            // \see Viewport2D
            // \see Scene
            // \see Texture::CreateInfoRenderTarget
            // \see Texture::create()
            ScreenSharedPtr screen = Screen::create(domain, "screen");
            screen->attach();
 
            // Create Viewport2D node.
            Viewport2DSharedPtr viewport = Viewport2D::create(domain, "viewport");
            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::CreateInfoRenderTarget textureCreateInfo(width, height, GraphicsFormatR8G8B8A8_UNORM);
            TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
 
            // Create renderpass prefab.
            RenderPassTemplateSharedPtr clearTemplate = RenderPassTemplate::create(ClearRenderPass::getStaticMetaclass()->getName(), "clear render pass");
            // 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));
            RenderPassTemplateSharedPtr drawTemplate = RenderPassTemplate::create(DrawObjectsRenderPass::getStaticMetaclass()->getName(), "draw render pass");
            RenderPassTemplateSharedPtr rootTemplate = RenderPassTemplate::create(CompositionTargetRenderPass::getStaticMetaclass()->getName(), "composition render pass");
            // 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 = renderer->getCompositionStack();
                screen->setAllocatedSize(Vector2(static_cast<float>(width), static_cast<float>(height)));
                screen->setArrangeTransform(Matrix3x3());
                screen->layout();
                compositionStack.pushCompositionActiveGraphicsOutput(screen->getAllocatedSize());
                screen->render(*renderer);
                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::CreateInfoRenderTarget 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.
            auto& compositionStack = renderer->getCompositionStack();
            compositionStack.pushComposition(*texture);
            renderer->setOrthographicProjection();
 
            // Fill texture with a color
            auto& commandRecorder = renderer->getCommandRecorder();
            optional<ColorRGBA> clearColor = ColorRGBA(0.5f, 0.6f, 0.7f, 1.0f);
            commandRecorder.clearFramebuffer(asSpan(clearColor));
 
            compositionStack.popComposition();

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::CreateInfoRenderTarget 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.
            auto& compositionStack = renderer->getCompositionStack();
            compositionStack.pushComposition(*texture);
            renderer->setOrthographicProjection();
 
            // Fill texture with a color
            auto& commandRecorder = renderer->getCommandRecorder();
            optional<ColorRGBA> clearColor = ColorRGBA(0.5f, 0.6f, 0.7f, 1.0f);
            commandRecorder.clearFramebuffer(asSpan(clearColor));
 
            compositionStack.popComposition();
 
            // 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.usageFlags |= gfx::ImageUsageFlag::Attachment;
 
            // 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.
            auto& compositionStack = renderer->getCompositionStack();
 
            // Storage for framebuffers used for rendering into CTRP faces.
            array<FramebufferPtr, 6u> faceFramebuffers;
 
            for (unsigned int faceIndex = 0; faceIndex < 6; ++faceIndex)
            {
                faceFramebuffers[faceIndex] = Framebuffer::create("face " + to_string(faceIndex));
                auto& framebuffer = *(faceFramebuffers[faceIndex]);
 
                // Prepare the framebuffer for rendering.
                framebuffer.setColorAttachment(0u, texture, faceIndex);
                framebuffer.update(*renderer);
 
                // Push framebuffer into composition stack and apply.
                compositionStack.pushComposition(
                    framebuffer,
                    Vector2(static_cast<float>(texture->getWidth()), static_cast<float>(texture->getHeight())));
                renderer->setOrthographicProjection();
 
                // Come up with content for each face; Fill with six shades of gray.
                float relativeFace = static_cast<float>(faceIndex) / 5.0f;
                auto& commandRecorder = renderer->getCommandRecorder();
                optional<ColorRGBA> clearColor = ColorRGBA(relativeFace, relativeFace, relativeFace, 1.0f);
                commandRecorder.clearFramebuffer(asSpan(clearColor));
 
                compositionStack.popComposition();
            }
 
            // Generate mipmaps for texture. Without this, remaining mipmap level images would have undefined content.
            texture->generateMipmaps();

Since

Kanzi 4.0.0

Removed the deployInternalFramebuffers, getNativeFramebufferHandle, getNativeHandle, getRenderTargetMode, makeTexture and makeTextureHandle functions.
Removed the m_attachedColorRenderbuffer, m_attachedDepthTexture, m_depthStencilRenderbuffer, m_features, m_framebufferHandle, m_msaaRenderbuffer, m_renderTargetMode and m_resolveFramebufferHandle fields.

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

domain	Domain for texture.
createInfo	Texture creation parameters.
name	Name for texture.

◆ Texture() [2/2]

kanzi::Texture::Texture	(	Domain *	domain,
		TextureType	type,
		const gfx::NativeTextureHandle &	nativeHandle,
		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

domain	Domain for texture.
type	Texture type.
nativeHandle	Pre-existing valid GL texture object name.
format	Format of the texture.
mipmapLevelCount	Mipmap level count of the texture.
width	Width of the texture.
height	Height of the texture.
takeOwnership	Indicates whether kanzi::Texture should take ownership of provided GL texture object.
name	Name.

Since: Kanzi 4.0.0 changed the type of mipmapLevelCount, width and height parameters to size_t.

Member Function Documentation

◆ create() [1/2]

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

inlinestatic

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, CreateInfoRenderTarget, CreateInfoCubemap and CreateInfoCubemapRenderTarget 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

domain	Domain for the texture.
createInfo	Texture creation parameters.
name	Name for the texture.

Returns: Texture shared pointer.

◆ create() [2/2]

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

inlinestatic

Creates texture from a pre-existing image object.

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

Note: Caller should always provide accurate information in format, mipmapLevelCount, width and height.

Parameters

domain	Domain.
type	Texture type.
nativeHandle	NativeTextureHandle element which is containing information for pre-existing image object.
takeOwnership	If true, texture will take ownership of the native resource (image object).
format	Format of the texture.
mipmapLevelCount	Number of mipmap levels in the texture.
width	Width of the texture.
height	Height of the texture.
name	Name.

Returns: Texture shared pointer.

Since: Kanzi 4.0.0 changed the type of mipmapLevelCount, width and height parameters to size_t.

◆ getDefaultTexture()

static TextureSharedPtr kanzi::Texture::getDefaultTexture	(	Domain *	domain,
		gfx::ImageType	type )

static

Returns the built-in fallback texture for the given type.

Parameters

domain	Domain.
type	Image type.

Returns: Default texture shared pointer.

Since: Kanzi 4.1.0

◆ getSampler()

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

inline

Returns the Sampler used by the texture.

Returns: Reference to sampler.

◆ getCurrentSamplerCreateInfo()

Sampler::CreateInfo kanzi::Texture::getCurrentSamplerCreateInfo ( ) const

inline

Gets the current sampler create information.

This is either the current topmost overriding info or the one from the base sampler.

Returns: Current sampler create info.

Since: Kanzi 4.0.0

◆ pushOverrideSamplerCreateInfo()

void kanzi::Texture::pushOverrideSamplerCreateInfo ( Sampler::CreateInfo createInfo )

inline

Pushes an overriding sampler create info into the override stack.

Parameters

createInfo Overriding sampler create info.

Since: Kanzi 4.0.0

◆ popOverrideSamplerCreateInfo()

void kanzi::Texture::popOverrideSamplerCreateInfo ( )

inline

Pups the topmost sampler create info into the override stack.

Since: Kanzi 4.0.0

◆ getOverrideSamplerCreateInfoCount()

size_t kanzi::Texture::getOverrideSamplerCreateInfoCount ( ) const

inline

Gets the number of overrides in the sampler create info stack.

Returns: Number of sampler override settings.

Since: Kanzi 4.0.0

◆ getSamplerHandle()

gfx::SamplerHandleGuard kanzi::Texture::getSamplerHandle ( Renderer & renderer )

Gets the current sampler handle guard for the texture.

This is either the default sampler for the texture, or an overridden sampler from the renderer.

Returns: Sampler handle.

Since: Kanzi 4.0.0

◆ getType()

TextureType kanzi::Texture::getType ( ) const

inline

Gets type of the texture.

Returns: Texture type.

◆ getNativeDeploymentTarget()

NativeDeploymentTarget kanzi::Texture::getNativeDeploymentTarget ( ) const

inline

Gets the native deployment target.

Returns: 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

colorRenderbuffer Renderbuffer 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

depthTexture Depth texture to use as the depth target in the framebuffer.

◆ generateMipmaps()

void kanzi::Texture::generateMipmaps ( ) const

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.

Since: Kanzi 4.0.0 this function is now const.

◆ setData() [1/3]

void kanzi::Texture::setData	(	Face	face,
		size_t	mipmapLevel,
		size_t	x,
		size_t	y,
		size_t	width,
		size_t	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

face	Which texture face to update.
mipmapLevel	Which mipmap level to update.
x	Specifies the x-coordinate of the texture.
y	Specifies the y-coordinate of the texture.
width	Specifies the width of the texture.
height	Specifies the height of the texture.
data	Texture data.

Since: Kanzi 4.0.0 changed the type of the mipmapLevel, x, y, width, and height parameters to size_t.

◆ setData() [2/3]

void kanzi::Texture::setData	(	size_t	mipmapLevel,
		size_t	x,
		size_t	y,
		size_t	width,
		size_t	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

mipmapLevel	Which mipmap level to update.
x	Specifies the x-coordinate of the texture.
y	Specifies the y-coordinate of the texture.
width	Specifies the width of the texture.
height	Specifies the height of the texture.
data	Texture data.

Since: Kanzi 4.0.0 changed the type of the mipmapLevel, x, y, width, and height parameters to size_t.

◆ setData() [3/3]

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

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

Parameters

data	Texture data.

◆ getHandle()

gfx::ImageHandleGuard kanzi::Texture::getHandle ( ) const

Gets Kanzi graphics image handle for the texture.

Returns: Kanzi graphics image handle.

Since: Kanzi 4.0.0

◆ getDepthStencilFormat()

GraphicsFormat kanzi::Texture::getDepthStencilFormat ( ) const

inline

Returns depth/stencil format of the texture.

Returns: Graphics format of depth stencil buffer, or GraphicsFormatNone if texture does not have depth stencil buffer.

◆ getFramebuffer()

Framebuffer * kanzi::Texture::getFramebuffer ( ) const

inline

Gets the framebuffer used for rendering.

This function is intended for inspecting the internal Texture Framebuffer state.

Returns: Pointer to the framebuffer or nullptr.

Since: Kanzi 4.0.0

◆ getColorRenderbuffer()

RenderbufferSharedPtr kanzi::Texture::getColorRenderbuffer ( ) const

inline

Returns internal color renderbuffer used for rendering, if one exists.

Returns: Color renderbuffer created internally for the texture, or nullptr.

Since: Kanzi 4.0.0

◆ getDepthStencilRenderbuffer()

RenderbufferSharedPtr kanzi::Texture::getDepthStencilRenderbuffer ( ) const

inline

Returns internal depth/stencil renderbuffer used for rendering, if one exists.

Returns: Renderbuffer created internally for the texture, or nullptr.

◆ connectToFramebufferColor()

void kanzi::Texture::connectToFramebufferColor	(	Framebuffer &	framebuffer,
		size_t	attachmentIndex )

Connects the texture into color attachment of a framebuffer.

Use this function if using this texture as a part of combined rendering using multiple textures. The texture must be a color texture to support the connection. For connecting to resolve attachment, use connectToFramebufferResolveColor().

Parameters

framebuffer	Target framebuffer.
attachmentIndex	Target attachment index.

Since: Kanzi 4.0.0

◆ connectToFramebufferResolveColor()

void kanzi::Texture::connectToFramebufferResolveColor	(	Framebuffer &	framebuffer,
		size_t	attachmentIndex )

Connects the texture into color resolve attachment of a framebuffer.

Use this function if you are using this texture as a part of combined rendering using multiple textures. The texture must be a color texture to support the connection. If this texture is not a suitable resolve target, the resolve target in the framebuffer is cleared. For connecting to draw attachment, use connectToFramebufferColor().

Parameters

framebuffer	Target framebuffer.
attachmentIndex	Target attachment index.

Since: Kanzi 4.0.0

◆ connectToFramebufferDepthStencil()

void kanzi::Texture::connectToFramebufferDepthStencil ( Framebuffer & framebuffer )

Connects the texture into a depth attachments of a framebuffer.

Use this function if using this texture as a part of combined rendering using multiple textures. The texture must have a depth/stencil renderbuffer or be a depth texture to support the connection. For connecting to resolve attachment, use connectToFramebufferResolveDepthStencil().

Parameters

framebuffer Target framebuffer.

Since: Kanzi 4.0.0

◆ connectToFramebufferResolveDepthStencil()

void kanzi::Texture::connectToFramebufferResolveDepthStencil ( Framebuffer & framebuffer )

Connects the texture into a resolve depth attachments of a framebuffer.

Use this function if you are using this texture as a part of combined rendering using multiple textures. The texture must be a depth texture to support the connection. If this texture is not a suitable resolve target, the resolve target in the framebuffer is cleared. For connecting to draw attachment, use connectToFramebufferDepthStencil().

Parameters

framebuffer Target framebuffer.

Since: Kanzi 4.0.0

◆ getHostCopyImage() [1/2]

BitmapImageSharedPtr kanzi::Texture::getHostCopyImage	(	Face	face,
		size_t	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

face	The texture face for which you want to get the data. For single textures, this value is FaceDefault. For cubemap 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.
slice	The 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.

Since: Kanzi 4.0.0 changed the type of the slice parameter to size_t.

◆ 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 cubemap texture, returns a null pointer.

◆ getUsageFlags()

gfx::ImageUsageFlag kanzi::Texture::getUsageFlags ( ) const

inline

Returns texture usage flags.

Returns: Usage flags.

See also: gfx::ImageUsageFlag.

Since: Kanzi 4.0.0

◆ resize()

void kanzi::Texture::resize	(	size_t	width,
		size_t	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

width	New width.
height	New height.

Since: Kanzi 4.0.0 changed the type of the width and height parameters to size_t.

◆ 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

divisor New 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

divisor New 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.

◆ isRenderTargetTransient()

bool kanzi::Texture::isRenderTargetTransient ( ) const

inline

Indicates whether render target buffers are transient.

If this flag is set, any renderbuffers associated with depth, stencil or multisampling should be considered lost information at the end of render pass.

Returns: Render target transient flag.

Since: Kanzi 4.0.0

◆ 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

name	The name of the Texture.
kzbFile	The KzbFile containing the texture.
file	The 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

name	The name of the Texture.
file	The file containing the Texture data.
domain	The 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

createInfo The texture descriptor.

◆ resolveMSAA()

void kanzi::Texture::resolveMSAA ( Renderer & renderer ) const

Resolves the internal multisample anti-aliasing renderbuffer to a single sample texture, if necessary.

This is required after the rendering is complete if more than one sample is requested. Kanzi blits the contents of the internal MSAA renderbuffer into the texture that can be sampled. If the texture does not have multisampling enabled, this function is a NOP.

Parameters

renderer Renderer.

Since: Kanzi 3.9.7; Kanzi 4.0.0 this function is now const.

◆ reloadOverride()

void kanzi::Texture::reloadOverride ( )

overrideprotectedvirtual

Resource::reloadOverride() implementation.

Reimplemented from kanzi::Resource.

◆ reloadFromKzbOverride()

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

staticprotected

Helper function to allocate host images.

There are three cases:

Texture is created with GpuOnly memory type, empty vector will be returned.
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.
Texture is created with RamOnly or GpuAndRam memory type, create info did not contain images. Returns a vector that contains newly allocated images.
Parameters

createInfo Texture 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.

◆ initialize()

void kanzi::Texture::initialize ( )

protected

Initialize the texture.

Part of the texture creation and storing of the settings happens in the constructor. This function performs parts of the initialization that do not depend on data in the CreateInfo structure. Kanzi calls this function after the object creation, so it can access shared_from_this() if necessary.

Since: Kanzi 4.0.0

◆ generateCreateInfo()

CreateInfo kanzi::Texture::generateCreateInfo ( bool includeImages )

protected

Generate a create info for the texture based on current properties.

Parameters

includeImages Should the CPU images be moved into the create info structure.

Returns: The CreateInfo struct.

Since: Kanzi 4.0.0

◆ createFramebuffers()

void kanzi::Texture::createFramebuffers ( Renderer & renderer )

protected

Create internal framebuffers.

Creates both the framebuffer for rendering and the framebuffer for resolving multisamples if necessary. This function needs to be ran if the texture has been resized. The internal parameters must have been updated before calling.

Parameters

renderer Renderer to use for framebuffer creation.

Since: Kanzi 4.0.0

◆ shouldBeDeployedDuringConstruction()

bool kanzi::Texture::shouldBeDeployedDuringConstruction ( ) const

inlineprotected

Checks if the texture is deployable during construction.

This indicates if the texture should be deployed to the GPU and is not an external texture.

Returns: If the texture's contents should be deployed during construction true, false otherwise.

Since: Kanzi 4.0.0

Friends And Related Symbol Documentation

◆ ResourceManager

friend class ResourceManager

friend

◆ GlyphCacheManager

friend class GlyphCacheManager

friend

◆ swap

void swap	(	Texture &	texture1,
		Texture &	texture2 )

friend

Swaps two textures.

Parameters

texture1	Left-hand-side operand.
texture2	Right-hand-side operand.

This framebuffer is used both for rendering and resolving multisampling.

Since: Kanzi 4.0.0

◆ m_format

GraphicsFormat kanzi::Texture::m_format

protected

Format of the texture handle.

This is either a color format or a depth format. Stencil format should never be used.

◆ m_width

size_t kanzi::Texture::m_width

protected

Texture width.

Since: Kanzi 4.0.0 changed the type to size_t.

◆ m_height

size_t kanzi::Texture::m_height

protected

Texture height.

Since: Kanzi 4.0.0 changed the type to size_t.

◆ m_widthDivisor

unsigned int kanzi::Texture::m_widthDivisor

protected

Divisor for automatic width determination, 0 for no automatic height.

◆ m_heightDivisor

unsigned int kanzi::Texture::m_heightDivisor

protected

Divisor for automatic height determination, 0 for no automatic height.

◆ m_sliceCount

size_t kanzi::Texture::m_sliceCount

protected

Reserved for future use.

Always set to 1. Number of texture slices.

Since: Kanzi 4.0.0 changed the type to size_t.

◆ m_faceCount

size_t kanzi::Texture::m_faceCount

protected

Number of texture faces.

1 for 2D textures, and 6 for cubemap textures

Since: Kanzi 4.0.0 changed the type to size_t.

◆ m_mipmapLevelCount

size_t kanzi::Texture::m_mipmapLevelCount

protected

Number of mipmap levels in the texture.

Since: Kanzi 4.0.0 changed the type to size_t.

◆ m_samplerName

string kanzi::Texture::m_samplerName

protected

Name to use with the sampler(s) for this texture.

Since: Kanzi 4.0.0

◆ m_sampler

Sampler kanzi::Texture::m_sampler

protected

Sampler configuration.

◆ m_images

vector<BitmapImageSharedPtr> kanzi::Texture::m_images

protected

Copy of texture data, provides host CPU access without reading back from GPU.

◆ m_usageFlags

gfx::ImageUsageFlag kanzi::Texture::m_usageFlags

protected

Image usage flags.

Determines the texture's intended usage. Copied over from the create info.

Since: Kanzi 4.0.0

◆ m_memoryType

MemoryType kanzi::Texture::m_memoryType

protected

Memory type for texture.

◆ m_nativeDeploymentTarget

NativeDeploymentTarget kanzi::Texture::m_nativeDeploymentTarget

protected

Native memory storage for the texture.

◆ m_type

TextureType kanzi::Texture::m_type

protected

Texture type.

◆ m_rendertargetSampleCount

size_t kanzi::Texture::m_rendertargetSampleCount

protected

Number of implicit multisample samples.

Since: Kanzi 4.0.0 changed the type to size_t.

◆ m_renderTargetTransient

bool kanzi::Texture::m_renderTargetTransient

protected

Transient flag for renderbuffers generated for off-screen rendering.

If this flag is set and the texture is used as a composition target, renderbuffers will not be preserved for successive render passes.

Since: Kanzi 4.0.0

◆ m_depthStencilFormat

GraphicsFormat kanzi::Texture::m_depthStencilFormat

protected

Depth/Stencil format.

This is depth/stencil format of the additional render buffer in addition to the format in m_format. Both format and depth/stencil format cannot have depth.

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

kanzi/core.ui/graphics2d/texture.hpp

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Examples - Creating Textures with Kanzi C++ API

Examples - Updating texture data with Kanzi C++ API

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

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

Constructor & Destructor Documentation

◆ Texture() [1/2]

◆ Texture() [2/2]

Member Function Documentation

◆ create() [1/2]

◆ create() [2/2]

◆ getDefaultTexture()

◆ getSampler()

◆ getCurrentSamplerCreateInfo()

◆ pushOverrideSamplerCreateInfo()

◆ popOverrideSamplerCreateInfo()

◆ getOverrideSamplerCreateInfoCount()

◆ getSamplerHandle()

◆ getType()

◆ getNativeDeploymentTarget()

◆ reattachFramebuffer() [1/3]

◆ reattachFramebuffer() [2/3]

◆ reattachFramebuffer() [3/3]

◆ generateMipmaps()

◆ setData() [1/3]

◆ setData() [2/3]

◆ setData() [3/3]

◆ getHandle()

◆ getDepthStencilFormat()

◆ getFramebuffer()

◆ getColorRenderbuffer()

◆ getDepthStencilRenderbuffer()

◆ connectToFramebufferColor()

◆ connectToFramebufferResolveColor()

◆ connectToFramebufferDepthStencil()

◆ connectToFramebufferResolveDepthStencil()

◆ getHostCopyImage() [1/2]

◆ getHostCopyImage() [2/2]

◆ getUsageFlags()

◆ resize()

◆ getWidthDivisor()

◆ setWidthDivisor()

◆ hasAutomaticWidth()

◆ getHeightDivisor()

◆ setHeightDivisor()

◆ hasAutomaticHeight()

◆ isRenderTargetTransient()

◆ createLoadTask()

◆ createGenericFileLoadTask()

◆ recreate()

◆ resolveMSAA()

◆ reloadOverride()

◆ reloadFromKzbOverride()

◆ reloadFromFileOverride()

◆ getCPUMemoryUsageOverride()

◆ invalidateOverride()

◆ destroyOverride()

◆ isDeployedOverride()

◆ getGPUMemoryUsageOverride()

◆ getFormatOverride()

◆ getRenderTargetSampleCountOverride()

◆ getWidthOverride()

◆ getHeightOverride()

◆ getSliceCountOverride()

◆ getFaceCountOverride()

◆ getMipmapLevelCountOverride()

◆ makeHostCopyImages()

◆ initialize()

◆ generateCreateInfo()

◆ createFramebuffers()

◆ shouldBeDeployedDuringConstruction()

Friends And Related Symbol Documentation