kanzi::Texture Struct Reference

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

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

Inheritance diagram for kanzi::Texture:
kanzi::Surface kanzi::GPUResource kanzi::Resource kanzi::Object kanzi::MetaObject kanzi::PropertyObject

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::PropertyStoragePropertyStoragePtr
 
typedef vector< PropertyStoragePtrPropertyStorageContainer
 
typedef PropertyStorageContainer::iterator PropertyStorageIterator
 
typedef PropertyStorageContainer::const_iterator PropertyStorageConstIterator
 
typedef PropertyStorageContainer::reverse_iterator PropertyStorageReverseIterator
 

Public Member Functions

const SamplergetSampler () const
 Returns the Sampler used by the texture. More...
 
Type getType () const
 Returns type of the texture. 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
 
RenderergetRenderer () const
 
bool isDeployed () const
 
- Public Member Functions inherited from kanzi::Resource
KzcMemoryManagergetMemoryManager () 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 ()
 
DomaingetDomain () const
 Returns the domain the object belongs to. More...
 
KzuTaskSchedulergetTaskScheduler () const
 Returns the task scheduler of the object. More...
 
KzuMessageDispatchergetMessageDispatcher () const
 Returns the message dispatcher of the object. More...
 
ResourceManagergetResourceManager () const
 Returns the resource manager of the object. More...
 
virtual const MetaclassgetDynamicMetaclass () 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 MetaclassgetStaticMetaclass ()
 Returns the metaclass of Object class. More...
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 Default implementation that returns empty editor info. More...
 
- Static Public Member Functions inherited from kanzi::MetaObject
static const MetaclassgetStaticMetaclass ()
 Returns the metaclass of Object class. More...
 
static PropertyTypeEditorInfoSharedPtr makeEditorInfo ()
 Default implementation that returns empty editor info. More...
 

Public Attributes

vector< BitmapImageSharedPtrimages
 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...
 
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::ValueSourceEntrygetTopValueSourceEntry (AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage) const
 
AbstractPropertyTypeDescriptor::ValueSourceEntrygetTopValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourcegetTopValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourcegetFinalValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourcegetNonClassValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourcegetClassValueSource (AbstractPropertyTypeDescriptor &descriptor) const
 
AbstractPropertyTypeDescriptor::ValueSourceEntryfindLocalValueSourceEntry (AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
 
AbstractPropertyTypeDescriptor::ValueSourceEntryconstructLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor, AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
 
AbstractPropertyTypeDescriptor::ValueSourceEntryacquireLocalValueSourceEntry (AbstractPropertyTypeDescriptor &descriptor)
 
AbstractPropertyTypeDescriptor::PropertyStoragefindPropertyStorage (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::ModifierStorageacquireModifierStorage (AbstractPropertyTypeDescriptor &descriptor)
 
AbstractPropertyTypeDescriptor::ModifierStoragefindModifierStorage (AbstractPropertyTypeDescriptor &descriptor)
 
AbstractPropertyTypeDescriptor::NotificationStorageacquireNotificationStorage (AbstractPropertyTypeDescriptor &descriptor)
 
AbstractPropertyTypeDescriptor::NotificationStoragefindNotificationStorage (AbstractPropertyTypeDescriptor &descriptor)
 
AbstractPropertyTypeDescriptorfindPropertyTypeDescriptorByUnqualifiedNameAndDataType (string_view unqualifiedName, PropertyDataType dataType)
 
void validatePropertyModifiersAndNotifyHandlers (PropertyStoragePtr &propertyStorage)
 
void copyLocalValue (const AbstractPropertyTypeDescriptor::PropertyStorage &propertyStorage)
 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< BitmapImageSharedPtrmakeHostCopyImages (const CreateInfo &createInfo)
 Helper function to allocate host images. More...
 
static GLTextureHandle makeTexture (Renderer *renderer, const CreateInfo &createInfo)
 Helper function to create GL texture object. More...
 
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< AppliedStyleEntrySharedPtrAppliedStyleContainer
 Applied style container. More...
 
- Protected Attributes inherited from kanzi::Object
AppliedStyleContainer m_appliedStyles
 Listing of applied styles applied to this object. More...
 

Detailed Description

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

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.
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;
// 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.
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.
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.
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()
// 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
// 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
// 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

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.

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.

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
DomainDomain for texture.
createInfoTexture creation parameters.
nameName 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
DomainDomain for texture.
typeTexture type.
glHandlePre-existing valid GL texture object name.
formatFormat of the texture.
mipmapLevelCountMipmap level count of the texture.
widthWidth of the texture.
heightHeight of the texture.
takeOwnershipShould kanzi::Texture take ownership of provided GL texture object
nameName

Member Function Documentation

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

Creates a texture with specified texture creation parameters.

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

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

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

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

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

Note
create() takes ownership of images you pass in the create info. You must not delete images that you pass to Texture::create() in createInfos. You must immediately discard any CreateInfo which contains images after first call to create(). The images in createInfo are no longer valid, and such CreateInfo cannot be reused.
Parameters
domainDomain for the texture.
createInfoTexture creation parameters.
nameName for the texture.
Returns
Texture shared pointer.
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
domainDomain.
typeTexture type.
nativeHandlePre-existing native handle that identifies a valid GL texture object.
takeOwnershipIf true, texture will take ownership of the native resource (GL texture object).
formatFormat of the texture.
mipmapLevelCountNumber of mipmap levels in the texture.
widthWidth of the texture.
heightHeight of the texture.
nameName.
Returns
Texture shared pointer.
const Sampler& kanzi::Texture::getSampler ( ) const

Returns the Sampler used by the texture.

Type kanzi::Texture::getType ( ) const

Returns type of the texture.

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
colorRenderbufferRenderbuffer 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
depthTextureDepth 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
faceWhich texture face to update.
mipmapLevelWhich mipmap level to update.
x,y,width,heightSpecifies the rectangle to update.
dataTexture 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
mipmapLevelWhich mip level to update.
x,y,width,heightSpecifies the rectangle to update.
dataTexture data.
void kanzi::Texture::setData ( const kanzi::byte data)

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

Parameters
dataTexture 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
faceThe texture face for which you want to get the data. For single textures, this value is FaceDefault. For cube-map textures use a valid face for the texture. For example, FacePositiveX, or FaceNegativeZ. If you try to access an invalid texture face, the function throws an exception.
sliceThe texture slice for which you want to get the data. Slice applies to array and 3D textures. Currently this parameter must always be 0. If you access an invalid texture slice, the function throws an exception.
Returns
When you create a texture with the MemoryType property set to GpuAndRam or RamOnly, returns the host-side image uploaded to to the GPU. If you create a texture with the MemoryType property set to GpuOnly, or try to retrieve a composition target texture, returns a null pointer.
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
widthNew width.
heightNew 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
createInfoThe 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
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
static vector<BitmapImageSharedPtr> kanzi::Texture::makeHostCopyImages ( const CreateInfo createInfo)
staticprotected

Helper function to allocate host images.

There are three cases:

  1. Texture is created with GpuOnly memory type, empty vector will be returned.
  2. Texture is created with RamOnly or GpuAndRam memory type, and create info contains images. A vector containing those images from create info will be returned.
  3. Texture is created with RamOnly or GpuAndRam memory type, create info did not contain images. A vector conatining newly allocated images will be returned.
    Parameters
    createInfoTexture create info.
    Returns
    Vector of images. It will be empty if texture memory type is GpuOnly, otherwise it will have images from createInfo if it has images, and if not, it will return newly allocated images.
static GLTextureHandle kanzi::Texture::makeTexture ( Renderer renderer,
const CreateInfo createInfo 
)
staticprotected

Helper function to create GL texture object.

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

Parameters
rendererRenderer.
createInfoTexture create info.
Returns
Texture handle.
static GLFramebufferHandle kanzi::Texture::makeFramebuffer ( Renderer renderer,
const CreateInfo createInfo 
)
staticprotected

Helper function to create GL framebuffer object.

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

Parameters
rendererRenderer.
createInfoTexture create info.
Returns
Framebuffer handle.
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
rendererRenderer.
createInfoTexture 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
imagesImages to deploy.
rendererRenderer.
void kanzi::Texture::deployInternalFramebuffers ( Renderer renderer,
RenderbufferSharedPtr  colorRenderbuffer,
TextureSharedPtr  depthTexture 
)
protected

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

Texture internal variables must already be initialized.

Parameters
rendererRenderer.
colorRenderbufferColor renderbuffer not owned by the texture to attach.
depthTextureDepth texture not owned by this texture to attach.
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
rendererRenderer 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
    rendererRenderer to validate with.
    nameA 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
rendererRenderer to use for feature queries.
textureTypeThe 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
rendererRenderer 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
rendererRenderer 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
rendererRenderer 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
rendererRenderer 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
imageSource 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
mipmapsMipmap 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
widthWidth for the texture
heightHeight for the texture
formatFormat 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
widthWidth for the texture
heightHeight for the texture
formatFormat 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
widthWidth for the texture.
heightHeight for the texture.
formatFormat 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
widthWidth for the texture.
heightHeight for the texture.
formatFormat 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
RendererRenderer, to provide multisample path.
sampleCountNumber of samples.
widthWidth for the texture.
heightHeight for the texture.
formatFormat 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
imagesSource 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
mipmapsMipmap 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
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: