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

Inheritance diagram for kanzi::Texture:

Public Types
enum	Type { TypeTwoDimensional, TypeTwoDimensionalArray, TypeTwoDimensionalMultisample, TypeTwoDimensionalMultisampleArray, TypeThreeDimensional, TypeCubeMap, TypeCubeMapArray, TypeExternal, TypeCount, TypeInvalid }
	Texture type. More...

enum	RenderTargetMode { RenderTargetModeNone, RenderTargetModeInternal, RenderTargetModeExternal }
	RenderTarget mode for Texture. More...

enum	Status { StatusInvalidType, StatusTypeNotSupported, StatusInvalidRenderTargetMode, StatusInvalidImageCount, StatusMissingImages, StatusImageMissingMipmaps, StatusInvalidImageSize, StatusInvalidMinimumSize, StatusInvalidMaximumSize, StatusInvalidMipmapSize, StatusUnsupportedGraphicsFormat, StatusUnsupportedTextureFilter, StatusInvalidFeatures, StatusUnsupportedMultisampleFilter, StatusUnsupportedMultisampleMipmaps, StatusUnsupportedMultisampleSamples, StatusUnsupportedInternalRenderTargetSampleCount, StatusUnsupportedSampleCount, StatusImageFormatMismatch, StatusImageIncompatibleWithDevice, StatusUnsupportedDepthComparisonMode, StatusValid }
	Status tells if texture creation parameters can be used to create a texture. More...

Public Types inherited from kanzi::Surface
enum	Usage { UsageRenderTarget, UsageMultisampleResolveBlitDestination }

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
typedef intrusive_ptr< AbstractPropertyTypeDescriptor::PropertyStorage >	PropertyStoragePtr

typedef vector< PropertyStoragePtr >	PropertyStorageContainer

typedef PropertyStorageContainer::iterator	PropertyStorageIterator

typedef PropertyStorageContainer::const_iterator	PropertyStorageConstIterator

typedef PropertyStorageContainer::reverse_iterator	PropertyStorageReverseIterator

Public Member Functions
const Sampler &	getSampler () const
	Returns the Sampler used by the texture. More...

Type	getType () const
	Returns type of the texture. More...

NativeDeploymentTarget	getNativeDeploymentTarget () const
	Returns the native deployment target. 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	generateMipmaps ()
	Generates the mipmaps from the base level image. 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...

unsigned int	getNativeHandle () const
	Gets native texture handle for the texture. More...

unsigned int	getNativeFramebufferHandle () const
	Gets native framebuffer handle for the texture. More...

GraphicsFormat	getDepthStencilFormat () const
	Returns depthStencil format of the texture. 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...

RenderTargetMode	getRenderTargetMode () const
	Returns rendertarget mode of the texture. More...

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

bool	hasAutomaticWidth () const
	Tell if width is or should be automatically calculated. More...

bool	hasAutomaticHeight () const
	Tell if height is or should be automatically calculated. More...

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

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

	CreateInfo ()
	Default constructor for texture create info. More...

Status	validate (const Renderer &renderer) const
	Perform validation of texture creation parameters. More...

Status	adjust (const Renderer &renderer, string_view name)
	Validates and applies adjustments to some texture creation parameters in case of avoidable error conditions. More...

void	updateShapeAndFormatFromImages ()
	Use updateShapeAndFormatFromImages() to fill in format, width, height from images. More...

	CreateInfo2D (BitmapImageUniquePtr image)
	CreateInfo2D constructor for texture creation parameters, for creating a two dimensional texture that is initialized from an image. More...

	CreateInfo2D (Sampler::MipmapMode mipmaps, BitmapImageUniquePtr image)
	CreateInfo2D constructor that also takes in mipmap mode. More...

	CreateInfo2D (unsigned int width, unsigned int height, GraphicsFormat format)
	CreateInfo2D constructor for texture creation parameters, for creating a two dimensional texture with specified format and size. More...

	CreateInfoHostCopy2D (unsigned int width, unsigned int height, GraphicsFormat format)
	Constructor for CreateInfoHostCopy2D. More...

	CreateInfoNode2DRenderTarget (unsigned int width, unsigned int height, GraphicsFormat format)
	Constructor for CreateInfoNode2DRenderTarget. More...

	CreateInfoRenderpassRenderTarget (unsigned int width, unsigned int height, GraphicsFormat format)
	Constructor for CreateInfoRenderpassRenderTarget - non-multisample version. More...

	CreateInfoRenderpassRenderTarget (Renderer *renderer, unsigned int sampleCount, unsigned int width, unsigned int height, GraphicsFormat format)
	Constructor for CreateInfoRenderpassRenderTarget - multisample version. More...

	CreateInfoCubemap (BitmapImageVector images)
	CreateInfoCubemap constructor for texture creation parameters, for creating a cube map texture that is initialized from six images. More...

	CreateInfoCubemap (Sampler::MipmapMode mipmapMode, BitmapImageVector images)
	CreateInfoCubemap constructor that also takes in mipmap mode. More...

Public Member Functions inherited from kanzi::Surface
void	attach (Usage usage, APIAttachment apiAttachment, Face face, unsigned int mipmapLevel)
	Attach surface to framebuffer. More...

GraphicsFormat	getFormat () const
	Get GraphicsFormat of Surface. More...

unsigned int	getFeatures () const
	Get features for Surface. More...

unsigned int	getRenderTargetSampleCount () const
	Get number of multisample samples for Surface. More...

unsigned int	getWidth () const
	Get width in pixels. More...

unsigned int	getHeight () const
	Get height in pixels. More...

unsigned int	getSliceCount () const
	Get number of slices. More...

unsigned int	getFaceCount () const
	Get number of faces. This should be six for cubemaps and one for everything else. More...

unsigned int	getMipmapLevelCount () const
	Get number of mipmap levels. More...

Public Member Functions inherited from kanzi::GPUResource
virtual	~GPUResource () KZ_OVERRIDE

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

unsigned int	getGPUMemoryUsage () const

Renderer *	getRenderer () const

bool	isDeployed () const

Public Member Functions inherited from kanzi::Resource
KzcMemoryManager *	getMemoryManager () const

	Resource (Domain *domain, string_view name)

virtual	~Resource ()

virtual void	loadFromKZB (const ResourceLoaderThreadContext threadContext, KzcInputStream inputStream, const KzuBinaryFileInfo *file)
	Function for loading the resource from .KZB. More...

virtual void	unloadOverride ()
	Unload function for resource. Releases all CPU memory taken by the resource except the resource loader. More...

virtual unsigned int	getCPUMemoryUsage () const
	Function for getting the memory usage of a resource. More...

void	setKZB (const KzuBinaryDirectory *binaryDirectory, string_view path)
	Set the binary directory and path of the resource. More...

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

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

void	setUrl (string_view url)
	Sets the resource URL. More...

void	setNotLoaded ()

bool	isFromKZB () const

void	reload ()

void	reloadFromKzb (KzcInputStream inputStream, const KzuBinaryFileInfo file)

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

void	reloadFromFile (string_view filePath)

void	load ()

void	unload ()

bool	isLoaded () const

void	kzuResourceLoad_private (const ResourceLoaderThreadContext *threadContext)
	Private function for kzuResourceLoad() with specified thread context. More...

void	kzuResourceFinishLoading_private (const ResourceLoaderThreadContext *threadContext)
	Private function for finishing the loading of the resource. More...

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

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

Public Member Functions inherited from kanzi::Object
	Object (Domain *domain)

virtual	~Object ()

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

KzuTaskScheduler *	getTaskScheduler () const
	Returns the task scheduler of the object. More...

KzuMessageDispatcher *	getMessageDispatcher () const
	Returns the message dispatcher of the object. More...

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

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

AppliedStyleEntrySharedPtr	applyObjectStyle (kanzi::StyleSharedPtr style)
	Applies a style to an object. More...

void	unapplyObjectStyle (AppliedStyleEntrySharedPtr appliedStyleEntry)

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

void	unapplyObjectStyles ()
	Unapplies and removes all applied styles. More...

Public Member Functions inherited from kanzi::MetaObject
virtual	~MetaObject ()

bool	isTypeOf (const Metaclass *objectType) const
	Determines if the type of this object is the given type or derived from it. More...

Public Member Functions inherited from kanzi::PropertyObject
	PropertyObject ()

virtual	~PropertyObject ()

template<typename DataType >
void	setProperty (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Traits::ParameterType value)
	Sets the local value of a property. More...

void	removeKzbProperties ()

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

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 >
PropertyType< DataType >::Traits::ReturnType	getPropertyBase (const PropertyType< DataType > &propertyType) const
	Returns the current value of a property disregarding modifiers. More...

template<typename DataType >
void	setAbstractProperty (AbstractPropertyType abstractPropertyType, typename PropertyType< DataType >::Traits::ParameterType value)

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

void	setPropertyFlag (AbstractPropertyType propertyType, uint32_t flag)

bool	isPropertyFlagSet (AbstractPropertyType propertyType, uint32_t flag) const

void	clearPropertyFlag (AbstractPropertyType propertyType, uint32_t flag)

bool	hasValue (AbstractPropertyType propertyType) const
	Evaluates whether there are any inputs into the property value. 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...

void	removeLocalValue (AbstractPropertyType propertyType)
	Removes the local value associated with the property. More...

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

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

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

template<typename DataType >
void	removePropertyValueSource (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::TypedValueSource valueSource, void owner)

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

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

void	validatePropertyModifiers (AbstractPropertyType propertyType)

template<typename DataType >
void	addPropertyNotificationHandler (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::NotificationCallback callback, void *owner)

template<typename DataType >
void	removePropertyNotificationHandler (const PropertyType< DataType > &propertyType, typename PropertyType< DataType >::Descriptor::NotificationCallback callback, void *owner)

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

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, Type 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	createLoadTask (string_view name, KzbFile *kzbFile, unique_ptr< ReadOnlyMemoryFile > file)

static CreateInfo	createSubstitutePattern (const Renderer &renderer, Type type)
	Create a texture create info structure for a black 1x1 texture. 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...

Public Attributes
vector< BitmapImageSharedPtr >	images
	Images that are used to create the texture. More...

GraphicsFormat	format
	Format for texture. More...

GraphicsFormat	depthStencilFormat
	DepthStencil format. More...

unsigned int	features
	Required format features. More...

Type	type
	Texture type. More...

unsigned int	width
	Width for the base level of texture. More...

unsigned int	height
	Height for the base level of texture. More...

unsigned int	widthDivisor
	Automatic size determination divisor for width, 0 when not automatic. More...

unsigned int	heightDivisor
	Automatic size determination divisor for height, 0 when not automatic. More...

unsigned int	depth
	Reserved for future use. More...

unsigned int	renderTargetSampleCount
	Specifies number of samples for the draw renderbuffer when RenderTargetMode is RenderTargetModeExternal. More...

unsigned int	mipmapLevelCount
	Number of mipmap levels for the texture. More...

MemoryType	memoryType
	Memory type for the texture. More...

NativeDeploymentTarget	nativeDeploymentTarget
	Native deployment target to use for memory storage if supported by the backend. More...

RenderTargetMode	renderTargetMode
	RenderTarget mode for the texture. More...

Sampler::MipmapMode	mipmapMode
	Mipmap mode for the texture. More...

Sampler::Filter	minificationFilter
	Texture magnification filter. More...

Sampler::Filter	magnificationFilter
	Texture minification filter. More...

Sampler::AddressingMode	addressingMode
	Texture addressing mode. More...

float	anisotropy
	Texture anisotropy. More...

GraphicsCompareFunction	depthCompareFunction
	Depth comparison function. More...

float	mipLodBias
	Reserved for future use. More...

float	minLod
	Reserved for future use. More...

float	maxLod
	Reserved for future use. More...

Protected Member Functions
virtual void	reloadOverride () KZ_OVERRIDE
	Resource::reloadOverride() implementation. More...

virtual void	reloadFromKzbOverride (KzcInputStream inputStream, const KzuBinaryFileInfo file) KZ_OVERRIDE
	Resource::reloadFromKzbOverride() implementation. More...

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

virtual void	reloadFromFileOverride (string_view filePath) KZ_OVERRIDE
	Resource::reloadFromFileOverride() implementation. More...

virtual unsigned int	getCPUMemoryUsageOverride () const KZ_OVERRIDE
	Resource::getCPUMemoryUsageOverride() implementation. More...

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

virtual void	invalidateOverride () KZ_OVERRIDE
	GPUResource::invalidateOverride() implementation. More...

virtual bool	isDeployedOverride () const KZ_OVERRIDE
	GpuResource::isDeployed() implementation. More...

virtual unsigned int	getGPUMemoryUsageOverride () const KZ_OVERRIDE
	GpuResource::getGPUMemoryUsageOverride() implementation. More...

virtual void	attachOverride (Usage usage, APIAttachment apiAttachment, Face face, unsigned int mipmapLevel) KZ_OVERRIDE
	Surface::attachOverride() implementation. More...

virtual GraphicsFormat	getFormatOverride () const KZ_OVERRIDE
	Surface::getFormatOverride() implementation. More...

virtual unsigned int	getFeaturesOverride () const KZ_OVERRIDE
	Surface::getFeaturesOverride() implementation. More...

virtual unsigned int	getRenderTargetSampleCountOverride () const KZ_OVERRIDE
	Surface::getRenderTargetSampleCountOverride() implementation. More...

virtual unsigned int	getWidthOverride () const KZ_OVERRIDE
	Surface::getWidthOverride() implementation. More...

virtual unsigned int	getHeightOverride () const KZ_OVERRIDE
	Surface::getHeightOverride() implementation. More...

virtual unsigned int	getSliceCountOverride () const KZ_OVERRIDE
	Surface::getSliceCountOverride() implementation. More...

virtual unsigned int	getFaceCountOverride () const KZ_OVERRIDE
	Surface::getFaceCountOverride() implementation. More...

virtual unsigned int	getMipmapLevelCountOverride () const KZ_OVERRIDE
	Surface::getMipmapLevelCountOverride() implementation. More...

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

	Texture (Domain *domain, Type 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...

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

Status	validateImages (const Renderer &renderer) const
	Test if given set of images can be used to create Texture. More...

Status	validateFormat (const Renderer &renderer) const
	Validates texture format and features. More...

Status	validateSize (const Renderer &renderer) const
	Validates texture size against minimum valid texture size (1x1) and maximum supported by graphics adapter. More...

Status	validateTargetCompatibility (const Renderer &renderer) const
	Checks for known device incompatibilities, for example with texture formats and size. 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="")

Protected Member Functions inherited from kanzi::Object
void	initialize ()

void	onCopy (const Object &other)

Protected Member Functions inherited from kanzi::MetaObject
	MetaObject ()

void	initialize ()

Protected Member Functions inherited from kanzi::PropertyObject
void	addPropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource valueSource, PropertyValuePrecedence precedence, void owner)

void	removePropertyValueSource (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::ValueSource valueSource, void owner)

AbstractPropertyTypeDescriptor::ValueSourceEntry *	getTopValueSourceEntry (AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage) const

AbstractPropertyTypeDescriptor::ValueSourceEntry *	getTopValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor) const

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

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

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

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

AbstractPropertyTypeDescriptor::ValueSourceEntry *	findLocalValueSourceEntry (AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)

AbstractPropertyTypeDescriptor::ValueSourceEntry *	constructLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)

AbstractPropertyTypeDescriptor::ValueSourceEntry *	acquireLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, PropertyStoragePtr &propertyStorage)

AbstractPropertyTypeDescriptor::PropertyStorage *	findPropertyStorage (AbstractPropertyTypeDescriptor &descriptor) const

PropertyStoragePtr	findPropertyStoragePtr (AbstractPropertyTypeDescriptor &descriptor) const
	Gets property storage intrusive pointer that can be used to hold a reference until end of operation. More...

PropertyStoragePtr	constructPropertyStorage (AbstractPropertyTypeDescriptor &descriptor)

PropertyStoragePtr	acquirePropertyStorage (AbstractPropertyTypeDescriptor &descriptor)

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

AbstractPropertyTypeDescriptor::ModifierStorage *	findModifierStorage (AbstractPropertyTypeDescriptor &descriptor)

AbstractPropertyTypeDescriptor::NotificationStorage *	acquireNotificationStorage (AbstractPropertyTypeDescriptor &descriptor)

AbstractPropertyTypeDescriptor::NotificationStorage *	findNotificationStorage (AbstractPropertyTypeDescriptor &descriptor)

AbstractPropertyTypeDescriptor *	findPropertyTypeDescriptorByUnqualifiedNameAndDataType (string_view unqualifiedName, PropertyDataType dataType)

void	validatePropertyModifiersAndNotifyHandlers (PropertyStoragePtr &propertyStorage)

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

PropertyStorageContainer::iterator	beginPropertyStorage ()

PropertyStorageContainer::iterator	endPropertyStorage ()

virtual void	notifyPropertyHandlers (PropertyStoragePtr &propertyStorage, PropertyNotificationReason reason)

void	onCopy (const PropertyObject &other)

Static Protected Member Functions
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...

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

static GLRenderbufferHandle	makeRenderbufferHandle (Renderer *renderer, const CreateInfo &createInfo)
	Helper function to create GL renderbuffer object for color or depth/stencil buffer. More...

Friends
class	ResourceManager

class	Texture

void	swap (Texture &texture1, Texture &texture2)

Additional Inherited Members
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.

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

Texture creation parameters for texture that can be used as render target for renderpasses.

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

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

Texture creation parameters for two dimensional texture.

Struct which contains all the parameters that are needed for texture creation.

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.

See also: 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 also: 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 = Texture::TypeCubeMap;
            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 scene graph.
        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 scene graph.
        {
            CompositionStack& compositionStack = renderer->getCompositionStack();
            screen->setAllocatedSize(Vector2(static_cast<float>(width), static_cast<float>(height)));
            screen->setArrangeTransform(Matrix3x3());
            screen->layout();
            screen->extract();
            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");
            setScreen(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.
            LegacyRenderPassSharedPtr renderpass = LegacyRenderPass::create(domain, "renderpass");
            renderpass->setRenderPassRenderTargetColor0(texture);
            // There is no other content in the scene, but we do apply clear color.
            ColorRGBA lightBlue(0.4f, 0.4f, 0.9f, 1.0f);
            renderpass->setColorBuffer(true, lightBlue, GraphicsColorWriteModeRGBA);
            renderpass->setDepthBufferClearEnabled(false);
            renderpass->setStencilBufferClearEnabled(false);
            renderpass->initialize();
            scene->setRenderPass(renderpass);
            // Render the scene graph.
            {
                CompositionStack& compositionStack = renderer3D->getCompositionStack();
                screen->setAllocatedSize(Vector2(static_cast<float>(width), static_cast<float>(height)));
                screen->setArrangeTransform(Matrix3x3());
                screen->layout();
                screen->extract();
                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::CreateInfo2D textureCreateInfo(512, 512, GraphicsFormatR8G8B8A8_UNORM);
            // Set rendertarget mode to RenderTargetModeExternal
            textureCreateInfo.renderTargetMode = Texture::RenderTargetModeExternal;
            // Texture format is required to work as color attachment
            textureCreateInfo.features |= GraphicsFormatFeatureColorAttachment;
            // Adjust filter settings to reduce aliasing
            textureCreateInfo.minificationFilter = Sampler::FilterLinear;
            textureCreateInfo.magnificationFilter = Sampler::FilterLinear;
            // Create the texture
            TextureSharedPtr texture = Texture::create(domain, textureCreateInfo, "Texture");
            // Create Framebuffer, for rendering to the 
            Framebuffer::CreateInfo framebufferCreateInfo(Surface::UsageRenderTarget);
            framebufferCreateInfo.setAttachment(Framebuffer::AttachmentPointColor0, texture);
            {
                // Add depthStencil renderbuffer, for depth test to work. In this example
                // this is not actually necessary, but this is how you could do add it.
                Renderbuffer::CreateInfo renderbufferCreateInfo(512, 512, renderer->getDepthStencilFormatForRenderbuffer(true, false));
                framebufferCreateInfo.setAttachment(Framebuffer::AttachmentPointDepthStencil,
                                                    Renderbuffer::create(domain, renderbufferCreateInfo, "DepthStencil renderbuffer"));
            }
            FramebufferSharedPtr framebuffer = Framebuffer::create(domain, framebufferCreateInfo, "Framebuffer");
            // Render something to framebuffer. Here we just clear the texture.
            renderer->bindFramebuffer(framebuffer->getNativeHandle());
            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::CreateInfo2D textureCreateInfo(512, 512, GraphicsFormatR8G8B8A8_UNORM);
            // Set rendertarget mode to RenderTargetModeExternal
            textureCreateInfo.renderTargetMode = Texture::RenderTargetModeExternal;
            // Texture format is required to work as color attachment
            textureCreateInfo.features |= GraphicsFormatFeatureColorAttachment;
            // 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");
            // In this example, texture contents are specified by rendering to it with Kanzi
            // through a framebuffer. You can render to texture with framebuffer if you need
            // customized rendering and renderpass does not suit your requirements.
            Framebuffer::CreateInfo framebufferCreateInfo(Surface::UsageRenderTarget);
            unsigned int mipmapLevel = 0; // Render to texture base mipmap image.
            framebufferCreateInfo.setAttachment(Framebuffer::AttachmentPointColor0, texture, mipmapLevel);
            // Create Framebuffer for rendering to the texture to
            FramebufferSharedPtr framebuffer = Framebuffer::create(domain, framebufferCreateInfo, "Framebuffer");
            // Render something to framebuffer. Here we just clear the base level image of the texture.
            renderer->bindFramebuffer(framebuffer->getNativeHandle());
            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.
            // Here we use the default Texture::CreateInfo constructor, so we must fill in most members in it.
            Texture::CreateInfo textureCreateInfo;
            // Specify that a cubemap texture is to be created
            textureCreateInfo.type = Texture::TypeCubeMap;
            // Specify texture size and format
            textureCreateInfo.width = 512;
            textureCreateInfo.height = 512;
            textureCreateInfo.format = GraphicsFormatR8G8B8A8_UNORM;
            // We will render to the texture using a framebuffer, which manages necessary GL resources (GL framebuffer object)
            // for renderting to the texture
            textureCreateInfo.renderTargetMode = Texture::RenderTargetModeExternal;
            // Texture will sampled from, and it will be rendered to as a color attachment
            textureCreateInfo.features = GraphicsFormatFeatureSampledImage | GraphicsFormatFeatureColorAttachment;
            // 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");
            // Texture contents are specified by rendering to it with Kanzi through framebuffers.
            // You can render to texture with framebuffer if you need customized rendering and
            // renderpass does not suit your requirements. Since each framebuffer can only render to
            // one specific texture face, we need one framebuffer for each cubemap face.
            array<FramebufferSharedPtr, 6> framebuffers;
            unsigned int mipmapLevel = 0;
            for (unsigned int faceIndex = 0; faceIndex < 6; ++faceIndex)
            {
                Surface::Face face = static_cast<Surface::Face>(faceIndex);
                Framebuffer::CreateInfo framebufferCreateInfo(Surface::UsageRenderTarget);
                framebufferCreateInfo.setAttachment(Framebuffer::AttachmentPointColor0, texture, face, mipmapLevel);
                framebuffers[faceIndex] = Framebuffer::create(domain, framebufferCreateInfo, "Framebuffer for cubemap face " + to_string(faceIndex));
            }
            // Render to all cubemap faces
            renderer->setViewport(ViewportRectangle(0, 0, texture->getWidth(), texture->getHeight()));
            for (unsigned int faceIndex = 0; faceIndex < 6; ++faceIndex)
            {
                // Come up with content for each face; Fill with six shades of gray.
                float relativeFace = static_cast<float>(faceIndex) / 5.0f;
                renderer->bindFramebuffer(framebuffers[faceIndex]->getNativeHandle());
                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();

See also: Texture; Texture::CreateInfo2D; Texture::CreateInfoHostCopy2D; Texture::CreateInfoNode2DRenderTarget; Texture::CreateInfoRenderpassRenderTarget; Texture::CreateInfoCubemap

You can use resulting texture as content in Image2D nodes or texture brushes, or in materials for 3D rendering or material brushes.

You can use CreateInfoHostCopy2D to initialize texture creation parameters for textures that you update from the CPU. Textures will be created with specified format and size, and texture will maintain CPU accessible copy of texture content. Use Texture::getHostCopyImage() to access copy of texture data. Use this kind of texture is when you update texture contents only from the CPU, and you nead read access to the texture data. For example glyph cache for font rendering is a plausible use case.

Note: When you create texture from CreateInfoHostCopy2D, texture contents are initially undefined. Use Texture::setData() to specify texture contents.

See also: Texture::getHostCopyImage(); Texture::setData()

You can use the resulting texture as content in Image2D nodes or texture brushes. You can also use resulting texture in materials for 3D rendering or material brushes.

You can use the resulting texture as content in Image2D nodes or texture brushes. You can also use the resulting texture in materials for 3D rendering or material brushes.

Texture size, format and mipmap mode is determined from the images. You can use texture created with CreateInfoCubemap as content in materials for 3D rendering or material brushes.

Member Enumeration Documentation

enum kanzi::Texture::Type

Texture type.

Enumerator
TypeTwoDimensional	Two dimensional texture.
TypeTwoDimensionalArray	Reserved for future use. Do not use. Two dimensional array texture
TypeTwoDimensionalMultisample	Reserved for future use. Do not use. Two dimensional multisample texture
TypeTwoDimensionalMultisampleArray	Reserved for future use. Do not use. Two dimensional multisample array texture
TypeThreeDimensional	Reserved for future use. Do not use. Three dimensionla texture
TypeCubeMap	Cubemap texture.
TypeCubeMapArray	Reserved for future use. Do not use. Cubemap array texture
TypeExternal	External texture. Note External textures are specific to OpenGL ES and EGL.
TypeCount	Number of valid texture targets.
TypeInvalid	Invalid texture target.

enum kanzi::Texture::RenderTargetMode

RenderTarget mode for Texture.

Rendering to a Texture may require extra resources (such as framebuffer when using OpenGL or OpenGL ES). RenderTargetMode specifies who manages these resources.

Enumerator

RenderTargetModeNone

When texture has rendertarget mode RenderTargetModeNone, that texture cannot be rendered to.

You must not set such texture as render target for 2D nodes. You should not set such texture as render target for renderpasses.

RenderTargetModeInternal

RenderTargetModeInternal allows texture to be rendered to without externally managed resources.

You can set such texture as render target for 2D nodes. You should not set such texture as render target for renderpasses.

Note: Implementation details: When you create texture with renderTargetMode set to RenderTargetModeInternal, texture will internally maintain necessary resources that are required to perform rendering to the texture. When such texture is created, the texture will also maintain a GL framebuffer and optional depth stencil renderbuffer.; Use getNativeFramebufferHandle() to get handle to the framebuffer object in the texture.

RenderTargetModeExternal

RenderTargetModeExternal allows texture to be rendered to with externally managed resources.

You can set texture as render target for renderpasses. You must not set texture as render target for 2D nodes.

When you create texture with renderTargetMode set to RenderTargetModeExternal, an external entity such as renderpass is responsible for creating necessary resources that are required to perform rendering to the texture.

enum kanzi::Texture::Status

Status tells if texture creation parameters can be used to create a texture.

If status is not StatusValid, create info must not be passed to Texture::create().

Enumerator
StatusInvalidType	Invalid texture type. See Texture::Type for valid texture types.
StatusTypeNotSupported	Requested Texture type is not supported.
StatusInvalidRenderTargetMode	Requested rendertarget mode is not valid.
StatusInvalidImageCount	Wrong number of images. Two dimensional textures must have 0 or 1 image, cubemap textures must have 0 or 6 images.
StatusMissingImages	Not all images were properly defined.
StatusImageMissingMipmaps	Mipmaps are required, but the image is missing them.
StatusInvalidImageSize	Sizes of images are inconsistent.
StatusInvalidMinimumSize	Image size must be at least 1 x 1.
StatusInvalidMaximumSize	Image size cannot exceed size supported by the GL device.
StatusInvalidMipmapSize	Image mipmap size was not correctly derived from base image.
StatusUnsupportedGraphicsFormat	Unsupported image format.
StatusUnsupportedTextureFilter	Requested filtering mode is not supported for requested graphics format.
StatusInvalidFeatures	Requested graphics format features are not valid for texture.
StatusUnsupportedMultisampleFilter	Multisample textures do not support filtering.
StatusUnsupportedMultisampleMipmaps	Multisample textures do not support mipmaps.
StatusUnsupportedMultisampleSamples	Multisample textures must have a valid number of samples.
StatusUnsupportedInternalRenderTargetSampleCount	Textures with rendertarget mode set to RenderTargetModeInternal do not support multisampling.
StatusUnsupportedSampleCount	Requested number of multisample sample exceeds number of multisample samples supported by the graphics device.
StatusImageFormatMismatch	Inconsistent image formats.
StatusImageIncompatibleWithDevice	Image incompatible with target device.
StatusUnsupportedDepthComparisonMode	Requested depth comparison mode is not supported by graphics device.
StatusValid	CreateInfo is valid and can be used to create Texture.

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

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

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

Gets native texture handle for the texture.

Returns: Native texture handle.

unsigned int 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

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

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 kzcScreenCaptureToImage().

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.

bool kanzi::Texture::hasAutomaticWidth ( ) const

inline

Tell if width is or should be automatically calculated.

bool kanzi::Texture::hasAutomaticHeight ( ) const

inline

Tell if height is or should be automatically calculated.

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

inline

Get height divisor for automatic sizes.

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

inline

Get width divisor for automatic sizes.

static ResourceManager::LoadTaskSharedPtr kanzi::Texture::createLoadTask	(	string_view	name,
		KzbFile *	kzbFile,
		unique_ptr< ReadOnlyMemoryFile >	file
	)

static

virtual void kanzi::Texture::reloadOverride ( )

protectedvirtual

Resource::reloadOverride() implementation.

Reimplemented from kanzi::Resource.

virtual void kanzi::Texture::reloadFromKzbOverride	(	KzcInputStream *	inputStream,
		const KzuBinaryFileInfo *	file
	)

protectedvirtual

Resource::reloadFromKzbOverride() implementation.

Reimplemented from kanzi::Resource.

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

protectedvirtual

Resource::reloadFromKzbOverride() implementation.

Reimplemented from kanzi::Resource.

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

protectedvirtual

Resource::reloadFromFileOverride() implementation.

Reimplemented from kanzi::Resource.

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

protectedvirtual

Resource::getCPUMemoryUsageOverride() implementation.

Reimplemented from kanzi::Resource.

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

protected

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

Parameters

createInfo The texture descriptor.

virtual void kanzi::Texture::invalidateOverride ( )

protectedvirtual

GPUResource::invalidateOverride() implementation.

Reimplemented from kanzi::GPUResource.

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

protectedvirtual

GpuResource::isDeployed() implementation.

Implements kanzi::GPUResource.

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

protectedvirtual

GpuResource::getGPUMemoryUsageOverride() implementation.

Reimplemented from kanzi::GPUResource.

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

protectedvirtual

Surface::attachOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

Surface::getFormatOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

Surface::getFeaturesOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

Surface::getRenderTargetSampleCountOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

Surface::getWidthOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

Surface::getHeightOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

Surface::getSliceCountOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

Surface::getFaceCountOverride() implementation.

Implements kanzi::Surface.

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

protectedvirtual

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. A vector conatining newly allocated images will be returned.
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.

static GLRenderbufferHandle kanzi::Texture::makeRenderbufferHandle	(	Renderer *	renderer,
		const CreateInfo &	createInfo
	)

staticprotected

Helper function to create GL renderbuffer object for color or depth/stencil buffer.

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

kanzi::Texture::CreateInfo ( )

explicit

Default constructor for texture create info.

After the CreateInfo constructor:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.
Texture rendertarget mode is set to RenderTargetModeNone, so resulting texture cannot be set as rendertarget for neither 2d nodes nor renderpasses. If you want to render to the resulting texture, change rendertarget mode.

If you use this constructor, then you must fill in at least type, format, width and height before CreateInfo can be used to create texture.

Note: If you specify images after the constructor, you still need to set format, width, height and mipmapLevelCount correctly, You can simply do this by setting desired mipmapMode and the calling updateShapeAndFormatFromImages().; You can use CreateInfo2D, CreateInfoHostCopy2D, CreateInfoNode2DRenderTarget, :CreateInfoRenderpassRenderTarget and CreateInfoCubemap derived struct constructors to create initialize texture creation parameters for specific purpose.

Status kanzi::Texture::validate ( const Renderer & renderer ) const

Perform validation of texture creation parameters.

You can call validate() to see if texture creation parameters are valid before you pass create info to Texture::create().

Parameters

renderer Renderer to validate with.

Returns: StatusValid if these creation parameters can be used to create a texture. Otherwise a reason code for why this CreateInfo cannot be used to create a texture.

Status kanzi::Texture::adjust	(	const Renderer &	renderer,
		string_view	name
	)

Validates and applies adjustments to some texture creation parameters in case of avoidable error conditions.

Some error conditions cause adjustments instead of resulting in an error. These include:

Missing flags in the surface feature requirements based on given surface format specifications.
Applying for a surface format that is not supported by the current hardware.
Missing or invalid mipmaps. This function should be called when the texture create info should survive from the error cases above. In most use cases it is advisable to call this function regardless before passing the CreateInfo forward. It is not necessary to call validate() separately if using this function. The return value of this function is directly the return value of validate() after all possible adjustments have been made.
Parameters

renderer Renderer to validate with.

name A name to be used for this texture in possible warning log messages.

Returns
Status value for the validity of this descriptor after possible adjustments.

static CreateInfo kanzi::Texture::createSubstitutePattern	(	const Renderer &	renderer,
		Type	type
	)

static

Create a texture create info structure for a black 1x1 texture.

Parameters

renderer	Renderer to use for feature queries.
textureType	The type of the texture.

Returns: Texture::CreateInfo object that can be used for creating the texture.

void kanzi::Texture::updateShapeAndFormatFromImages ( )

Use updateShapeAndFormatFromImages() to fill in format, width, height from images.

Those parameters must match images in order for Texture::create() to accept CreateInfo.

Status kanzi::Texture::validateImages ( const Renderer & renderer ) const

protected

Test if given set of images can be used to create Texture.

Parameters

renderer Renderer to validate with.

Returns: Status if images can be used to create Texture, otherwise reason why images cannot be used to create Texture.

Status kanzi::Texture::validateFormat ( const Renderer & renderer ) const

protected

Validates texture format and features.

Parameters

renderer Renderer to validate with.

Returns: StatusValid if texture format is valid, otherwise reason why texture format and features is not valid.

Status kanzi::Texture::validateSize ( const Renderer & renderer ) const

protected

Validates texture size against minimum valid texture size (1x1) and maximum supported by graphics adapter.

Parameters

renderer Renderer to validate with.

Returns: StatusValid if image size is valid, otherwise reason why texture size is not valid.

Status kanzi::Texture::validateTargetCompatibility ( const Renderer & renderer ) const

protected

Checks for known device incompatibilities, for example with texture formats and size.

Parameters

renderer Renderer to validate with.

Returns: StatusValid if there is no known target compatibility issue with texture size or other parameters.

kanzi::Texture::CreateInfo2D ( BitmapImageUniquePtr image )

explicit

CreateInfo2D constructor for texture creation parameters, for creating a two dimensional texture that is initialized from an image.

After the CreateInfo2D constructor:

Image is stored in create info.
Texture type is set to TypeTwoDimensional.
Texture size and format is determined from the image.

The following (from CreateInfo constructor) also applies:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.

Note: After constructor, due to filter settings and lack of mipmaps, the resulting texture should only be used when texture content is shown without scaling. If you show resulting texture content with scaling, there will be noticable aliasing. Adjust filter and mipmap settings after constructor to reduce aliasing.; Texture::create() takes ownership of images you pass in the create info,

See also: Texture::create().; Image

Parameters

image Source image for texture.

kanzi::Texture::CreateInfo2D	(	Sampler::MipmapMode	mipmaps,
		BitmapImageUniquePtr	image
	)

explicit

CreateInfo2D constructor that also takes in mipmap mode.

For details, see #CreateInfo(ImageUniquePtr)

Parameters

mipmaps Mipmap mode.

kanzi::Texture::CreateInfo2D	(	unsigned int	width,
		unsigned int	height,
		GraphicsFormat	format
	)

explicit

CreateInfo2D constructor for texture creation parameters, for creating a two dimensional texture with specified format and size.

After the CreateInfo2D constructor:

Texture type is set to TypeTwoDimensional.
Texture size and format is set according to constructor parameters.

The following (from CreateInfo constructor) also applies:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.
Texture rendertarget mode is set to RenderTargetModeNone, so resulting texture cannot be set as rendertarget for neither 2d nodes nor renderpasses. If you want to render to the resulting texture, change rendertarget mode.

Note: After constructor, due to filter settings and lack of mipmaps, the resulting texture should only be used when texture content is shown without scaling. If you show resulting texture content with scaling, there will be noticable aliasing. Adjust filter and mipmap settings after constructor to reduce aliasing.; When you create texture from CreateInfo that has no images, texture contents are initially undefined. Use Texture::setData() to specify texture contents, or render to the texture.

Parameters

width	Width for the texture
height	Height for the texture
format	Format for the texture

kanzi::Texture::CreateInfoHostCopy2D	(	unsigned int	width,
		unsigned int	height,
		GraphicsFormat	format
	)

explicit

Constructor for CreateInfoHostCopy2D.

After the CreateInfoHostCopy2D constructor:

Texture memoryType is set to GpuAndRam

The following (from CreateInfo2D constructor) also applies:

Texture type is set to TypeTwoDimensional.
Texture size and format is set according to constructor parameters.

The following (from CreateInfo constructor) also applies:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.

Note: After constructor, due to filter settings and lack of mipmaps, the resulting texture should only be used when texture content is shown without scaling. If you show resulting texture content with scaling, there will be noticable aliasing. Adjust filter and mipmap settings after constructor to reduce aliasing.

Parameters

width	Width for the texture
height	Height for the texture
format	Format for the texture

kanzi::Texture::CreateInfoNode2DRenderTarget	(	unsigned int	width,
		unsigned int	height,
		GraphicsFormat	format
	)

explicit

Constructor for CreateInfoNode2DRenderTarget.

After the CreateInfoNode2DRenderTarget constructor:

Texture features is set to GraphicsFormatFeatureSampledImage and then OR'd with GraphicsFormatFeatureColorAttachment or GraphicsFormatFeatureDepthStencilAttachment depending on format.
Texture rendertarget mode is set to RenderTargetModeInternal, so Node2d::RenderTargetProperty can use the resulting texture.

The following (from CreateInfo2D constructor) also applies:

Texture type is set to TypeTwoDimensional.
Texture size and format is set according to constructor parameters.

The following (from CreateInfo constructor) also applies:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.

Note: After constructor, due to filter settings and lack of mipmaps, the resulting texture should only be used when texture content is shown without scaling. If resulting texture is shown with scaling, there will be noticable aliasing. You can adjust settings in the create info structure after constructor before passing it to Texture::create() if default settings are not ideal for you.; Not all texture formats support rendering to (GraphicsFormatFeatureColorAttachment). Make sure you use texture format that your device supports rendering to.

When you create texture from CreateInfoNode2DRenderTarget, texture contents are initially undefined. Set texture as rendertarget for a node, and arrange node to be rendered before using the texture as content.

See also: Node2D::RenderTargetProperty; Node2D::OffscreenRenderingProperty

Parameters

width	Width for the texture.
height	Height for the texture.
format	Format for the texture.

kanzi::Texture::CreateInfoRenderpassRenderTarget	(	unsigned int	width,
		unsigned int	height,
		GraphicsFormat	format
	)

explicit

Constructor for CreateInfoRenderpassRenderTarget - non-multisample version.

After the CreateInfoRenderpassRenderTarget constructor:

Texture features is set to GraphicsFormatFeatureSampledImage | GraphicsFormatFeatureColorAttachment.
Texture rendertarget mode is set to RenderTargetModeExternal, so renderpasses can use the resulting texture.

The following (from CreateInfo2D constructor) also applies:

Texture type is set to TypeTwoDimensional.
Texture size and format is set according to constructor parameters.

The following (from CreateInfo constructor) also applies:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.

Note: After constructor, due to filter settings and lack of mipmaps, the resulting texture should only be used when texture content is shown without scaling. If resulting texture is shown with scaling, there will be noticable aliasing. You can adjust settings in the create info structure after constructor before passing it to Texture::create() if default settings are not ideal for you.; Not all texture formats support rendering to (GraphicsFormatFeatureColorAttachment). Make sure you use texture format that your device supports rendering to.

When you create texture from CreateInfoRenderpassRenderTarget, texture contents are initially undefined. Set texture as rendertarget for a renderpass, and arrange viewport node to be rendered with the renderpass before using the texture as content.

See also: Scene::RenderPassProperty

Parameters

width	Width for the texture.
height	Height for the texture.
format	Format for the texture.

kanzi::Texture::CreateInfoRenderpassRenderTarget	(	Renderer *	renderer,
		unsigned int	sampleCount,
		unsigned int	width,
		unsigned int	height,
		GraphicsFormat	format
	)

explicit

Constructor for CreateInfoRenderpassRenderTarget - multisample version.

Use this CreateInfoRenderpassRenderTarget to create a texture which can be used in renderpasses with multisample anti aliasing.

Note: CreateInfoRenderpassRenderTarget constructor will throw an exception, which may stop program execution, if graphics device does not support multisample renderbuffers.

After the CreateInfoRenderpassRenderTarget constructor:

Texture features will have GraphicsFormatFeatureSampledImage and GraphicsFormatFeatureColorAttachment bits set. If graphics device supports multisampled render to texture extension, GraphicsFormatFeatureColorAttachment bit will be set in features. Else, if any other multisample technique is supported by graphics device, GraphicsFormatFeatureBlitDestination bit will be set in features.
Texture rendertarget mode is set to RenderTargetModeExternal, so renderpasses can use the resulting texture.
Texture renderTargetSampleCount is set to requested number of samples

The following (from CreateInfo2D constructor) also applies:

Texture type is set to TypeTwoDimensional.
Texture size and format is set according to constructor parameters.

The following (from CreateInfo constructor) also applies:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.

Note: After constructor, due to filter settings and lack of mipmaps, the resulting texture should only be used when texture content is shown without scaling. If resulting texture is shown with scaling, there will be noticable aliasing. You can adjust settings in the create info structure after constructor before passing it to Texture::create() if default settings are not ideal for you.; Not all texture formats support rendering to (GraphicsFormatFeatureColorAttachment). Make sure you use texture format that your device supports rendering to.

When you create texture from CreateInfoRenderpassRenderTarget, texture contents are initially undefined. Set texture as rendertarget for a renderpass, and arrange a viewport node to be rendered with the renderpass before using the texture as content.

Note: The resulting texture is not a multisample texture. For all sampling purposes, the resulting texture does not have multiple samples. Rendering to the texture happens through either a multisample renderbuffer or implicit resolve (multisampled render to texture extension)

See also: Scene::RenderPassProperty

Parameters

Renderer	Renderer, to provide multisample path.
sampleCount	Number of samples.
width	Width for the texture.
height	Height for the texture.
format	Format for the texture.

kanzi::Texture::CreateInfoCubemap ( BitmapImageVector images )

explicit

CreateInfoCubemap constructor for texture creation parameters, for creating a cube map texture that is initialized from six images.

After the CreateInfoCubemap constructor:

Images are stored in create info.
Texture type is set to TypeCubeMap.
Texture size and format is determined from the images.

The following (from CreateInfo constructor) also applies:

Texture minification and magnification filter settings are set to FilterNearest.
Texture wrap mode is set to AddressingModeClamp, so texture will not repeat.
Texture mipmap mode is set to MipmapModeBase, and mipmapLevelCount is set to 1, so texture will have only base image, no mipmaps.

Note: After constructor, due to filter settings and lack of mipmaps, the resulting texture should only be used when texture content is shown without scaling. If you show resulting texture content with scaling, there will be noticable aliasing. Adjust filter and mipmap settings after constructor to reduce aliasing.; TextureTexture::create() takes ownership of images you pass in the create info,

See also: Texture::create().; Image

Parameters

images Source images. There must be six images in the vector.

kanzi::Texture::CreateInfoCubemap	(	Sampler::MipmapMode	mipmapMode,
		BitmapImageVector	images
	)

explicit

CreateInfoCubemap constructor that also takes in mipmap mode.

For details, see #CreateInfoCubemap(ImageVector)

Parameters

mipmaps Mipmap mode.

Friends And Related Function Documentation

friend class ResourceManager

friend

friend class Texture

friend

void swap	(	Texture &	texture1,
		Texture &	texture2
	)

friend

Member Data Documentation

vector<BitmapImageSharedPtr> kanzi::Texture::images

Images that are used to create the texture.

If you set texture type to two dimensional, images must contain zero or one image. If you set texture type to cube map, images must contain zero or six images.

Default CreateInfo constructor initializes this to empty.

See also: updateShapeAndFormatFromImages()

GraphicsFormat kanzi::Texture::format

Format for texture.

Default CreateInfo constructor initializes this to GraphicsFormatNone, which is not valid value for Texture::create().

Note: Not all devices support all texture formats, and not all formats support all features. You can check with validate() that create info has combination of format and features that are supported by your graphics driver.

GraphicsFormat kanzi::Texture::depthStencilFormat

DepthStencil format.

This is only used when you set renderTargetMode to RenderTargetModeInternal.

Default CreateInfo constructor initializes this to GraphicsFormatNone, meaning there will be no depth/stencil for native framebuffer that is created if you set renderTargetMode to RenderTargetModeInternal.

Note: Only GraphicsFormatNone or formats with depth and/or stencil component are valid.

See also: GraphicsFormat.

unsigned int kanzi::Texture::features

Required format features.

Default CreateInfo constructor initializes this to GraphicsFormatFeatureSampledImage.

Note: Not all devices support all texture formats, and not all formats support all features. You can check with validate() that create info has combination of format and features that are supported by your graphics driver.

See also: GraphicsFormatFeature

Type kanzi::Texture::type

Texture type.

Default CreateInfo constructor initializes this to TypeInvalid, which is not valid value for Texture::create().

See also: Type

unsigned int kanzi::Texture::width

Width for the base level of texture.

Default CreateInfo constructor initializes this to 0, which is not valid value for Texture::create().

Note: Combination of mipmapMode, mipmapLevelCount, width and height must be valid when calling Texture::create().

unsigned int kanzi::Texture::height

Height for the base level of texture.

Default CreateInfo constructor initializes this to 0, which is not valid value for Texture::create().

Note: Combination of mipmapMode, mipmapLevelCount, width and height must be valid when calling Texture::create().

unsigned int kanzi::Texture::widthDivisor

Automatic size determination divisor for width, 0 when not automatic.

Default CreateInfo constructor initializes this to 0.

unsigned int kanzi::Texture::heightDivisor

Automatic size determination divisor for height, 0 when not automatic.

Default CreateInfo constructor initializes this to 0.

unsigned int kanzi::Texture::depth

Reserved for future use.

Set to 1.

Depth for the base level of texture.

Default CreateInfo constructor initializes this to 1.

unsigned int kanzi::Texture::renderTargetSampleCount

Specifies number of samples for the draw renderbuffer when RenderTargetMode is RenderTargetModeExternal.

Default CreateInfo constructor initializes this to 0, meaning no multisample samples.

unsigned int kanzi::Texture::mipmapLevelCount

Number of mipmap levels for the texture.

Default CreateInfo constructor initializes this to 1, meaning there is only base level image and no mipmap images.

Note: Combination of mipmapMode, mipmapLevelCount, width and height must be valid when calling Texture::create().

MemoryType kanzi::Texture::memoryType

Memory type for the texture.

If Gpu is not included, texture will not be deployed when created.

If Ram is not included, texture will not contain images after it has been deployed.

Default CreateInfo constructor initializes this to GpuOnly.

See also: MemoryType

NativeDeploymentTarget kanzi::Texture::nativeDeploymentTarget

Native deployment target to use for memory storage if supported by the backend.

Default CreateInfo constructor initializes this to None.

See also: NativeDeploymentTarget

RenderTargetMode kanzi::Texture::renderTargetMode

RenderTarget mode for the texture.

Default CreateInfo constructor initializes this to RenderTargetModeNone.

See also: RenderTargetMode

Sampler::MipmapMode kanzi::Texture::mipmapMode

Mipmap mode for the texture.

Default CreateInfo constructor initializes this to Sampler::MipmapModeBase.

Note: Default setting for mipmap and filter settings are optimized for textures that are shown without scaling. If your texture is shown with scaling, consider changing mipmapMode and filter settings to minimize aliasing.; Combination of mipmapMode, mipmapLevelCount, width and height must be valid when calling Texture::create().

See also: Sampler::MipmapMode

Sampler::Filter kanzi::Texture::minificationFilter

Texture magnification filter.

Default CreateInfo constructor initializes this to Sampler::FilterNearest.

Note: Default setting for mipmap and filter settings are optimized for textures that are shown without scaling. If your texture is shown with scaling, consider changing mipmapMode and filter settings to minimize aliasing.

See also: Sampler::Filter

Sampler::Filter kanzi::Texture::magnificationFilter

Texture minification filter.

Default CreateInfo constructor initializes this to Sampler::FilterNearest.

Note: Default setting for mipmap and filter settings are optimized for textures that are shown without scaling. If your texture is shown with scaling, consider changing mipmapMode and filter settings to minimize aliasing.

See also: Sampler::Filter

Sampler::AddressingMode kanzi::Texture::addressingMode

Texture addressing mode.

Default CreateInfo constructor initializes this to Sampler::AddressingModeClamp.

Note: Default setting for addressingMode makes the texture not repeat. If you want texture to repeat, you must change addressingMode.

See also: Sampler::AddressingMode

float kanzi::Texture::anisotropy

Texture anisotropy.

Default CreateInfo constructor initializes this to 1.0 (no anisotropy).

Note: Use of anisotropic texture filter requires GL extension.

GraphicsCompareFunction kanzi::Texture::depthCompareFunction

Depth comparison function.

Default CreateInfo constructor initializes this to GraphicsCompareFunctionLessOrEqual.

float kanzi::Texture::mipLodBias

Reserved for future use.

Set to 0.0f. Texture mipmap level of detail bias. Default CreateInfo constructor initializes this to 0.

Note: Using texture Lod controls requires OpenGL ES 3.0.

float kanzi::Texture::minLod

Reserved for future use.

Set to -1000.0f. Minimum texture level of detail. Default CreateInfo constructor initializes this to -1000.0f (effectively no clamping for level of detail).

Note: Using texture Lod controls requires OpenGL ES 3.0.

float kanzi::Texture::maxLod

Reserved for future use.

Maximum texture level of detail. Default CreateInfo constructor initializes this to 1000 (effectively no clamping for level of detail).

Note: Using texture Lod controls requires OpenGL ES 3.0.

The documentation for this struct was generated from the following files:

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

renderer	Renderer to validate with.
name	A name to be used for this texture in possible warning log messages.

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

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

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation