mxvk::VK_PointSpriteBatch Class Reference

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 135 of file mxvk_point_sprite_batch.hpp.

{ return max_vertices; }

cleanup()

void mxvk::VK_PointSpriteBatch::cleanup

(

)

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

Definition at line 71 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 16 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 133 of file mxvk_point_sprite_batch.hpp.

{ 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 111 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 53 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 124 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 135 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 146 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 101 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 88 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 137 of file mxvk_point_sprite_batch.hpp.

{ 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