Owns a stencil attachment and two fullscreen pipelines for stencil-masked rendering. More...

#include <mxvk/include/mxvk/mxvk_stencil.hpp>

Classes
struct	PushConstants
	Push-constant payload shared by the mask and content shaders. More...

Public Member Functions
void	configure_attachment (VkRenderingAttachmentInfo &attachment) const
	Fill a VkRenderingAttachmentInfo for VK_Window dynamic rendering.
void	destroy ()
	Release all Vulkan resources and reset the helper to an empty state.
void	draw_content (VkCommandBuffer cmd, const PushConstants &push_constants) const
	Draw the fullscreen content pass clipped by stencil reference value 1.
void	draw_mask (VkCommandBuffer cmd, const PushConstants &push_constants) const
	Draw the fullscreen stencil-writing mask pass.
VkExtent2D	extent () const noexcept
	Return the current stencil attachment extent.
void	initialize (const VulkanContext &context, VkExtent2D extent, VkFormat color_format, VkFormat depth_format, VkPipelineCache pipeline_cache, const std::string &mask_vertex_shader, const std::string &mask_fragment_shader, const std::string &content_vertex_shader, const std::string &content_fragment_shader)
	Create the stencil attachment and fullscreen mask/content pipelines.
VK_Stencil &	operator= (const VK_Stencil &)=delete
VK_Stencil &	operator= (VK_Stencil &&)=delete
void	prepare_for_rendering (VkCommandBuffer cmd)
	Transition the stencil image for use as a dynamic-rendering stencil attachment.
void	resize (VkExtent2D extent)
	Recreate the stencil image for a new render extent.
VkFormat	stencil_format () const noexcept
	Return the selected stencil-capable image format.
bool	valid () const noexcept
	Check whether image resources are ready for rendering.
	VK_Stencil ()=default
	Construct an empty stencil helper.
	VK_Stencil (const VK_Stencil &)=delete
	VK_Stencil (VK_Stencil &&)=delete
	~VK_Stencil ()
	Destroy any live Vulkan resources owned by the helper.

Detailed Description

Owns a stencil attachment and two fullscreen pipelines for stencil-masked rendering.

VK_Stencil is intended for use from VK_Window subclasses. Call initialize() once the window has a valid device and swapchain extent, call prepare_for_rendering() before VK_Window begins dynamic rendering, pass configure_attachment() through VK_Window::onConfigureDepthStencilAttachments(), then call draw_mask() before draw_content() inside VK_Window::onRecordCustomRendering().

Definition at line 26 of file mxvk_stencil.hpp.

Constructor & Destructor Documentation

◆ VK_Stencil() [1/3]

mxvk::VK_Stencil::VK_Stencil ( )

default

Construct an empty stencil helper.

◆ ~VK_Stencil()

mxvk::VK_Stencil::~VK_Stencil ( )

Destroy any live Vulkan resources owned by the helper.

Definition at line 10 of file mxvk_stencil.cpp.

                            {
        destroy();
    }

◆ VK_Stencil() [2/3]

mxvk::VK_Stencil::VK_Stencil ( const VK_Stencil & )

delete

◆ VK_Stencil() [3/3]

mxvk::VK_Stencil::VK_Stencil ( VK_Stencil && )

delete

Member Function Documentation

◆ configure_attachment()

void mxvk::VK_Stencil::configure_attachment ( VkRenderingAttachmentInfo & attachment ) const

Fill a VkRenderingAttachmentInfo for VK_Window dynamic rendering.

Parameters

attachment Attachment info to populate when the helper is valid.

Definition at line 90 of file mxvk_stencil.cpp.

                                                                                     {
        if (!valid()) {
            return;
        }
        attachment.imageView = view;
        attachment.imageLayout = VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL;
        attachment.loadOp = VK_ATTACHMENT_LOAD_OP_CLEAR;
        attachment.storeOp = VK_ATTACHMENT_STORE_OP_DONT_CARE;
        attachment.clearValue.depthStencil = {1.0f, 0U};
    }

◆ destroy()

void mxvk::VK_Stencil::destroy ( )

Release all Vulkan resources and reset the helper to an empty state.

Definition at line 38 of file mxvk_stencil.cpp.

                             {
        destroy_pipelines();
        destroy_image();
        vk_context = {};
        stencil_extent = {};
        render_color_format = VK_FORMAT_UNDEFINED;
        render_depth_format = VK_FORMAT_UNDEFINED;
        stencil_image_format = VK_FORMAT_UNDEFINED;
        cache = VK_NULL_HANDLE;
        mask_vertex_path.clear();
        mask_fragment_path.clear();
        content_vertex_path.clear();
        content_fragment_path.clear();
    }

◆ draw_content()

void mxvk::VK_Stencil::draw_content	(	VkCommandBuffer	cmd,
		const PushConstants &	push_constants ) const

Draw the fullscreen content pass clipped by stencil reference value 1.

Parameters

cmd	Command buffer recording inside the dynamic-rendering scope.
push_constants	Values passed to the content fragment shader.

Definition at line 110 of file mxvk_stencil.cpp.

                                                                                                {
        if (content_pipeline == VK_NULL_HANDLE || content_layout == VK_NULL_HANDLE) {
            return;
        }
        vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, content_pipeline);
        vkCmdPushConstants(cmd, content_layout, VK_SHADER_STAGE_FRAGMENT_BIT, 0, sizeof(PushConstants), &push_constants);
        vkCmdDraw(cmd, 3, 1, 0, 0);
    }

◆ draw_mask()

void mxvk::VK_Stencil::draw_mask	(	VkCommandBuffer	cmd,
		const PushConstants &	push_constants ) const

Draw the fullscreen stencil-writing mask pass.

Parameters

cmd	Command buffer recording inside the dynamic-rendering scope.
push_constants	Values passed to the mask fragment shader.

Definition at line 101 of file mxvk_stencil.cpp.

                                                                                             {
        if (mask_pipeline == VK_NULL_HANDLE || mask_layout == VK_NULL_HANDLE) {
            return;
        }
        vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, mask_pipeline);
        vkCmdPushConstants(cmd, mask_layout, VK_SHADER_STAGE_FRAGMENT_BIT, 0, sizeof(PushConstants), &push_constants);
        vkCmdDraw(cmd, 3, 1, 0, 0);
    }

◆ extent()

VkExtent2D mxvk::VK_Stencil::extent ( ) const

inlinenodiscardnoexcept

Return the current stencil attachment extent.

Definition at line 121 of file mxvk_stencil.hpp.

121{ return stencil_extent; }

◆ initialize()

void mxvk::VK_Stencil::initialize	(	const VulkanContext &	context,
		VkExtent2D	extent,
		VkFormat	color_format,
		VkFormat	depth_format,
		VkPipelineCache	pipeline_cache,
		const std::string &	mask_vertex_shader,
		const std::string &	mask_fragment_shader,
		const std::string &	content_vertex_shader,
		const std::string &	content_fragment_shader )

Create the stencil attachment and fullscreen mask/content pipelines.

Parameters

context	Vulkan device, physical device, queue, and command pool handles.
extent	Size of the stencil attachment in pixels.
color_format	Color attachment format used by the active dynamic rendering pass.
depth_format	Depth attachment format used by the active dynamic rendering pass.
pipeline_cache	Optional pipeline cache used when creating graphics pipelines.
mask_vertex_shader	SPIR-V vertex shader path for the stencil-writing pass.
mask_fragment_shader	SPIR-V fragment shader path for the stencil-writing pass.
content_vertex_shader	SPIR-V vertex shader path for the stencil-tested content pass.
content_fragment_shader	SPIR-V fragment shader path for the stencil-tested content pass.

Existing resources are destroyed before the new resources are created.

Definition at line 14 of file mxvk_stencil.cpp.

                                                                          {
        destroy();
        vk_context = context;
        stencil_extent = extent;
        render_color_format = color_format;
        render_depth_format = depth_format;
        cache = pipeline_cache;
        mask_vertex_path = mask_vertex_shader;
        mask_fragment_path = mask_fragment_shader;
        content_vertex_path = content_vertex_shader;
        content_fragment_path = content_fragment_shader;
        stencil_image_format = choose_stencil_format();
        create_resources();
        create_pipelines();
    }

◆ operator=() [1/2]

VK_Stencil & mxvk::VK_Stencil::operator= ( const VK_Stencil & )

delete

◆ operator=() [2/2]

VK_Stencil & mxvk::VK_Stencil::operator= ( VK_Stencil && )

delete

◆ prepare_for_rendering()

void mxvk::VK_Stencil::prepare_for_rendering ( VkCommandBuffer cmd )

Transition the stencil image for use as a dynamic-rendering stencil attachment.

Parameters

cmd	Command buffer currently recording outside a rendering scope.

Definition at line 62 of file mxvk_stencil.cpp.

                                                              {
        if (!valid()) {
            return;
        }
 
        VkImageMemoryBarrier2 barrier{};
        barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2;
        barrier.srcStageMask = image_initialized ? VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT : VK_PIPELINE_STAGE_2_NONE;
        barrier.srcAccessMask = image_initialized ? VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT : VK_ACCESS_2_NONE;
        barrier.dstStageMask = VK_PIPELINE_STAGE_2_EARLY_FRAGMENT_TESTS_BIT | VK_PIPELINE_STAGE_2_LATE_FRAGMENT_TESTS_BIT;
        barrier.dstAccessMask = VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_READ_BIT | VK_ACCESS_2_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT;
        barrier.oldLayout = image_initialized ? VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL : VK_IMAGE_LAYOUT_UNDEFINED;
        barrier.newLayout = VK_IMAGE_LAYOUT_STENCIL_ATTACHMENT_OPTIMAL;
        barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.image = image;
        barrier.subresourceRange.aspectMask = VK_IMAGE_ASPECT_STENCIL_BIT;
        barrier.subresourceRange.levelCount = 1;
        barrier.subresourceRange.layerCount = 1;
 
        VkDependencyInfo dependency{};
        dependency.sType = VK_STRUCTURE_TYPE_DEPENDENCY_INFO;
        dependency.imageMemoryBarrierCount = 1;
        dependency.pImageMemoryBarriers = &barrier;
        vkCmdPipelineBarrier2(cmd, &dependency);
        image_initialized = true;
    }

◆ resize()

void mxvk::VK_Stencil::resize ( VkExtent2D extent )

Recreate the stencil image for a new render extent.

Parameters

extent New attachment size in pixels.

Pipelines are retained because they depend on formats, not image dimensions.

Definition at line 53 of file mxvk_stencil.cpp.

                                             {
        if (extent.width == stencil_extent.width && extent.height == stencil_extent.height) {
            return;
        }
        stencil_extent = extent;
        destroy_image();
        create_resources();
    }

◆ stencil_format()

VkFormat mxvk::VK_Stencil::stencil_format ( ) const

inlinenodiscardnoexcept

Return the selected stencil-capable image format.

Definition at line 118 of file mxvk_stencil.hpp.

118{ return stencil_image_format; }

◆ valid()

bool mxvk::VK_Stencil::valid ( ) const

nodiscardnoexcept

Check whether image resources are ready for rendering.

Definition at line 119 of file mxvk_stencil.cpp.

                                          {
        return vk_context.device != VK_NULL_HANDLE && image != VK_NULL_HANDLE && view != VK_NULL_HANDLE &&
               stencil_extent.width > 0U && stencil_extent.height > 0U;
    }

The documentation for this class was generated from the following files:

mxvk/include/mxvk/mxvk_stencil.hpp
mxvk/src/mxvk_stencil.cpp

MXVK Vulkan Framework 0.33.1 C++20 Vulkan rendering framework for practical 2D and 3D application development with SDL3.

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ VK_Stencil() [1/3]

◆ ~VK_Stencil()

◆ VK_Stencil() [2/3]

◆ VK_Stencil() [3/3]

Member Function Documentation

◆ configure_attachment()

◆ destroy()

◆ draw_content()

◆ draw_mask()

◆ extent()

◆ initialize()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ prepare_for_rendering()

◆ resize()

◆ stencil_format()

◆ valid()