Kanzi  3.9.7
Kanzi Engine API
kanzi::Texture::CreateInfo Struct Reference

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:
[legend]

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

Member Enumeration Documentation

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

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
rendererRenderer to validate with.
nameA 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.
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
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::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
    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::CreateInfo::createSubstitutePattern ( const Renderer renderer,
TextureType  type 
)
static

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

Parameters
rendererRenderer to use for feature queries.
typeThe type of the texture.
Returns
Texture::CreateInfo object that can be used for creating the texture.
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.

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

Friends And Related Function Documentation

friend class Texture
friend

Member Data Documentation

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

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

Default CreateInfo constructor initializes this to 0.

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

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

Default CreateInfo constructor initializes this to 0.

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.

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.

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

RenderTarget mode for the texture.

Default CreateInfo constructor initializes this to RenderTargetModeNone.

See also
RenderTargetMode
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
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
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
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
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.
GraphicsCompareFunction kanzi::Texture::CreateInfo::depthCompareFunction

Depth comparison function.

Default CreateInfo constructor initializes this to GraphicsCompareFunctionLessOrEqual.

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