Struct Texture

pub struct Texture(/* private fields */);

Expand description

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

Textures can be set as render target. Texture can be set to as render target for either 2d node or render pass, but not both.

For details on the render target texture, see RenderTargetMode, CreateInfoNode2DRenderTarget, and CreateInfoRenderpassRenderTarget. Note that the CreateInfoRenderpassRenderTarget is intended for use with the deprecated LegacyRenderPass. For all other render passes, use CreateInfoNode2DRenderTarget, or to acquire the composition targets use the CompositionManager.

Texture can optionally maintain CPU accessible copy of texture data. See CreateInfoHostCopy2D. for CPU accessible texture data details.

In order to create a texture, you must prepare Texture::CreateInfo structure and make sure it is valid using CreateInfo::validate(), then create the texture with Texture::create(). If texture creation parameters are not valid, Texture::create() will throw an exception, which can stop program execution.

Two dimensional textures can be created from Image or by specifying size, format and features. Cubemap textures can be created from six Images or by specifying size, format and features.

You must specify texture filtering, addressing mode (also known as wrap mode), and mipmap settings in Texture::CreateInfo before you create the texture. Two dimensional textures which are shown without scaling can be created with default texture creation parameters, which improve performance and reduce memory usage. If you show texture content with scaling, consider using linear filtering and prefiltered mipmaps to reduce aliasing, with some performance and memory cost.

§Examples - Creating Textures with Kanzi C++ API

To create a two dimensional texture from image:

To load image from file and create texture:

To access the image data after you create a texture:

To create a two dimensional texture from image with custom sampler settings:

To create a cubemap texture from 6 face images:

Examples - Loading textures with Kanzi C++ API using ResourceManager

To load texture with ResourceManager using file URL:

To load texture with ResourceManager:

§Examples - Updating texture data with Kanzi C++ API

To update texture data of two dimensional texture base level image:

To update texture data of cubemap texture all mipmap level images:

§Examples - Use texture as render target for node 2D or renderpass using Kanzi C++ API

To use texture as render target for 2D node:

To use texture as render target for renderpass:

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

To create a two dimensional texture with mipmaps and render to it through framebuffer:

To create a cubemap texture with mipmaps and render to it through framebuffers:

Implementations§

§

impl Texture

pub fn create( domain: &Domain, create_info: TextureCreateInfo, name: impl AsRef<KanziStr>, ) -> Result<Texture, Error>

§Arguments

domain - Domain for the texture.
create_info - Texture creation parameters.
name - Name for the texture.

§Errors

Returns an INVALID_ARGUMENT error if an invalid TextureCreateInfo is provided.

pub unsafe fn create_unchecked( domain: &Domain, create_info: TextureCreateInfo, name: impl AsRef<KanziStr>, ) -> Result<Texture, Error>

§Arguments

domain - Domain for the texture.
create_info - Texture creation parameters.
name - Name for the texture.

§Returns

Texture shared pointer.

pub fn recreate(&self, create_info: TextureCreateInfo) -> Result<(), Error>

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

Methods from Deref<Target = Surface>§

pub fn get_width(&self) -> Result<u32, Error>

Get width in pixels.

pub fn get_height(&self) -> Result<u32, Error>

Get height in pixels.

pub fn get_render_target_sample_count(&self) -> Result<u32, Error>

Get number of multisample samples for Surface.

§Returns

Surface multisampling count.

pub fn get_format(&self) -> Result<GraphicsFormat, Error>

Get GraphicsFormat of Surface.

pub fn get_slice_count(&self) -> Result<u32, Error>

Get number of slices.

pub fn get_face_count(&self) -> Result<u32, Error>

Get number of faces. This should be six for cubemaps and one for everything else

pub fn get_mipmap_level_count(&self) -> Result<u32, Error>

Get number of mipmap levels

Methods from Deref<Target = GPUResource>§

pub fn get_gpu_memory_usage(&self) -> Result<u32, Error>

Gets the amount of GPU memory consumed by the resource.

§Returns

GPU memory consumption in bytes.

pub fn is_deployed(&self) -> Result<bool, Error>

Indicates whether a GPU resource is deployed.

Methods from Deref<Target = Resource>§

pub fn get_name(&self) -> Result<KanziString, Error>

Gets the resource name.

pub fn get_url(&self) -> Result<KanziString, Error>

Gets the resource URL. Note that the URL is not necessarily in URL form if resource has been just created.

§Returns

URL string.

pub fn set_keep_alive(&self, keep_alive: bool) -> Result<(), Error>

Sets the keep alive flag. Can be set only before the resource is registered to the resource manager. Normally set by loadFromKZB.

§Arguments

keep_alive - Value for the keep alive flag.

Methods from Deref<Target = Object>§

pub fn as_ptr(&self) -> *mut ObjectWrapper

pub fn as_wrapper(&self) -> &ObjectWrapper

pub fn as_object(&self) -> &Object

Represents any type inheriting from Object as &Object. This is useful for comparisions when PartialEq traits failed to compare objects of different types.

let child = screen.get_child(0)?;
let parent = child.get_parent()?.into_error(ErrorKind::ObjectNotFound)?;
// assert_eq!(screen, parent); // <- Fails to compile!
assert_eq!(screen.as_object(), parent.as_object());

pub fn get_native(&self) -> Result<NonNull<c_void>, Error>

Gets a pointer to the backing C++ instance.

pub fn is_stale(&self) -> bool

Checks whether the weak reference has expired.

pub fn get_property<T>( &self, property_type: &PropertyType<T>, ) -> Result<<T as VariantConstraint>::RetArg, Error>
where T: PropertyTypeConstraint,

Returns the current value of a property disregarding modifiers.

Base value is affected by the following inputs where the highest entry in the list determines the base value:

Local value set with setProperty or loaded from kzb
Value set by a style affecting the property.
Value defined by class metadata.

Modifiers are not applied, the highest-priority base value is returned.

If no inputs to the property value can be established the system returns the value default value from property type metadata.

§Arguments

property_type - The property type identifying the property to retrieve.

§Returns

The evaluated property value.

pub fn get_optional_property<T>( &self, property_type: &PropertyType<T>, ) -> Result<Option<<T as VariantConstraint>::RetArg>, Error>
where T: PropertyTypeConstraint,

Returns the current value of a property disregarding modifiers, but does not default to the value in property metadata if there are no inputs to the property value.

If there is no value sources, None is returned.

If no inputs to the property value can be established the system returns the value default value from property type metadata.