Reusable Vulkan point-list renderer for textured particle effects. More...

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

Public Member Functions
size_t	capacity () const
void	cleanup ()
	Destroy all owned resources and reset the batch to an unloaded state.
void	load (VK_Window *window, const std::string &texture_path, const std::string &vertex_shader_path, const std::string &fragment_shader_path, size_t max_vertices)
	Create texture, vertex buffer, descriptors, and point-list pipeline.
bool	loaded () const
VK_PointSpriteBatch &	operator= (const VK_PointSpriteBatch &)=delete
VK_PointSpriteBatch &	operator= (VK_PointSpriteBatch &&)=delete
void	render (VkCommandBuffer cmd, uint32_t image_index)
	Record point-sprite draw commands into an active rendering scope.
void	resize (VK_Window *window)
	Recreate swapchain-dependent resources after a window resize.
void	set_additive_blending (bool enabled)
	Select additive or alpha-over color blending.
void	set_depth_test_enabled (bool enabled)
	Enable or disable depth testing in the point-sprite pipeline.
void	set_depth_write_enabled (bool enabled)
	Enable or disable depth writes in the point-sprite pipeline.
void	update_mvp (uint32_t image_index, const glm::mat4 &mvp)
	Update the MVP uniform for one swapchain image.
void	upload_vertices (const PointSpriteVertex *vertices, size_t count)
	Copy point vertices into the persistent mapped vertex buffer.
size_t	vertex_count () const
	VK_PointSpriteBatch ()=default
	Construct an empty point-sprite batch.
	VK_PointSpriteBatch (const VK_PointSpriteBatch &)=delete
	VK_PointSpriteBatch (VK_PointSpriteBatch &&)=delete
	~VK_PointSpriteBatch ()
	Destroy all owned Vulkan resources.

Detailed Description

Reusable Vulkan point-list renderer for textured particle effects.

VK_PointSpriteBatch owns a host-visible vertex buffer, a sampled point texture, per-swapchain MVP uniform buffers, descriptors, and a point-list graphics pipeline using MXVK's dynamic rendering path. It is intended for starfields, sparks, dust, and similar effects where each vertex becomes one shader-expanded point sprite via gl_PointSize/gl_PointCoord.

The caller owns simulation and fills PointSpriteVertex data each frame via upload_vertices(). The batch must be loaded only after VK_Window has created deferred render resources, usually from onRecordCustomRendering().

Definition at line 53 of file mxvk_point_sprite_batch.hpp.

Constructor & Destructor Documentation

◆ VK_PointSpriteBatch() [1/3]

mxvk::VK_PointSpriteBatch::VK_PointSpriteBatch ( )

default

Construct an empty point-sprite batch.

◆ ~VK_PointSpriteBatch()

mxvk::VK_PointSpriteBatch::~VK_PointSpriteBatch ( )

Destroy all owned Vulkan resources.

Definition at line 14 of file mxvk_point_sprite_batch.cpp.

                                              {
        cleanup();
    }

◆ VK_PointSpriteBatch() [2/3]

mxvk::VK_PointSpriteBatch::VK_PointSpriteBatch ( const VK_PointSpriteBatch & )

delete

◆ VK_PointSpriteBatch() [3/3]

mxvk::VK_PointSpriteBatch::VK_PointSpriteBatch ( VK_PointSpriteBatch && )

delete

Member Function Documentation

◆ capacity()

size_t mxvk::VK_PointSpriteBatch::capacity ( ) const

inlinenodiscard

Returns: Maximum number of vertices accepted by upload_vertices().

Definition at line 139 of file mxvk_point_sprite_batch.hpp.

139{ return max_vertices; }

◆ cleanup()

void mxvk::VK_PointSpriteBatch::cleanup ( )

Destroy all owned resources and reset the batch to an unloaded state.

Definition at line 78 of file mxvk_point_sprite_batch.cpp.

                                      {
        cleanup_swapchain_resources();
        destroy_vertex_buffer();
        destroy_texture(context.device, texture);
        context = {};
        pipeline_cache = VK_NULL_HANDLE;
        color_attachment_format = VK_FORMAT_UNDEFINED;
        depth_attachment_format = VK_FORMAT_UNDEFINED;
        image_count = 0;
        texture_path.clear();
        vertex_shader_path.clear();
        fragment_shader_path.clear();
        max_vertices = 0;
        active_vertices = 0;
        batch_loaded = false;
    }

◆ load()

void mxvk::VK_PointSpriteBatch::load	(	VK_Window *	window,
		const std::string &	texture_path,
		const std::string &	vertex_shader_path,
		const std::string &	fragment_shader_path,
		size_t	max_vertices )

Create texture, vertex buffer, descriptors, and point-list pipeline.

Parameters

window	Active MXVK window with ready swapchain/render resources.
texture_path	PNG texture sampled by the fragment shader.
vertex_shader_path	SPIR-V vertex shader path.
fragment_shader_path	SPIR-V fragment shader path.
max_vertices	Maximum number of point vertices the batch can draw.

Exceptions

mxvk::Exception on invalid input or Vulkan resource failure.

Definition at line 18 of file mxvk_point_sprite_batch.cpp.

                                                            {
        if (window == nullptr) {
            throw mxvk::Exception("VK_PointSpriteBatch::load called with null window");
        }
        if (max_vertex_count == 0) {
            throw mxvk::Exception("VK_PointSpriteBatch::load requires non-zero vertex capacity");
        }
 
        cleanup();
        context = {
            .device = window->getDevice(),
            .physical_device = window->getPhysicalDevice(),
            .graphics_queue = window->getGraphicsQueue(),
            .command_pool = window->getCommandPool(),
        };
        pipeline_cache = window->getPipelineCache();
        color_attachment_format = window->getSwapchainFormat();
        depth_attachment_format = window->getDepthFormat();
        image_count = window->getSwapchainImageCount();
        texture_path = texture_path_value;
        vertex_shader_path = vertex_shader_path_value;
        fragment_shader_path = fragment_shader_path_value;
        max_vertices = max_vertex_count;
 
        if (context.device == VK_NULL_HANDLE || context.physical_device == VK_NULL_HANDLE ||
            context.graphics_queue == VK_NULL_HANDLE || context.command_pool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create point-sprite batch before Vulkan render resources are available");
        }
        if (color_attachment_format == VK_FORMAT_UNDEFINED || image_count == 0) {
            throw mxvk::Exception("Cannot create point-sprite batch before swapchain resources are available");
        }
 
        create_texture_from_png(context, texture_path, texture);
        create_vertex_buffer();
        create_swapchain_resources();
        batch_loaded = true;
    }

◆ loaded()

bool mxvk::VK_PointSpriteBatch::loaded ( ) const

inlinenodiscard

Returns: true when load() has completed successfully.

Definition at line 137 of file mxvk_point_sprite_batch.hpp.

137{ return batch_loaded; }

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

VK_PointSpriteBatch & mxvk::VK_PointSpriteBatch::operator= ( VK_PointSpriteBatch && )

delete

◆ render()

void mxvk::VK_PointSpriteBatch::render	(	VkCommandBuffer	cmd,
		uint32_t	image_index )

Record point-sprite draw commands into an active rendering scope.

Parameters

cmd	Command buffer in recording state inside MXVK dynamic rendering.
image_index	Current swapchain image index.

Definition at line 118 of file mxvk_point_sprite_batch.cpp.

                                                                              {
        if (!batch_loaded || active_vertices == 0 || pipeline == VK_NULL_HANDLE || image_index >= descriptor_sets.size()) {
            return;
        }
 
        vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline);
        VkBuffer buffers[] = {vertex_buffer.buffer};
        VkDeviceSize offsets[] = {0};
        vkCmdBindVertexBuffers(cmd, 0, 1, buffers, offsets);
        vkCmdBindDescriptorSets(
            cmd,
            VK_PIPELINE_BIND_POINT_GRAPHICS,
            pipeline_layout,
            0,
            1,
            &descriptor_sets[image_index],
            0,
            nullptr);
        vkCmdDraw(cmd, static_cast<uint32_t>(active_vertices), 1, 0, 0);
    }

◆ resize()

void mxvk::VK_PointSpriteBatch::resize ( VK_Window * window )

Recreate swapchain-dependent resources after a window resize.

Parameters

window Active MXVK window with recreated swapchain resources.

Definition at line 60 of file mxvk_point_sprite_batch.cpp.

                                                      {
        if (!batch_loaded || window == nullptr) {
            return;
        }
 
        context.device = window->getDevice();
        context.physical_device = window->getPhysicalDevice();
        context.graphics_queue = window->getGraphicsQueue();
        context.command_pool = window->getCommandPool();
        pipeline_cache = window->getPipelineCache();
        color_attachment_format = window->getSwapchainFormat();
        depth_attachment_format = window->getDepthFormat();
        image_count = window->getSwapchainImageCount();
 
        cleanup_swapchain_resources();
        create_swapchain_resources();
    }

◆ set_additive_blending()

void mxvk::VK_PointSpriteBatch::set_additive_blending ( bool enabled )

Select additive or alpha-over color blending.

Parameters

enabled true for additive blending, false for alpha blending.

Definition at line 139 of file mxvk_point_sprite_batch.cpp.

                                                                {
        if (additive_blending == enabled) {
            return;
        }
        additive_blending = enabled;
        if (batch_loaded) {
            destroy_pipeline();
            create_pipeline();
        }
    }

◆ set_depth_test_enabled()

void mxvk::VK_PointSpriteBatch::set_depth_test_enabled ( bool enabled )

Enable or disable depth testing in the point-sprite pipeline.

Parameters

enabled true to test against the depth attachment.

Definition at line 150 of file mxvk_point_sprite_batch.cpp.

                                                                 {
        if (depth_test_enabled == enabled) {
            return;
        }
        depth_test_enabled = enabled;
        if (batch_loaded) {
            destroy_pipeline();
            create_pipeline();
        }
    }

◆ set_depth_write_enabled()

void mxvk::VK_PointSpriteBatch::set_depth_write_enabled ( bool enabled )

Enable or disable depth writes in the point-sprite pipeline.

Parameters

enabled true to write point depth values.

Definition at line 161 of file mxvk_point_sprite_batch.cpp.

                                                                  {
        if (depth_write_enabled == enabled) {
            return;
        }
        depth_write_enabled = enabled;
        if (batch_loaded) {
            destroy_pipeline();
            create_pipeline();
        }
    }

◆ update_mvp()

void mxvk::VK_PointSpriteBatch::update_mvp	(	uint32_t	image_index,
		const glm::mat4 &	mvp )

Update the MVP uniform for one swapchain image.

Parameters

image_index	Current swapchain image index.
mvp	Model-view-projection transform consumed by the vertex shader.

Definition at line 108 of file mxvk_point_sprite_batch.cpp.

                                                                                 {
        if (image_index >= uniform_buffers.size() || uniform_buffers[image_index].mapped == nullptr) {
            return;
        }
 
        UniformBufferObject ubo{};
        ubo.mvp = mvp;
        std::memcpy(uniform_buffers[image_index].mapped, &ubo, sizeof(ubo));
    }

◆ upload_vertices()

void mxvk::VK_PointSpriteBatch::upload_vertices	(	const PointSpriteVertex *	vertices,
		size_t	count )

Copy point vertices into the persistent mapped vertex buffer.

Parameters

vertices	Pointer to `count` vertices. May be nullptr only when count is zero.
count	Number of vertices to upload and draw.

Exceptions

mxvk::Exception if count exceeds capacity().

Definition at line 95 of file mxvk_point_sprite_batch.cpp.

                                                                                             {
        if (!batch_loaded || vertex_buffer.mapped == nullptr || vertices == nullptr || count == 0) {
            active_vertices = 0;
            return;
        }
        if (count > max_vertices) {
            throw mxvk::Exception("VK_PointSpriteBatch::upload_vertices exceeds batch capacity");
        }
 
        std::memcpy(vertex_buffer.mapped, vertices, count * sizeof(PointSpriteVertex));
        active_vertices = count;
    }

◆ vertex_count()

size_t mxvk::VK_PointSpriteBatch::vertex_count ( ) const

inlinenodiscard

Returns: Number of vertices that will be drawn by render().

Definition at line 141 of file mxvk_point_sprite_batch.hpp.

141{ return active_vertices; }

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

mxvk/include/mxvk/mxvk_point_sprite_batch.hpp
mxvk/src/mxvk_point_sprite_batch.cpp

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ VK_PointSpriteBatch() [1/3]

◆ ~VK_PointSpriteBatch()

◆ VK_PointSpriteBatch() [2/3]

◆ VK_PointSpriteBatch() [3/3]

Member Function Documentation

◆ capacity()

◆ cleanup()

◆ load()

◆ loaded()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ render()

◆ resize()

◆ set_additive_blending()

◆ set_depth_test_enabled()

◆ set_depth_write_enabled()

◆ update_mvp()

◆ upload_vertices()

◆ vertex_count()