Struct CompositionTargetRenderPass

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

Use the Composition Target Render Pass to set one to four composition targets and render all descendant render passes to the composition targets that the Composition Target Render Pass created. If you set multiple composition targets, rendering can write to all specified buffers at the same time. See MultipleCompositionTargets “Using multiple composition targets”. After Kanzi renders the descendant render passes of a Composition Target Render Pass, the Composition Target Render Pass restores the earlier composition settings.

Configuring the composition target

Composition Target Render Pass by default creates one composition target whose size is the same as the size of the current Viewport 2D node using the RGBA pixel format and depth buffer. To configure the composition target, you can:

• Set the pixel format of the composition target with the PixelFormat0Property property.
• Set the size of the composition target in relation to the size of the current Viewport 2D node with the ResolutionMultiplierProperty and ResolutionDivisorProperty properties. These properties set a fractional number (rational number) which Kanzi uses to multiply the size of the current Viewport 2D node.
• Set the absolute size of the composition target with the WidthProperty and HeightProperty. This overrides the resolution that you set with the ResolutionMultiplierProperty and ResolutionDivisorProperty.
• Set the filtering mode of the composition target with the FilterModeProperty and MipmapModeProperty.
• Set the addressing mode of the composition target with the AddressingModeProperty.
• Set the number of samples for each pixel or disable multisampling with the MultisampleLevelProperty.

Using custom render target textures

You can set a Composition Target Render Pass to use a composition target texture that you create somewhere else with the CompositionTarget0Property property. The render pass for which you set the composition target texture with this property does not create its own render target.

For example, to use a custom render target texture, bind the CompositionTarget0Property property of a Composition Target Render Pass to properties of other render passes. Use the DepthTargetProperty to set the depth texture.

To set a Composition Target Render Pass to render to multiple render target textures, use these properties to set each render target texture:

• CompositionTarget0Property
• CompositionTarget1Property
• CompositionTarget2Property
• CompositionTarget3Property
• DepthTargetProperty

When you use the result target properties from other CompositionTargetRenderPass render passes to render incrementally into the targets, set the ResolveImmediatelyProperty to false in the original CompositionTargetRenderPass.

The size settings of the explicitly defined composition targets must match. If you do not explicitly define some of the composition targets, the size of the explicitly defined composition targets must match the size that Kanzi automatically calculates for the viewport. Kanzi discards all composition targets with mismatches in their sizes and instead creates a composition target automatically.

Accessing the composition target result

To access the result of a Composition Target Render Pass:

The texture that the getResultTexture0() function returns is not necessarily the texture that a Composition Target Render Pass rendered, or the texture set to the CompositionTarget0Property. For example, if you use multisampling, the getResultTexture0() function returns the target, where it resolves multiple samples into a 2D texture.

If a Composition Target Render Pass was not executed, the result of the getResultTexture0() function is undefined.

To use the result textures of a Composition Target Render Pass in another render pass, create bindings to these properties:

• ResultTexture0Property
• ResultTexture1Property
• ResultTexture2Property
• ResultTexture3Property
• ResultDepthTextureProperty

For example, in a Blit Render Pass you can bind the BlitRenderPass::Texture0Property to the ResultTexture0Property of a Composition Target Render Pass, the BlitRenderPass::Texture1Property to the ResultTexture1Property, and so on.

You can use the result texture properties to access the result textures of both the explicitly defined composition targets and the composition targets generated automatically by the Composition Target Render Pass.

To avoid needlessly updating the bindings that read these properties, Kanzi updates the values of these properties only when the associated composition targets change or disappear.

Use the ResolveImmediatelyProperty to set whether to resolve multisamples and generate mipmaps for the composition targets immediately after rendering. By default the Composition Render Target Render Pass resolves multisamples and generates mipmaps immediately, but if you use some or all of the composition targets for further rendering elsewhere, you can set the value of this property to false. This way you delay the resolve operations until the result composition target is referenced.

Using multiple composition targets

You can set a Composition Target Render Pass to render to up to 4 composition targets at the same time. To control the pixel format of a composition target, set its pixel format property:

• PixelFormat0Property
• PixelFormat1Property
• PixelFormat2Property
• PixelFormat3Property
• DepthTextureFormatProperty

The Pixel Format property with the highest index sets the number of composition targets that Kanzi creates for a Composition Target Render Pass. If you do not set some of the Pixel Format properties, those properties get their value from a Pixel Format property with a higher index whose value is set. For example, if you set the values of the PixelFormat0Property and PixelFormat2Property, Kanzi creates three composition targets and:

• The first composition target uses the pixel format that you set using the PixelFormat0Property.
• The second composition target uses the pixel format that you set in the PixelFormat2Property.
• The third composition target uses the pixel format that you set in the PixelFormat2Property.

To set the same pixel format for all composition targets, you can set the corresponding highest-index pixel format property and remove the other pixel format properties.

Use the DepthTextureFormatProperty to set the format for a depth texture. When you do not set the DepthTextureFormatProperty, but the rendering settings require depth testing to render the child render passes, Kanzi automatically creates a depth renderbuffer. When you set the DepthTextureFormatProperty, Kanzi creates a depth texture that you can access with the ResultDepthTextureProperty.

To create a Composition Target Render Pass with multiple output textures:

To use the result textures from a Composition Target Render Pass in a Blit Render Pass:

Examples

To use a Composition Target Render Pass with a custom render target with automatic size:

Implementations

impl CompositionTargetRenderPass

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

Creates a Composition Target Render Pass.

Arguments

• domain - The domain to use.
• name - The name of the Composition Target Render Pass.

Returns

The created Composition Target Render Pass.

impl CompositionTargetRenderPass

pub fn get_composition_target0(&self) -> Result<Option<Weak<Resource>>, Error>

See: COMPOSITION_TARGET0_PROPERTY

pub fn set_composition_target0( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COMPOSITION_TARGET0_PROPERTY

pub fn get_composition_target1(&self) -> Result<Option<Weak<Resource>>, Error>

See: COMPOSITION_TARGET1_PROPERTY

pub fn set_composition_target1( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COMPOSITION_TARGET1_PROPERTY

pub fn get_composition_target2(&self) -> Result<Option<Weak<Resource>>, Error>

See: COMPOSITION_TARGET2_PROPERTY

pub fn set_composition_target2( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COMPOSITION_TARGET2_PROPERTY

pub fn get_composition_target3(&self) -> Result<Option<Weak<Resource>>, Error>

See: COMPOSITION_TARGET3_PROPERTY

pub fn set_composition_target3( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COMPOSITION_TARGET3_PROPERTY

pub fn get_depth_target(&self) -> Result<Option<Weak<Resource>>, Error>

See: DEPTH_TARGET_PROPERTY

pub fn set_depth_target(&self, value: Option<&Resource>) -> Result<(), Error>

See: DEPTH_TARGET_PROPERTY

pub fn get_result_texture0(&self) -> Result<Option<Weak<Resource>>, Error>

See: RESULT_TEXTURE0_PROPERTY

pub fn set_result_texture0(&self, value: Option<&Resource>) -> Result<(), Error>

See: RESULT_TEXTURE0_PROPERTY

pub fn get_result_texture1(&self) -> Result<Option<Weak<Resource>>, Error>

See: RESULT_TEXTURE1_PROPERTY

pub fn set_result_texture1(&self, value: Option<&Resource>) -> Result<(), Error>

See: RESULT_TEXTURE1_PROPERTY

pub fn get_result_texture2(&self) -> Result<Option<Weak<Resource>>, Error>

See: RESULT_TEXTURE2_PROPERTY

pub fn set_result_texture2(&self, value: Option<&Resource>) -> Result<(), Error>

See: RESULT_TEXTURE2_PROPERTY

pub fn get_result_texture3(&self) -> Result<Option<Weak<Resource>>, Error>

See: RESULT_TEXTURE3_PROPERTY

pub fn set_result_texture3(&self, value: Option<&Resource>) -> Result<(), Error>

See: RESULT_TEXTURE3_PROPERTY

pub fn get_result_depth_texture(&self) -> Result<Option<Weak<Resource>>, Error>

See: RESULT_DEPTH_TEXTURE_PROPERTY

pub fn set_result_depth_texture( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: RESULT_DEPTH_TEXTURE_PROPERTY

pub fn get_resolution_multiplier(&self) -> Result<i32, Error>

See: RESOLUTION_MULTIPLIER_PROPERTY

pub fn set_resolution_multiplier(&self, value: i32) -> Result<(), Error>

See: RESOLUTION_MULTIPLIER_PROPERTY

pub fn get_resolution_divisor(&self) -> Result<i32, Error>

See: RESOLUTION_DIVISOR_PROPERTY

pub fn set_resolution_divisor(&self, value: i32) -> Result<(), Error>

See: RESOLUTION_DIVISOR_PROPERTY

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

See: WIDTH_PROPERTY

pub fn set_width(&self, value: i32) -> Result<(), Error>

See: WIDTH_PROPERTY

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

See: HEIGHT_PROPERTY

pub fn set_height(&self, value: i32) -> Result<(), Error>

See: HEIGHT_PROPERTY

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

See: PIXEL_FORMAT0_PROPERTY

pub fn set_pixel_format0(&self, value: GraphicsFormat) -> Result<(), Error>

See: PIXEL_FORMAT0_PROPERTY

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

See: PIXEL_FORMAT1_PROPERTY

pub fn set_pixel_format1(&self, value: GraphicsFormat) -> Result<(), Error>

See: PIXEL_FORMAT1_PROPERTY

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

See: PIXEL_FORMAT2_PROPERTY

pub fn set_pixel_format2(&self, value: GraphicsFormat) -> Result<(), Error>

See: PIXEL_FORMAT2_PROPERTY

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

See: PIXEL_FORMAT3_PROPERTY

pub fn set_pixel_format3(&self, value: GraphicsFormat) -> Result<(), Error>

See: PIXEL_FORMAT3_PROPERTY

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

See: DEPTH_TEXTURE_FORMAT_PROPERTY

pub fn set_depth_texture_format( &self, value: GraphicsFormat, ) -> Result<(), Error>

See: DEPTH_TEXTURE_FORMAT_PROPERTY

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

See: DEPTH_RENDERBUFFER_FORMAT_PROPERTY

pub fn set_depth_renderbuffer_format( &self, value: GraphicsFormat, ) -> Result<(), Error>

See: DEPTH_RENDERBUFFER_FORMAT_PROPERTY

pub fn get_depth_compare_function( &self, ) -> Result<GraphicsCompareFunction, Error>

See: DEPTH_COMPARE_FUNCTION_PROPERTY

pub fn set_depth_compare_function( &self, value: GraphicsCompareFunction, ) -> Result<(), Error>

See: DEPTH_COMPARE_FUNCTION_PROPERTY

pub fn get_addressing_mode(&self) -> Result<SamplerAddressingMode, Error>

See: ADDRESSING_MODE_PROPERTY

pub fn set_addressing_mode( &self, value: SamplerAddressingMode, ) -> Result<(), Error>

See: ADDRESSING_MODE_PROPERTY

pub fn get_filter_mode(&self) -> Result<SamplerFilter, Error>

See: FILTER_MODE_PROPERTY

pub fn set_filter_mode(&self, value: SamplerFilter) -> Result<(), Error>

See: FILTER_MODE_PROPERTY

pub fn get_mipmap_mode(&self) -> Result<SamplerMipmapMode, Error>

See: MIPMAP_MODE_PROPERTY

pub fn set_mipmap_mode(&self, value: SamplerMipmapMode) -> Result<(), Error>

See: MIPMAP_MODE_PROPERTY

pub fn get_multisample_level(&self) -> Result<MultisampleCount, Error>

See: MULTISAMPLE_LEVEL_PROPERTY

pub fn set_multisample_level( &self, value: MultisampleCount, ) -> Result<(), Error>

See: MULTISAMPLE_LEVEL_PROPERTY

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

See: RESOLVE_IMMEDIATELY_PROPERTY

pub fn set_resolve_immediately(&self, value: bool) -> Result<(), Error>

See: RESOLVE_IMMEDIATELY_PROPERTY

Methods from Deref<Target = RenderPass>

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

See: ENABLED_PROPERTY

pub fn set_enabled(&self, value: bool) -> Result<(), Error>

See: ENABLED_PROPERTY

pub fn get_input_viewport_area(&self) -> Result<Vector4, Error>

See: INPUT_VIEWPORT_AREA_PROPERTY

pub fn set_input_viewport_area(&self, value: Vector4) -> Result<(), Error>

See: INPUT_VIEWPORT_AREA_PROPERTY

pub fn get_update_rate(&self) -> Result<i32, Error>

See: UPDATE_RATE_PROPERTY

pub fn set_update_rate(&self, value: i32) -> Result<(), Error>

See: UPDATE_RATE_PROPERTY

pub fn get_update_offset(&self) -> Result<i32, Error>

See: UPDATE_OFFSET_PROPERTY

pub fn set_update_offset(&self, value: i32) -> Result<(), Error>

See: UPDATE_OFFSET_PROPERTY

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:

1. Local value set with setProperty or loaded from kzb
2. Value set by a style affecting the property.
3. 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.

Arguments

• property_type - The property type identifying the property to retrieve.

Returns

The evaluated property value.

pub fn set_property<T>( &self, property_type: &PropertyType<T>, value: <T as VariantConstraint>::DataArg<'_>, ) -> Result<(), Error>

where T: PropertyTypeConstraint,

Sets the local value of a property type.

pub fn has_value<T>( &self, property_type: &PropertyType<T>, ) -> Result<bool, Error>

where T: PropertyTypeConstraint,

Evaluates whether there are any inputs into the property value. Both value sources and modifiers are taken into account.

Returns

Returns true if there are inputs into the property value, false otherwise.

pub fn remove_local_value<T>( &self, property_type: &PropertyType<T>, ) -> Result<(), Error>

where T: PropertyTypeConstraint,

Removes the local value associated with the property.

pub fn get_metaclass(&self) -> Result<Metaclass, Error>

Returns the metaclass of the dynamic type of the object.

pub fn get_domain(&self) -> Result<Domain, Error>

Returns the domain the object belongs to.

pub fn set_flag_keep_during_patching<T>( &self, property_type: &PropertyType<T>, ) -> Result<(), Error>

where T: PropertyTypeConstraint,

Sets the flag to indicate that the property was loaded from KZB.

pub fn debug_string(&self) -> Result<String, Error>

Builds a string representation of the object intended for debugging purposes.

Trait Implementations

impl Clone for CompositionTargetRenderPass

fn clone(&self) -> CompositionTargetRenderPass

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl ConcreteObjectConstraint for CompositionTargetRenderPass

fn create_instance( domain: &Domain, name: impl AsRef<KanziStr>, ) -> Result<Self, Error>

impl Debug for CompositionTargetRenderPass

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Deref for CompositionTargetRenderPass

type Target = RenderPass

The resulting type after dereferencing.

fn deref(&self) -> &<CompositionTargetRenderPass as Deref>::Target

Dereferences the value.

impl IMipmapGenerationConcept for CompositionTargetRenderPass

fn get_cubemap_mipmap_material(&self) -> Result<Option<Weak<Resource>>, Error>

See: CUBEMAP_MIPMAP_MATERIAL_PROPERTY

fn set_cubemap_mipmap_material( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: CUBEMAP_MIPMAP_MATERIAL_PROPERTY

fn get_color_mipmap_material0(&self) -> Result<Option<Weak<Resource>>, Error>

See: COLOR_MIPMAP_MATERIAL0_PROPERTY

fn set_color_mipmap_material0( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COLOR_MIPMAP_MATERIAL0_PROPERTY

fn get_color_mipmap_material1(&self) -> Result<Option<Weak<Resource>>, Error>

See: COLOR_MIPMAP_MATERIAL1_PROPERTY

fn set_color_mipmap_material1( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COLOR_MIPMAP_MATERIAL1_PROPERTY

fn get_color_mipmap_material2(&self) -> Result<Option<Weak<Resource>>, Error>

See: COLOR_MIPMAP_MATERIAL2_PROPERTY

fn set_color_mipmap_material2( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COLOR_MIPMAP_MATERIAL2_PROPERTY

fn get_color_mipmap_material3(&self) -> Result<Option<Weak<Resource>>, Error>

See: COLOR_MIPMAP_MATERIAL3_PROPERTY

fn set_color_mipmap_material3( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: COLOR_MIPMAP_MATERIAL3_PROPERTY

fn get_depth_mipmap_material(&self) -> Result<Option<Weak<Resource>>, Error>

See: DEPTH_MIPMAP_MATERIAL_PROPERTY

fn set_depth_mipmap_material( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: DEPTH_MIPMAP_MATERIAL_PROPERTY

fn get_current_mipmap_level(&self) -> Result<f32, Error>

See: CURRENT_MIPMAP_LEVEL_PROPERTY

fn set_current_mipmap_level(&self, value: f32) -> Result<(), Error>

See: CURRENT_MIPMAP_LEVEL_PROPERTY

fn get_mipmap_source_texture(&self) -> Result<Option<Weak<Resource>>, Error>

See: MIPMAP_SOURCE_TEXTURE_PROPERTY

fn set_mipmap_source_texture( &self, value: Option<&Resource>, ) -> Result<(), Error>

See: MIPMAP_SOURCE_TEXTURE_PROPERTY

impl Inheritable for CompositionTargetRenderPass

unsafe fn downcast_unchecked<T>(self) -> T

where T: Inherits<Self>,

Downcast the object to a more specific type.

unsafe fn downcast_unchecked_ref<T>(&self) -> &T

where T: Inherits<Self>,

Downcast the object reference to a more specific type.

impl Inherits<MipmapGenerationConcept> for CompositionTargetRenderPass

fn upcast(self) -> Base

fn upcast_ref(&self) -> &Base

impl Inherits<Object> for CompositionTargetRenderPass

fn upcast(self) -> Base

fn upcast_ref(&self) -> &Base

impl Inherits<RenderPass> for CompositionTargetRenderPass

fn upcast(self) -> Base

fn upcast_ref(&self) -> &Base

impl Inherits<Resource> for CompositionTargetRenderPass

fn upcast(self) -> Base

fn upcast_ref(&self) -> &Base

impl MetaclassConstraint for CompositionTargetRenderPass

fn get_static_metaclass() -> &'static Metaclass

Gets metaclass associated with a given type.

impl ObjectConstraint for CompositionTargetRenderPass

fn downcast<T>(self) -> Result<Option<T>, Error>

where T: MetaInherits<Self>,

Casts metaclass to a more specific type by value.

fn downcast_ref<T>(&self) -> Result<Option<&T>, Error>

where T: MetaInherits<Self>,

Casts metaclass to a more specific type by reference.

fn is_a<T>(&self) -> Result<bool, Error>

where T: MetaInherits<Self>,

Determines whether the class this metaclass describes derives from a class described by specified metaclass.

fn downgrade(self) -> Weak<Self>

fn downgrade_ref(&self) -> Weak<Self>

fn lock(self) -> ThreadObject<Self>

fn lock_ref(&self) -> ThreadObject<Self>

impl<T> PartialEq<T> for CompositionTargetRenderPass

where T: ObjectConstraint,

fn eq(&self, rhs: &T) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialEq<Weak<T>> for CompositionTargetRenderPass

where T: ObjectConstraint,

fn eq(&self, rhs: &Weak<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for CompositionTargetRenderPass