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

#include <kanzi/core.ui/graphics2d/texture_create_info.hpp>

Inheritance diagram for kanzi::Texture::CreateInfo:

Public Types
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 Member Functions
Status	adjust (const Renderer &renderer, string_view name)
	Validates and applies adjustments to some texture creation parameters in case of avoidable error conditions. More...

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

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

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

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

Static Public Member Functions
static CreateInfo	createSubstitutePattern (const Renderer &renderer, TextureType type)
	Create a texture create info structure for a black 1x1 texture. More...

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

float	anisotropy
	Texture anisotropy. More...

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

GraphicsCompareFunction	depthCompareFunction
	Depth comparison function. More...

GraphicsFormat	depthStencilFormat
	DepthStencil format. More...

unsigned int	features
	Required format features. More...

GraphicsFormat	format
	Format for texture. More...

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

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

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

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

float	maxLod
	Reserved for future use. More...

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

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

float	minLod
	Reserved for future use. More...

float	mipLodBias
	Reserved for future use. More...

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

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

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

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

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

TextureType	type
	Texture type. More...

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

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

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

Status	validateImages (const Renderer &renderer) const
	Test if given set of images can be used to create Texture. 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...

Friends
class	Texture

Detailed Description

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

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

Member Enumeration Documentation

◆ Status

enum kanzi::Texture::CreateInfo::Status

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

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

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

Constructor & Destructor Documentation

◆ CreateInfo()

kanzi::Texture::CreateInfo::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.

Member Function Documentation

◆ validate() [1/2]

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

Perform validation of texture creation parameters.

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

Parameters

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

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.

◆ validate() [2/2]

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

Perform validation of texture creation parameters.

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

Parameters

renderer Renderer to validate with.

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

◆ adjust()

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

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

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

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

renderer Renderer to validate with.

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

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

◆ createSubstitutePattern()

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

static

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

Parameters

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

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

◆ updateShapeAndFormatFromImages()

void kanzi::Texture::CreateInfo::updateShapeAndFormatFromImages ( )

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

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

◆ validateImages()

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

protected

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

Parameters

renderer Renderer to validate with.

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

◆ validateFormat()

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

protected

Validates texture format and features.

Parameters

renderer Renderer to validate with.

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

◆ validateSize()

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

protected

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

Parameters

renderer Renderer to validate with.

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

◆ validateTargetCompatibility()

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

protected

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

Parameters

renderer Renderer to validate with.

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

Friends And Related Function Documentation

◆ Texture

friend class Texture

friend

Member Data Documentation

◆ images

vector<BitmapImageSharedPtr> kanzi::Texture::CreateInfo::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()

◆ format

GraphicsFormat kanzi::Texture::CreateInfo::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.

◆ depthStencilFormat

GraphicsFormat kanzi::Texture::CreateInfo::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.

◆ features

unsigned int kanzi::Texture::CreateInfo::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

TextureType kanzi::Texture::CreateInfo::type

Texture type.

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

See also: Type

◆ width

unsigned int kanzi::Texture::CreateInfo::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().

◆ height

unsigned int kanzi::Texture::CreateInfo::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().

◆ widthDivisor

unsigned int kanzi::Texture::CreateInfo::widthDivisor

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

Default CreateInfo constructor initializes this to 0.

◆ heightDivisor

unsigned int kanzi::Texture::CreateInfo::heightDivisor

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

Default CreateInfo constructor initializes this to 0.

◆ depth

unsigned int kanzi::Texture::CreateInfo::depth

Reserved for future use.

Set to 1.

Depth for the base level of texture.

Default CreateInfo constructor initializes this to 1.

◆ renderTargetSampleCount

unsigned int kanzi::Texture::CreateInfo::renderTargetSampleCount

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

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

◆ mipmapLevelCount

unsigned int kanzi::Texture::CreateInfo::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

MemoryType kanzi::Texture::CreateInfo::memoryType

Memory type for the texture.

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

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

Default CreateInfo constructor initializes this to GpuOnly.

See also: MemoryType

◆ nativeDeploymentTarget

NativeDeploymentTarget kanzi::Texture::CreateInfo::nativeDeploymentTarget

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

Default CreateInfo constructor initializes this to None.

See also: NativeDeploymentTarget

◆ renderTargetMode

RenderTargetMode kanzi::Texture::CreateInfo::renderTargetMode

RenderTarget mode for the texture.

Default CreateInfo constructor initializes this to RenderTargetModeNone.

See also: RenderTargetMode

◆ mipmapMode

Sampler::MipmapMode kanzi::Texture::CreateInfo::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

◆ minificationFilter

Sampler::Filter kanzi::Texture::CreateInfo::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

◆ magnificationFilter

Sampler::Filter kanzi::Texture::CreateInfo::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

◆ addressingMode

Sampler::AddressingMode kanzi::Texture::CreateInfo::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

◆ anisotropy

float kanzi::Texture::CreateInfo::anisotropy

Texture anisotropy.

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

Note: Use of anisotropic texture filter requires GL extension.

◆ depthCompareFunction

GraphicsCompareFunction kanzi::Texture::CreateInfo::depthCompareFunction

Depth comparison function.

Default CreateInfo constructor initializes this to GraphicsCompareFunctionLessOrEqual.

◆ mipLodBias

float kanzi::Texture::CreateInfo::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.

◆ minLod

float kanzi::Texture::CreateInfo::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.

◆ maxLod

float kanzi::Texture::CreateInfo::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 file:

kanzi/core.ui/graphics2d/texture_create_info.hpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ Status

Constructor & Destructor Documentation

◆ CreateInfo()

Member Function Documentation

◆ validate() [1/2]

◆ validate() [2/2]

◆ adjust()

◆ createSubstitutePattern()

◆ updateShapeAndFormatFromImages()

◆ validateImages()

◆ validateFormat()

◆ validateSize()

◆ validateTargetCompatibility()

Friends And Related Function Documentation

◆ Texture

Member Data Documentation

◆ images

◆ format

◆ depthStencilFormat

◆ features

◆ type

◆ width

◆ height

◆ widthDivisor

◆ heightDivisor

◆ depth

◆ renderTargetSampleCount

◆ mipmapLevelCount

◆ memoryType

◆ nativeDeploymentTarget

◆ renderTargetMode

◆ mipmapMode

◆ minificationFilter

◆ magnificationFilter

◆ addressingMode

◆ anisotropy

◆ depthCompareFunction

◆ mipLodBias

◆ minLod

◆ maxLod