Depth-tested 3D billboard sprite batch. More...

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

Public Member Functions
void	cleanup ()
	Destroy all owned Vulkan resources.
void	clearQueue ()
	Discard all queued sprite draws without rendering them.
void	drawSprite (const glm::vec3 &position, const glm::vec2 &size, const glm::vec4 &color=glm::vec4(1.0f), float rotationRadians=0.0f)
	Queue a billboard sprite for rendering.
int	getHeight () const
int	getWidth () const
void	load (VK_Window *window, const std::string &pngPath, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Load sprite texture and build the 3D billboard pipeline from a PNG file.
void	load (VK_Window window, SDL_Surface surface, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Load sprite texture and build the 3D billboard pipeline from an SDL surface.
bool	loaded () const
VK_Sprite3D &	operator= (const VK_Sprite3D &)=delete
VK_Sprite3D &	operator= (VK_Sprite3D &&)=delete
void	render (VkCommandBuffer cmd, uint32_t imageIndex)
	Record all queued billboard draws into the given command buffer.
void	resize (VK_Window *window)
	Rebuild swapchain-dependent resources after resize.
void	setAlphaDiscardThreshold (float threshold)
	Set the alpha threshold used to discard transparent texels.
void	setDepthTestEnabled (bool enabled)
	Enable or disable depth testing for the 3D sprite pipeline.
void	setDepthWriteEnabled (bool enabled)
	Enable or disable depth writes for the 3D sprite pipeline.
void	updateCamera (uint32_t imageIndex, const glm::mat4 &view, const glm::mat4 &proj)
	Upload the current camera matrices for one swapchain image.
	VK_Sprite3D ()=default
	Construct an empty 3D sprite batch.
	VK_Sprite3D (const VK_Sprite3D &)=delete
	VK_Sprite3D (VK_Sprite3D &&)=delete
	~VK_Sprite3D ()
	Destroy owned Vulkan resources.

Detailed Description

Depth-tested 3D billboard sprite batch.

VK_Sprite3D renders textured quads in world space. Each queued sprite is camera-facing, uses the view/projection matrix supplied with updateCamera(), and participates in the same dynamic-rendering pass as models.

Definition at line 33 of file mxvk_sprite3d.hpp.

Constructor & Destructor Documentation

◆ VK_Sprite3D() [1/3]

mxvk::VK_Sprite3D::VK_Sprite3D ( )

default

Construct an empty 3D sprite batch.

◆ ~VK_Sprite3D()

mxvk::VK_Sprite3D::~VK_Sprite3D ( )

Destroy owned Vulkan resources.

Definition at line 30 of file mxvk_sprite3d.cpp.

30{ cleanup(); }

mxvk::VK_Sprite3D::cleanup

void cleanup()

Destroy all owned Vulkan resources.

Definition mxvk_sprite3d.cpp:176

◆ VK_Sprite3D() [2/3]

mxvk::VK_Sprite3D::VK_Sprite3D ( const VK_Sprite3D & )

delete

◆ VK_Sprite3D() [3/3]

mxvk::VK_Sprite3D::VK_Sprite3D ( VK_Sprite3D && )

delete

Member Function Documentation

◆ cleanup()

void mxvk::VK_Sprite3D::cleanup ( )

Destroy all owned Vulkan resources.

Definition at line 176 of file mxvk_sprite3d.cpp.

                              {
        if (device != VK_NULL_HANDLE) {
            vkDeviceWaitIdle(device);
        }
        drawQueue.clear();
        destroyPipeline();
        destroyDescriptors();
        destroyCameraBuffers();
        destroyBuffers();
        destroyTexture();
 
        device = VK_NULL_HANDLE;
        physicalDevice = VK_NULL_HANDLE;
        graphicsQueue = VK_NULL_HANDLE;
        commandPool = VK_NULL_HANDLE;
        colorAttachmentFormat = VK_FORMAT_UNDEFINED;
        depthAttachmentFormat = VK_FORMAT_UNDEFINED;
        imageCount = 0;
        spriteLoaded = false;
    }

◆ clearQueue()

void mxvk::VK_Sprite3D::clearQueue ( )

Discard all queued sprite draws without rendering them.

Definition at line 132 of file mxvk_sprite3d.cpp.

132{ drawQueue.clear(); }

◆ drawSprite()

void mxvk::VK_Sprite3D::drawSprite	(	const glm::vec3 &	position,
		const glm::vec2 &	size,
		const glm::vec4 &	color = glm::vec4(1.0f),
		float	rotationRadians = 0.0f )

Queue a billboard sprite for rendering.

Parameters

position	World-space center position.
size	Billboard size in world units.
color	Per-sprite tint color.
rotationRadians	Rotation around the camera-facing axis.

Definition at line 93 of file mxvk_sprite3d.cpp.

                                                                                                                          {
        if (!spriteLoaded) {
            throw mxvk::Exception("VK_Sprite3D::drawSprite called before sprite was loaded");
        }
        if (size.x <= 0.0f || size.y <= 0.0f) {
            return;
        }
        drawQueue.push_back({position, size, color, rotationRadians});
    }

◆ getHeight()

int mxvk::VK_Sprite3D::getHeight ( ) const

inlinenodiscard

Returns: Sprite texture height in pixels.

Definition at line 131 of file mxvk_sprite3d.hpp.

131{ return spriteHeight; }

◆ getWidth()

int mxvk::VK_Sprite3D::getWidth ( ) const

inlinenodiscard

Returns: Sprite texture width in pixels.

Definition at line 129 of file mxvk_sprite3d.hpp.

129{ return spriteWidth; }

◆ load() [1/2]

void mxvk::VK_Sprite3D::load	(	VK_Window *	window,
		const std::string &	pngPath,
		const std::string &	vertexShaderPath = "",
		const std::string &	fragmentShaderPath = "" )

Load sprite texture and build the 3D billboard pipeline from a PNG file.

Parameters

window	Active MXVK window.
pngPath	Path to the PNG file.
vertexShaderPath	Optional custom vertex shader SPIR-V path.
fragmentShaderPath	Optional custom fragment shader SPIR-V path.

Definition at line 32 of file mxvk_sprite3d.cpp.

                                                                                                                                  {
        SDL_Surface *surface = mxvk::LoadPNG(pngPath.c_str());
        if (surface == nullptr) {
            throw mxvk::Exception("Failed to load 3D sprite image: " + pngPath);
        }
        load(window, surface, vertexPath, fragmentPath);
        SDL_DestroySurface(surface);
        std::cout << std::format("mxvk: Loaded 3D sprite PNG: {}\n", pngPath);
    }

◆ load() [2/2]

void mxvk::VK_Sprite3D::load	(	VK_Window *	window,
		SDL_Surface *	surface,
		const std::string &	vertexShaderPath = "",
		const std::string &	fragmentShaderPath = "" )

Load sprite texture and build the 3D billboard pipeline from an SDL surface.

Parameters

window	Active MXVK window.
surface	Source surface pointer.
vertexShaderPath	Optional custom vertex shader SPIR-V path.
fragmentShaderPath	Optional custom fragment shader SPIR-V path.

Definition at line 42 of file mxvk_sprite3d.cpp.

                                                                                                                              {
        if (window == nullptr) {
            throw mxvk::Exception("VK_Sprite3D::load called with null window");
        }
        if (surface == nullptr) {
            throw mxvk::Exception("VK_Sprite3D::load called with null surface");
        }
 
        cleanup();
 
        device = window->getDevice();
        physicalDevice = window->getPhysicalDevice();
        graphicsQueue = window->getGraphicsQueue();
        commandPool = window->getCommandPool();
        pipelineCache = window->getPipelineCache();
        colorAttachmentFormat = window->getSwapchainFormat();
        depthAttachmentFormat = window->getDepthFormat();
        imageCount = window->getSwapchainImageCount();
        vertexShaderPath = vertexPath.empty() ? (std::filesystem::path(MXVK_SPRITE3D_SHADER_DIR) / "sprite3d.vert.spv").string() : vertexPath;
        fragmentShaderPath = fragmentPath.empty() ? (std::filesystem::path(MXVK_SPRITE3D_SHADER_DIR) / "sprite3d.frag.spv").string() : fragmentPath;
 
        if (device == VK_NULL_HANDLE || physicalDevice == VK_NULL_HANDLE || graphicsQueue == VK_NULL_HANDLE || commandPool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create 3D sprite before Vulkan render resources are available");
        }
        if (colorAttachmentFormat == VK_FORMAT_UNDEFINED || imageCount == 0) {
            throw mxvk::Exception("Cannot create 3D sprite before swapchain resources are available");
        }
 
        createTexture(surface);
        createSampler();
        createQuadBuffers();
        createDescriptorSetLayout();
        createCameraBuffers();
        createDescriptorPool();
        createDescriptorSets();
        createPipeline();
        spriteLoaded = true;
        std::cout << std::format("mxvk: Created 3D sprite: {}x{}\n", spriteWidth, spriteHeight);
    }

◆ loaded()

bool mxvk::VK_Sprite3D::loaded ( ) const

inlinenodiscard

Returns: true if the sprite texture and pipeline are loaded.

Definition at line 127 of file mxvk_sprite3d.hpp.

127{ return spriteLoaded; }

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

VK_Sprite3D & mxvk::VK_Sprite3D::operator= ( VK_Sprite3D && )

delete

◆ render()

void mxvk::VK_Sprite3D::render	(	VkCommandBuffer	cmd,
		uint32_t	imageIndex )

Record all queued billboard draws into the given command buffer.

Parameters

cmd	Active command buffer.
imageIndex	Current swapchain image index.

Definition at line 103 of file mxvk_sprite3d.cpp.

                                                                     {
        if (!spriteLoaded || drawQueue.empty() || imageIndex >= descriptorSets.size()) {
            return;
        }
 
        vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline);
        vkCmdBindDescriptorSets(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, pipelineLayout, 0, 1, &descriptorSets[imageIndex], 0, nullptr);
 
        VkBuffer vertexBuffers[] = {vertexBuffer};
        VkDeviceSize offsets[] = {0};
        vkCmdBindVertexBuffers(cmd, 0, 1, vertexBuffers, offsets);
        vkCmdBindIndexBuffer(cmd, indexBuffer, 0, VK_INDEX_TYPE_UINT16);
 
        struct PushConstants {
            glm::vec4 positionSizeX;
            glm::vec4 color;
            glm::vec4 sizeYRotationAlpha;
        };
 
        for (const DrawCmd &draw : drawQueue) {
            PushConstants pc{};
            pc.positionSizeX = glm::vec4(draw.position, draw.size.x);
            pc.color = draw.color;
            pc.sizeYRotationAlpha = glm::vec4(draw.size.y, draw.rotationRadians, alphaDiscardThreshold, 0.0f);
            vkCmdPushConstants(cmd, pipelineLayout, VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT, 0, sizeof(PushConstants), &pc);
            vkCmdDrawIndexed(cmd, 6, 1, 0, 0, 0);
        }
    }

◆ resize()

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

Rebuild swapchain-dependent resources after resize.

Parameters

window Active MXVK window.

Definition at line 154 of file mxvk_sprite3d.cpp.

                                              {
        if (window == nullptr || !spriteLoaded) {
            return;
        }
 
        colorAttachmentFormat = window->getSwapchainFormat();
        depthAttachmentFormat = window->getDepthFormat();
        const size_t newImageCount = window->getSwapchainImageCount();
 
        if (newImageCount != imageCount) {
            imageCount = newImageCount;
            destroyDescriptors();
            destroyCameraBuffers();
            createDescriptorSetLayout();
            createCameraBuffers();
            createDescriptorPool();
            createDescriptorSets();
        }
 
        createPipeline();
    }

◆ setAlphaDiscardThreshold()

void mxvk::VK_Sprite3D::setAlphaDiscardThreshold ( float threshold )

inline

Set the alpha threshold used to discard transparent texels.

Parameters

threshold Alpha cutoff value.

Definition at line 113 of file mxvk_sprite3d.hpp.

113{ alphaDiscardThreshold = threshold; }

◆ setDepthTestEnabled()

void mxvk::VK_Sprite3D::setDepthTestEnabled ( bool enabled )

Enable or disable depth testing for the 3D sprite pipeline.

Parameters

enabled true to enable depth testing.

Definition at line 134 of file mxvk_sprite3d.cpp.

                                                      {
        if (depthTestEnabled == enabled) {
            return;
        }
        depthTestEnabled = enabled;
        if (spriteLoaded) {
            createPipeline();
        }
    }

◆ setDepthWriteEnabled()

void mxvk::VK_Sprite3D::setDepthWriteEnabled ( bool enabled )

Enable or disable depth writes for the 3D sprite pipeline.

Parameters

enabled true to write depth values.

Definition at line 144 of file mxvk_sprite3d.cpp.

                                                       {
        if (depthWriteEnabled == enabled) {
            return;
        }
        depthWriteEnabled = enabled;
        if (spriteLoaded) {
            createPipeline();
        }
    }

◆ updateCamera()

void mxvk::VK_Sprite3D::updateCamera	(	uint32_t	imageIndex,
		const glm::mat4 &	view,
		const glm::mat4 &	proj )

Upload the current camera matrices for one swapchain image.

Parameters

imageIndex	Swapchain image index.
view	View matrix.
proj	Projection matrix.

Definition at line 82 of file mxvk_sprite3d.cpp.

                                                                                                {
        if (imageIndex >= cameraBuffersMapped.size() || cameraBuffersMapped[imageIndex] == nullptr) {
            return;
        }
 
        CameraUBO camera{};
        camera.view = view;
        camera.proj = proj;
        std::memcpy(cameraBuffersMapped[imageIndex], &camera, sizeof(camera));
    }

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

mxvk/include/mxvk/mxvk_sprite3d.hpp
mxvk/src/mxvk_sprite3d.cpp

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ VK_Sprite3D() [1/3]

◆ ~VK_Sprite3D()

◆ VK_Sprite3D() [2/3]

◆ VK_Sprite3D() [3/3]

Member Function Documentation

◆ cleanup()

◆ clearQueue()

◆ drawSprite()

◆ getHeight()

◆ getWidth()

◆ load() [1/2]

◆ load() [2/2]

◆ loaded()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ render()

◆ resize()

◆ setAlphaDiscardThreshold()

◆ setDepthTestEnabled()

◆ setDepthWriteEnabled()

◆ updateCamera()