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 Sampler &	getSampler () 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	resolveMSAA (Renderer &renderer)
	Resolves the internal multisample anti-aliasing renderbuffer to a single sample texture, if necessary. 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
void	destroy ()
	Destroys a GPU resource. More...

unsigned int	getGPUMemoryUsage () const

Renderer *	getRenderer () 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...

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

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

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

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

ResourceManager *	getResourceManager () 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	addPropertyModifierWithoutNotifyingHandlers (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::ModifierCallback callback, void *owner)
	Adds a property modifier without notifying handlers. More...

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)

KZ_DEPRECATED void	validatePropertyModifiers (AbstractPropertyType propertyType)
	Validates property modifiers and notifies handlers. More...

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

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 Metaclass *	getStaticMetaclass ()
	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 Metaclass *	getStaticMetaclass ()
	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...

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

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

AbstractPropertyTypeDescriptor::NotificationStorage *	acquireNotificationStorage (AbstractPropertyTypeDescriptor &descriptor)

PropertyStoragePtr	acquirePropertyStorage (AbstractPropertyTypeDescriptor &descriptor)

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

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::ValueSourceEntry *	constructLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)

PropertyStoragePtr	constructPropertyStorage (AbstractPropertyTypeDescriptor &descriptor)

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

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

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

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

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

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

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

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	validatePropertyModifiers (PropertyStoragePtr &propertyStorage)
	Validates property modifiers without notifying handlers. More...

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

Static Protected Member Functions
static GLFramebufferHandle	makeFramebuffer (Renderer *renderer, const CreateInfo &createInfo)
	Helper function to create GL framebuffer object. More...

static vector< BitmapImageSharedPtr >	makeHostCopyImages (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< PropertyStoragePtr >	PropertyStorageContainer

typedef PropertyStorageContainer::iterator	PropertyStorageIterator

typedef intrusive_ptr< AbstractPropertyTypeDescriptor::PropertyStorage >	PropertyStoragePtr

typedef PropertyStorageContainer::reverse_iterator	PropertyStorageReverseIterator

Protected Types inherited from kanzi::Object
typedef vector< AppliedStyleEntrySharedPtr >	AppliedStyleContainer
	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.
            BitmapImageUniquePtr image = BitmapImage::createFromMemory(512, 512, GraphicsFormatR8G8B8A8_UNORM, 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:

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.
            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::CreateInfoRenderpassRenderTarget 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 = 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

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.

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

domain	Domain for texture.
type	Texture type.
glHandle	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	Should kanzi::Texture take ownership of provided GL texture object
name	Name

Member Function Documentation

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

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

Returns: Texture shared pointer.

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

domain	Domain.
type	Texture type.
nativeHandle	Pre-existing native handle that identifies a valid GL texture object.
takeOwnership	If true, texture will take ownership of the native resource (GL texture 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.

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

Returns the Sampler used by the texture.

TextureType kanzi::Texture::getType ( ) const

Returns type of the texture.

NativeDeploymentTarget kanzi::Texture::getNativeDeploymentTarget ( ) const

Returns the native deployment target.

void kanzi::Texture::reattachFramebuffer ( )

Reattaches the internal framebuffer object.

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

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.

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.

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.

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

face	Which texture face to update.
mipmapLevel	Which mipmap level to update.
x,y,width,height	Specifies the rectangle to update.
data	Texture data.

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

mipmapLevel	Which mip level to update.
x,y,width,height	Specifies the rectangle to update.
data	Texture data.

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

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

Parameters

data	Texture data.

NativeTextureHandle kanzi::Texture::getNativeHandle ( ) const

Gets native texture handle for the texture.

Returns: Native texture handle.

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.

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.

RenderbufferSharedPtr kanzi::Texture::getDepthStencilRenderbuffer ( ) const

inline

Returns internal depth/stencil renderbuffer.

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

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

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

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.

RenderTargetMode kanzi::Texture::getRenderTargetMode ( ) const

inline

Returns rendertarget mode of the texture.

Returns: Rendertarget mode.

See also: RenderTargetMode.

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

width	New width.
height	New height.

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

inline

Gets width divisor for automatic sizes.

Returns: Width divisor.

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

inline

Sets the wight divisor.

Parameters

divisor New width divisor.

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.

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

inline

Gets height divisor for automatic sizes.

Returns: Height divisor.

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

inline

Sets the height divisor.

Parameters

divisor New height divisor.

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.

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.

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.

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.

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

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 and the target device does not support implicit MSAA. In this case, Kanzi uses the internal renderbuffer.

Parameters

renderer Renderer.

Since: Kanzi 3.9.7

void kanzi::Texture::reloadOverride ( )

overrideprotectedvirtual

Resource::reloadOverride() implementation.

Reimplemented from kanzi::Resource.

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

overrideprotectedvirtual

Resource::reloadFromKzbOverride() implementation.

Reimplemented from kanzi::Resource.

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

overrideprotectedvirtual

Resource::reloadFromFileOverride() implementation.

Reimplemented from kanzi::Resource.

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

overrideprotectedvirtual

Resource::getCPUMemoryUsageOverride() implementation.

Reimplemented from kanzi::Resource.

void kanzi::Texture::invalidateOverride ( )

overrideprotectedvirtual

GPUResource::invalidateOverride() implementation.

Reimplemented from kanzi::GPUResource.

void kanzi::Texture::destroyOverride ( )

overrideprotectedvirtual

GPUResource::destroyOverride() implementation.

Reimplemented from kanzi::GPUResource.

bool kanzi::Texture::isDeployedOverride ( ) const

overrideprotectedvirtual

GpuResource::isDeployed() implementation.

Implements kanzi::GPUResource.

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

overrideprotectedvirtual

GpuResource::getGPUMemoryUsageOverride() implementation.

Reimplemented from kanzi::GPUResource.

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

overrideprotectedvirtual

Surface::attachOverride() implementation.

Implements kanzi::Surface.

GraphicsFormat kanzi::Texture::getFormatOverride ( ) const

overrideprotectedvirtual

Surface::getFormatOverride() implementation.

Implements kanzi::Surface.

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

overrideprotectedvirtual

Surface::getFeaturesOverride() implementation.

Implements kanzi::Surface.

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

overrideprotectedvirtual

Surface::getRenderTargetSampleCountOverride() implementation.

Implements kanzi::Surface.

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

overrideprotectedvirtual

Surface::getWidthOverride() implementation.

Implements kanzi::Surface.

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

overrideprotectedvirtual

Surface::getHeightOverride() implementation.

Implements kanzi::Surface.

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

overrideprotectedvirtual

Surface::getSliceCountOverride() implementation.

Implements kanzi::Surface.

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

overrideprotectedvirtual

Surface::getFaceCountOverride() implementation.

Implements kanzi::Surface.

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

overrideprotectedvirtual

Surface::getMipmapLevelCountOverride() implementation.

Implements kanzi::Surface.

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

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.

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

renderer	Renderer.
createInfo	Texture create info.

Returns: Texture handle.

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

renderer	Renderer.
createInfo	Texture create info.

Returns: Framebuffer handle.

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

images	Images to deploy.
renderer	Renderer.

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

renderer	Renderer.
colorRenderbuffer	Color renderbuffer not owned by the texture to attach.
depthTexture	Depth texture not owned by this texture to attach.

Friends And Related Function Documentation

friend class ResourceManager

friend

void swap	(	Texture &	texture1,
		Texture &	texture2
	)

friend

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

kanzi/core.ui/platform/graphics_backend/gl/texture.hpp

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

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

Member Function Documentation

Friends And Related Function Documentation