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

Public Member Functions
void	clearExternalTextureDescriptors ()
void	clearQueue ()
	Discard all pending draw commands without rendering.
void	createEmptySprite (int width, int height, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Create a blank (un-initialised) sprite texture.
void	drawSprite (int x, int y)
	Queue a draw at the given pixel position.
void	drawSprite (int x, int y, float scaleX, float scaleY)
	Queue a scaled draw.
void	drawSprite (int x, int y, float scaleX, float scaleY, float rotation)
	Queue a scaled and rotated draw.
void	drawSpriteRect (int x, int y, int w, int h)
	Queue a draw into an explicit destination rectangle.
void	enableExtendedUBO ()
	Allocate and initialise the extended uniform buffer object.
void	enableInstancing (uint32_t maxInstances, const std::string &instanceVertShaderPath, const std::string &instanceFragShaderPath)
	Enable GPU instancing for this sprite type.
bool	getEffectsEnabled () const
int	getHeight () const
VkPipeline	getPipeline () const
VkPipelineLayout	getPipelineLayout () const
int	getWidth () const
bool	hasOwnPipeline () const
bool	isExtendedUBOEnabled () const
bool	isInstancingEnabled () const
void	loadSprite (const std::string &pngPath, const std::string &fragmentShaderPath="")
	Load sprite texture from a PNG file.
void	loadSprite (SDL_Surface *surface, const std::string &fragmentShaderPath="")
	Load sprite texture from an SDL_Surface.
VK_Sprite &	operator= (const VK_Sprite &)=delete
VK_Sprite &	operator= (VK_Sprite &&)=delete
void	prepareForRendering (VkCommandBuffer cmdBuffer)
	Record texture barriers that must happen before dynamic rendering begins.
void	rebuildInstancedPipeline ()
	Destroy and recreate the instanced graphics pipeline.
void	rebuildPipeline ()
	Destroy and recreate the custom graphics pipeline.
void	releaseUploadResources ()
	Release upload/staging resources tied to the current command pool.
void	renderSprites (VkCommandBuffer cmdBuffer, VkPipelineLayout pipelineLayout, uint32_t screenWidth, uint32_t screenHeight)
	Record all queued draw commands into the given command buffer.
void	setColorAttachmentFormat (VkFormat format)
	Assign dynamic-rendering color attachment format used to build pipelines.
void	setCommandPool (VkCommandPool pool)
	Rebind the command pool used for upload/staging operations.
void	setDepthAttachmentFormat (VkFormat format)
	Assign dynamic-rendering depth attachment format used to build pipelines.
void	setDescriptorSetLayout (VkDescriptorSetLayout layout)
	Assign an external descriptor-set layout.
void	setEffectsEnabled (bool enabled)
	Enable or disable the custom fragment shader effects.
void	setExternalTexture (VkImageView image_view, int width, int height)
void	setFragmentShaderPath (const std::string &path)
	Replace the fragment shader path and rebuild the custom pipeline.
void	setMouseState (float mx, float my, float pressed, float reserved=0.0f)
	Upload mouse state to the extended UBO.
void	setPipelineCache (VkPipelineCache cache)
	Use the shared pipeline cache for custom/instanced pipeline creation.
void	setRenderPass (VkRenderPass rp)
	Assign the render pass used to build the custom pipeline.
void	setShaderParams (float p1=0.0f, float p2=0.0f, float p3=0.0f, float p4=0.0f)
	Set up to four custom shader float parameters.
void	setTextureFilter (VkFilter filter)
	Select the hardware filter used when scaling this sprite.
void	setUniform0 (float x, float y, float z, float w)
	Upload user uniform 0 to the extended UBO.
void	setUniform1 (float x, float y, float z, float w)
	Upload user uniform 1 to the extended UBO.
void	setUniform2 (float x, float y, float z, float w)
	Upload user uniform 2 to the extended UBO.
void	setUniform3 (float x, float y, float z, float w)
	Upload user uniform 3 to the extended UBO.
void	setVertexShaderPath (const std::string &path)
	Override the vertex shader path (used when rebuilding the pipeline).
void	updateTexture (const void *pixels, int width, int height, int pitch=0)
	Replace the sprite texture from a raw pixel buffer.
void	updateTexture (SDL_Surface *surface)
	Replace the sprite texture from an SDL_Surface.
	VK_Sprite (const VK_Sprite &)=delete
	VK_Sprite (VK_Sprite &&)=delete
	VK_Sprite (VkDevice device, VkPhysicalDevice physicalDevice, VkQueue graphicsQueue, VkCommandPool commandPool)
	Construct and record Vulkan context handles.
	~VK_Sprite ()
	Destructor — frees all Vulkan resources.

Public Attributes
VkSampler	spriteSampler = VK_NULL_HANDLE
	Texture sampler.

Detailed Description

Definition at line 56 of file mxvk_sprite.hpp.

Constructor & Destructor Documentation

◆ VK_Sprite() [1/3]

mxvk::VK_Sprite::VK_Sprite	(	VkDevice	device,
		VkPhysicalDevice	physicalDevice,
		VkQueue	graphicsQueue,
		VkCommandPool	commandPool )

Construct and record Vulkan context handles.

Parameters

device	Logical device.
physicalDevice	Physical device.
graphicsQueue	Graphics queue.
commandPool	Command pool for staging operations.

Definition at line 18 of file mxvk_sprite.cpp.

        : device(dev), physicalDevice(physDev), graphicsQueue(gQueue), commandPool(cmdPool) {
        std::cout << "mxvk: Created Sprite\n";
    }

◆ ~VK_Sprite()

mxvk::VK_Sprite::~VK_Sprite ( )

Destructor — frees all Vulkan resources.

Definition at line 58 of file mxvk_sprite.cpp.

                          {
        vkDeviceWaitIdle(device);
        drawQueue.clear();
 
        destroyStagingResources();
#ifdef MXVK_CUDA
        destroyCudaInterop();
#endif
        if (quadVertexBuffer != VK_NULL_HANDLE) {
            std::cout << "vk: destroying sprite quad vertex buffer\n";
            vkDestroyBuffer(device, quadVertexBuffer, nullptr);
            vkFreeMemory(device, quadVertexBufferMemory, nullptr);
        }
        if (quadIndexBuffer != VK_NULL_HANDLE) {
            std::cout << "vk: destroying sprite quad index buffer\n";
            vkDestroyBuffer(device, quadIndexBuffer, nullptr);
            vkFreeMemory(device, quadIndexBufferMemory, nullptr);
        }
 
        destroyTextureDescriptorPools();
 
        if (spriteSampler != VK_NULL_HANDLE) {
            std::cout << "vk: destroying sprite sampler\n";
            vkDestroySampler(device, spriteSampler, nullptr);
        }
 
        if (!externalTexture && spriteImageView != VK_NULL_HANDLE) {
            std::cout << "vk: destroying sprite image view\n";
            vkDestroyImageView(device, spriteImageView, nullptr);
        }
 
        if (!externalTexture && spriteImage != VK_NULL_HANDLE) {
            std::cout << "vk: destroying sprite image\n";
            vkDestroyImage(device, spriteImage, nullptr);
            vkFreeMemory(device, spriteImageMemory, nullptr);
        }
 
        if (fragmentShaderModule != VK_NULL_HANDLE) {
            vkDestroyShaderModule(device, fragmentShaderModule, nullptr);
        }
 
        if (customPipeline != VK_NULL_HANDLE) {
            std::cout << "vk: destroying sprite custom pipeline\n";
            vkDestroyPipeline(device, customPipeline, nullptr);
        }
 
        if (customPipelineLayout != VK_NULL_HANDLE) {
            std::cout << "vk: destroying sprite custom pipeline layout\n";
            vkDestroyPipelineLayout(device, customPipelineLayout, nullptr);
        }
 
        destroyExtendedUBO();
        destroyInstanceResources();
    }

◆ VK_Sprite() [2/3]

mxvk::VK_Sprite::VK_Sprite ( const VK_Sprite & )

delete

◆ VK_Sprite() [3/3]

mxvk::VK_Sprite::VK_Sprite ( VK_Sprite && )

delete

Member Function Documentation

◆ clearExternalTextureDescriptors()

void mxvk::VK_Sprite::clearExternalTextureDescriptors ( )

Definition at line 1712 of file mxvk_sprite.cpp.

                                                    {
        if (!externalTexture && externalDescriptorSets.empty()) {
            return;
        }
        destroyTextureDescriptorPools();
    }

◆ clearQueue()

void mxvk::VK_Sprite::clearQueue ( )

Discard all pending draw commands without rendering.

Definition at line 1818 of file mxvk_sprite.cpp.

                               {
        drawQueue.clear();
    }

◆ createEmptySprite()

void mxvk::VK_Sprite::createEmptySprite	(	int	width,
		int	height,
		const std::string &	vertexShaderPath = "",
		const std::string &	fragmentShaderPath = "" )

Create a blank (un-initialised) sprite texture.

Parameters

width	Pixel width.
height	Pixel height.
vertexShaderPath	Optional vertex shader.
fragmentShaderPath	Optional fragment shader.

Definition at line 911 of file mxvk_sprite.cpp.

                                                                                                                                   {
        if (width <= 0 || height <= 0) {
            throw mxvk::Exception("VKSprite::createEmptySprite invalid dimensions");
        }
        if (spriteLoaded || spriteImage != VK_NULL_HANDLE || fragmentShaderModule != VK_NULL_HANDLE) {
            destroySpriteResources();
        }
        spriteWidth = width;
        spriteHeight = height;
 
        if (!vertexShaderPath.empty()) {
            setVertexShaderPath(vertexShaderPath);
        }
 
#ifdef MXVK_CUDA
        try {
            createCudaExportableImage(width, height, spriteImage, spriteImageMemory);
        } catch (const std::exception &ex) {
            std::cout << std::format("mxvk: CUDA exportable sprite image unavailable: {}; using standard Vulkan image\n", ex.what());
            createImage(width, height, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_TILING_OPTIMAL,
                        VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_SAMPLED_BIT,
                        VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT, spriteImage, spriteImageMemory);
        }
#else
        createImage(width, height, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_TILING_OPTIMAL,
                    VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_SAMPLED_BIT,
                    VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT, spriteImage, spriteImageMemory);
#endif
 
        VkBuffer stagingBuffer = VK_NULL_HANDLE;
        VkDeviceMemory stagingMemory = VK_NULL_HANDLE;
        VkDeviceSize imageSize = static_cast<VkDeviceSize>(width) * height * 4;
 
        createBuffer(imageSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT,
                     VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                     stagingBuffer, stagingMemory);
 
        void *data;
        VK_CHECK_RESULT(vkMapMemory(device, stagingMemory, 0, imageSize, 0, &data));
        memset(data, 0, imageSize);
        vkUnmapMemory(device, stagingMemory);
 
        transitionImageLayout(spriteImage, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);
        copyBufferToImage(stagingBuffer, spriteImage, width, height);
        transitionImageLayout(spriteImage, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
#ifdef MXVK_CUDA
        cudaImageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
#endif
 
        vkDestroyBuffer(device, stagingBuffer, nullptr);
        vkFreeMemory(device, stagingMemory, nullptr);
 
        spriteImageView = createImageView(spriteImage, VK_FORMAT_R8G8B8A8_UNORM);
        createSampler();
        createQuadBuffer();
        createDescriptorPool();
 
        createStagingResources(imageSize);
 
        if (!fragmentShaderPath.empty()) {
            auto shaderCode = readShaderFile(fragmentShaderPath);
            fragmentShaderModule = mxvk::create_shader_module(device, shaderCode);
            hasCustomShader = true;
            this->fragmentShaderPath = fragmentShaderPath;
 
            if (colorAttachmentFormat != VK_FORMAT_UNDEFINED && descriptorSetLayout != VK_NULL_HANDLE) {
                createCustomPipeline();
            }
        }
 
        spriteLoaded = true;
        std::cout << std::format("mxvk: Created empty sprite: {}x{}\n", spriteWidth, spriteHeight);
    }

◆ drawSprite() [1/3]

void mxvk::VK_Sprite::drawSprite	(	int	x,
		int	y )

Queue a draw at the given pixel position.

Parameters

x	Destination X.
y	Destination Y.

Definition at line 1641 of file mxvk_sprite.cpp.

                                           {
        drawSpriteRect(x, y, spriteWidth, spriteHeight);
    }

◆ drawSprite() [2/3]

void mxvk::VK_Sprite::drawSprite	(	int	x,
		int	y,
		float	scaleX,
		float	scaleY )

Queue a scaled draw.

Parameters

x	Destination X.
y	Destination Y.
scaleX	Horizontal scale factor.
scaleY	Vertical scale factor.

Definition at line 1645 of file mxvk_sprite.cpp.

                                                                       {
        drawSpriteRect(x, y, static_cast<int>(spriteWidth * scaleX), static_cast<int>(spriteHeight * scaleY));
    }

◆ drawSprite() [3/3]

void mxvk::VK_Sprite::drawSprite	(	int	x,
		int	y,
		float	scaleX,
		float	scaleY,
		float	rotation )

Queue a scaled and rotated draw.

Parameters

x	Destination X.
y	Destination Y.
scaleX	Horizontal scale.
scaleY	Vertical scale.
rotation	Clockwise rotation in degrees.

Definition at line 1649 of file mxvk_sprite.cpp.

                                                                                       {
        if (!spriteLoaded) {
            throw mxvk::Exception("VKSprite::drawSprite called before sprite was loaded");
        }
 
        drawQueue.push_back({static_cast<float>(x), static_cast<float>(y),
                             static_cast<float>(static_cast<int>(spriteWidth * scaleX)),
                             static_cast<float>(static_cast<int>(spriteHeight * scaleY)),
                             rotation, shaderParams});
    }

◆ drawSpriteRect()

void mxvk::VK_Sprite::drawSpriteRect	(	int	x,
		int	y,
		int	w,
		int	h )

Queue a draw into an explicit destination rectangle.

Parameters

x,y,w,h Destination rectangle.

Definition at line 1660 of file mxvk_sprite.cpp.

                                                             {
        if (!spriteLoaded) {
            throw mxvk::Exception("VKSprite::drawSpriteRect called before sprite was loaded");
        }
 
        drawQueue.push_back({static_cast<float>(x), static_cast<float>(y),
                             static_cast<float>(w), static_cast<float>(h), 0.0f, shaderParams});
    }

◆ enableExtendedUBO()

void mxvk::VK_Sprite::enableExtendedUBO ( )

Allocate and initialise the extended uniform buffer object.

Definition at line 165 of file mxvk_sprite.cpp.

                                      {
        if (extendedUBOEnabled)
            return;
        extendedUBOEnabled = true;
        createExtendedUBO();
        createExtendedDescriptorSetLayout();
        rebuildPipeline();
    }

◆ enableInstancing()

void mxvk::VK_Sprite::enableInstancing	(	uint32_t	maxInstances,
		const std::string &	instanceVertShaderPath,
		const std::string &	instanceFragShaderPath )

Enable GPU instancing for this sprite type.

Parameters

maxInstances	Maximum simultaneous instances.
instanceVertShaderPath	Vertex shader supporting instancing.
instanceFragShaderPath	Fragment shader.

Definition at line 453 of file mxvk_sprite.cpp.

                                                                              {
        if (colorAttachmentFormat == VK_FORMAT_UNDEFINED || descriptorSetLayout == VK_NULL_HANDLE) {
            throw mxvk::Exception("VKSprite::enableInstancing called before color format/descriptorSetLayout set");
        }
        ensureInstanceBuffer(maxInstances);
        createQuadBuffer();
        instanceVertPath = instanceVertShaderPath;
        instanceFragPath = instanceFragShaderPath;
        createInstancedPipeline(instanceVertShaderPath, instanceFragShaderPath);
        instancingEnabled = true;
        std::cout << std::format("mxvk: Instancing enabled (max {} instances)\n", maxInstances);
    }

◆ getEffectsEnabled()

bool mxvk::VK_Sprite::getEffectsEnabled ( ) const

inline

Returns: true if shader effects are enabled.

Definition at line 167 of file mxvk_sprite.hpp.

167{ return effectsEnabled; }

◆ getHeight()

int mxvk::VK_Sprite::getHeight ( ) const

inline

Returns: Sprite texture height in pixels.

Definition at line 191 of file mxvk_sprite.hpp.

191{ return spriteHeight; }

◆ getPipeline()

VkPipeline mxvk::VK_Sprite::getPipeline ( ) const

inline

Returns: The custom VkPipeline handle (may be VK_NULL_HANDLE).

Definition at line 229 of file mxvk_sprite.hpp.

229{ return customPipeline; }

◆ getPipelineLayout()

VkPipelineLayout mxvk::VK_Sprite::getPipelineLayout ( ) const

inline

Returns: The custom pipeline layout handle.

Definition at line 231 of file mxvk_sprite.hpp.

231{ return customPipelineLayout; }

◆ getWidth()

int mxvk::VK_Sprite::getWidth ( ) const

inline

Returns: Sprite texture width in pixels.

Definition at line 189 of file mxvk_sprite.hpp.

189{ return spriteWidth; }

◆ hasOwnPipeline()

bool mxvk::VK_Sprite::hasOwnPipeline ( ) const

inline

Returns: true if a custom pipeline has been built.

Definition at line 227 of file mxvk_sprite.hpp.

227{ return customPipeline != VK_NULL_HANDLE; }

◆ isExtendedUBOEnabled()

bool mxvk::VK_Sprite::isExtendedUBOEnabled ( ) const

inline

Returns: true if the extended UBO is active.

Definition at line 257 of file mxvk_sprite.hpp.

257{ return extendedUBOEnabled; }

◆ isInstancingEnabled()

bool mxvk::VK_Sprite::isInstancingEnabled ( ) const

inline

Returns: true if GPU instancing is active.

Definition at line 251 of file mxvk_sprite.hpp.

251{ return instancingEnabled; }

◆ loadSprite() [1/2]

void mxvk::VK_Sprite::loadSprite	(	const std::string &	pngPath,
		const std::string &	fragmentShaderPath = "" )

Load sprite texture from a PNG file.

Parameters

pngPath	Path to the PNG file.
fragmentShaderPath	Optional custom fragment shader (SPIR-V .spv).

Definition at line 870 of file mxvk_sprite.cpp.

                                                                                            {
        SDL_Surface *surface = mxvk::LoadPNG(pngPath.c_str());
        if (!surface) {
            throw mxvk::Exception("Failed to load sprite image: " + pngPath);
        }
        loadSprite(surface, fragmentShaderPath);
        SDL_DestroySurface(surface);
        std::cout << std::format("mxvk: Loaded PNG: {}\n", pngPath);
    }

◆ loadSprite() [2/2]

void mxvk::VK_Sprite::loadSprite	(	SDL_Surface *	surface,
		const std::string &	fragmentShaderPath = "" )

Load sprite texture from an SDL_Surface.

Parameters

surface	Source surface (not consumed).
fragmentShaderPath	Optional custom fragment shader.

Definition at line 880 of file mxvk_sprite.cpp.

                                                                                        {
        if (!surface) {
            throw mxvk::Exception("VKSprite::loadSprite called with null surface");
        }
        if (spriteLoaded || spriteImage != VK_NULL_HANDLE || fragmentShaderModule != VK_NULL_HANDLE) {
            destroySpriteResources();
        }
        SDL_Surface *rgbaSurface = convertToRGBA(surface);
        if (!rgbaSurface) {
            throw mxvk::Exception("Failed to convert sprite surface to RGBA");
        }
        spriteWidth = rgbaSurface->w;
        spriteHeight = rgbaSurface->h;
        createSpriteTexture(rgbaSurface);
        SDL_DestroySurface(rgbaSurface);
        createSampler();
        createQuadBuffer();
        if (!fragmentShaderPath.empty()) {
            auto shaderCode = readShaderFile(fragmentShaderPath);
            fragmentShaderModule = mxvk::create_shader_module(device, shaderCode);
            hasCustomShader = true;
            this->fragmentShaderPath = fragmentShaderPath;
 
            if (colorAttachmentFormat != VK_FORMAT_UNDEFINED && descriptorSetLayout != VK_NULL_HANDLE) {
                createCustomPipeline();
            }
        }
        spriteLoaded = true;
        std::cout << std::format("mxvk: Loaded surface texture: {}x{}\n", spriteWidth, spriteHeight);
    }

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

VK_Sprite & mxvk::VK_Sprite::operator= ( VK_Sprite && )

delete

◆ prepareForRendering()

void mxvk::VK_Sprite::prepareForRendering ( VkCommandBuffer cmdBuffer )

Record texture barriers that must happen before dynamic rendering begins.

Parameters

cmdBuffer Command buffer currently being recorded outside a rendering instance.

Definition at line 1719 of file mxvk_sprite.cpp.

                                                                                  {
#ifdef MXVK_CUDA
        recordCudaReadyBarrier(cmdBuffer);
#endif
    }

◆ rebuildInstancedPipeline()

void mxvk::VK_Sprite::rebuildInstancedPipeline ( )

Destroy and recreate the instanced graphics pipeline.

Definition at line 831 of file mxvk_sprite.cpp.

                                             {
        if (!instancingEnabled || instanceVertPath.empty() || instanceFragPath.empty())
            return;
        createInstancedPipeline(instanceVertPath, instanceFragPath);
    }

◆ rebuildPipeline()

void mxvk::VK_Sprite::rebuildPipeline ( )

Destroy and recreate the custom graphics pipeline.

Definition at line 790 of file mxvk_sprite.cpp.

                                    {
        if (!hasCustomShader || fragmentShaderModule == VK_NULL_HANDLE)
            return;
        createCustomPipeline();
        std::cout << "mxvk: Pipeline rebuilt\n";
    }

◆ releaseUploadResources()

void mxvk::VK_Sprite::releaseUploadResources ( )

Release upload/staging resources tied to the current command pool.

Call this before destroying or recreating the command pool.

Definition at line 23 of file mxvk_sprite.cpp.

                                           {
        destroyStagingResources();
    }

◆ renderSprites()

void mxvk::VK_Sprite::renderSprites	(	VkCommandBuffer	cmdBuffer,
		VkPipelineLayout	pipelineLayout,
		uint32_t	screenWidth,
		uint32_t	screenHeight )

Record all queued draw commands into the given command buffer.

Parameters

cmdBuffer	Active command buffer.
pipelineLayout	Pipeline layout for push constants/descriptors.
screenWidth	Current viewport width.
screenHeight	Current viewport height.

Definition at line 1725 of file mxvk_sprite.cpp.

                                                                               {
        if (drawQueue.empty() || !spriteLoaded || !quadBufferCreated) {
            return;
        }
        if (descriptorSet == VK_NULL_HANDLE) {
            descriptorSet = createDescriptorSet(spriteImageView);
            if (externalTexture) {
                externalDescriptorSets[spriteImageView] = descriptorSet;
            }
        }
 
        if (instancingEnabled && instancedPipeline != VK_NULL_HANDLE && instanceBuffer != VK_NULL_HANDLE) {
            uint32_t instanceCount = static_cast<uint32_t>(drawQueue.size());
 
            if (instanceCount > instanceBufferCapacity) {
                ensureInstanceBuffer(instanceCount * 2);
            }
 
            SpriteInstanceData *dst = static_cast<SpriteInstanceData *>(instanceBufferMapped);
            for (uint32_t i = 0; i < instanceCount; ++i) {
                const auto &cmd = drawQueue[i];
                dst[i].posX = cmd.x;
                dst[i].posY = cmd.y;
                dst[i].sizeW = cmd.w;
                dst[i].sizeH = cmd.h;
                dst[i].params[0] = cmd.params.x;
                dst[i].params[1] = cmd.params.y;
                dst[i].params[2] = cmd.params.z;
                dst[i].params[3] = cmd.params.w;
            }
 
            vkCmdBindPipeline(cmdBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, instancedPipeline);
            vkCmdBindDescriptorSets(cmdBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, instancedPipelineLayout,
                                    0, 1, &descriptorSet, 0, nullptr);
 
            VkBuffer buffers[] = {quadVertexBuffer, instanceBuffer};
            VkDeviceSize bufOffsets[] = {0, 0};
            vkCmdBindVertexBuffers(cmdBuffer, 0, 2, buffers, bufOffsets);
            vkCmdBindIndexBuffer(cmdBuffer, quadIndexBuffer, 0, VK_INDEX_TYPE_UINT16);
 
            float screenSize[2] = {static_cast<float>(screenWidth), static_cast<float>(screenHeight)};
            vkCmdPushConstants(cmdBuffer, instancedPipelineLayout, VK_SHADER_STAGE_VERTEX_BIT,
                               0, sizeof(screenSize), screenSize);
 
            vkCmdDrawIndexed(cmdBuffer, 6, instanceCount, 0, 0, 0);
            return;
        }
 
        VkPipelineLayout layoutToUse = (customPipeline != VK_NULL_HANDLE) ? customPipelineLayout : pipelineLayout;
        if (customPipeline != VK_NULL_HANDLE) {
            vkCmdBindPipeline(cmdBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, customPipeline);
        }
 
        // When extended UBO is enabled, update UBO and bind extended descriptor set
        if (extendedUBOEnabled && customPipeline != VK_NULL_HANDLE) {
            updateExtendedUBO();
            if (extendedDescriptorSet == VK_NULL_HANDLE) {
                createExtendedDescriptorSet();
            }
            vkCmdBindDescriptorSets(cmdBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, layoutToUse,
                                    0, 1, &extendedDescriptorSet, 0, nullptr);
        } else {
            vkCmdBindDescriptorSets(cmdBuffer, VK_PIPELINE_BIND_POINT_GRAPHICS, layoutToUse,
                                    0, 1, &descriptorSet, 0, nullptr);
        }
 
        VkBuffer vertexBuffers[] = {quadVertexBuffer};
        VkDeviceSize offsets[] = {0};
        vkCmdBindVertexBuffers(cmdBuffer, 0, 1, vertexBuffers, offsets);
        vkCmdBindIndexBuffer(cmdBuffer, quadIndexBuffer, 0, VK_INDEX_TYPE_UINT16);
 
        for (const auto &cmd : drawQueue) {
            struct SpritePushConstants {
                float screenWidth;
                float screenHeight;
                float spritePosX;
                float spritePosY;
                float spriteSizeW;
                float spriteSizeH;
                float effectsOn;
                float padding2;
                float params[4];
            } pc{
                static_cast<float>(screenWidth), static_cast<float>(screenHeight), cmd.x, cmd.y, cmd.w, cmd.h, effectsEnabled ? 1.0f : 0.0f, cmd.rotation, {cmd.params.x, cmd.params.y, cmd.params.z, cmd.params.w}};
 
            vkCmdPushConstants(cmdBuffer, layoutToUse, VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT,
                               0, sizeof(SpritePushConstants), &pc);
 
            vkCmdDrawIndexed(cmdBuffer, 6, 1, 0, 0, 0);
        }
    }

◆ setColorAttachmentFormat()

void mxvk::VK_Sprite::setColorAttachmentFormat ( VkFormat format )

inline

Assign dynamic-rendering color attachment format used to build pipelines.

Definition at line 204 of file mxvk_sprite.hpp.

204{ colorAttachmentFormat = format; }

◆ setCommandPool()

void mxvk::VK_Sprite::setCommandPool ( VkCommandPool pool )

Rebind the command pool used for upload/staging operations.

Any in-flight upload resources tied to the previous pool are released first.

Definition at line 27 of file mxvk_sprite.cpp.

                                                     {
        if (pool == commandPool) {
            return;
        }
 
        // uploadCmdBuffer is allocated from commandPool, so it must be released
        // before switching to another pool.
        destroyStagingResources();
        commandPool = pool;
    }

◆ setDepthAttachmentFormat()

void mxvk::VK_Sprite::setDepthAttachmentFormat ( VkFormat format )

inline

Assign dynamic-rendering depth attachment format used to build pipelines.

Definition at line 206 of file mxvk_sprite.hpp.

206{ depthAttachmentFormat = format; }

◆ setDescriptorSetLayout()

void mxvk::VK_Sprite::setDescriptorSetLayout ( VkDescriptorSetLayout layout )

inline

Assign an external descriptor-set layout.

Definition at line 200 of file mxvk_sprite.hpp.

200{ descriptorSetLayout = layout; }

◆ setEffectsEnabled()

void mxvk::VK_Sprite::setEffectsEnabled ( bool enabled )

inline

Enable or disable the custom fragment shader effects.

Parameters

enabled true to enable effects.

Definition at line 164 of file mxvk_sprite.hpp.

164{ effectsEnabled = enabled; }

◆ setExternalTexture()

void mxvk::VK_Sprite::setExternalTexture	(	VkImageView	image_view,
		int	width,
		int	height )

Definition at line 1673 of file mxvk_sprite.cpp.

                                                                                    {
        if (image_view == VK_NULL_HANDLE || width <= 0 || height <= 0) {
            throw mxvk::Exception("VKSprite::setExternalTexture received an invalid image view");
        }
        if (externalTexture && spriteImageView == image_view) {
            spriteWidth = width;
            spriteHeight = height;
            spriteLoaded = true;
            return;
        }
        auto cached_descriptor = externalDescriptorSets.find(image_view);
        descriptorSet = (cached_descriptor != externalDescriptorSets.end()) ? cached_descriptor->second : VK_NULL_HANDLE;
        descriptorSetPool = VK_NULL_HANDLE;
        if (!externalTexture) {
            destroyTextureDescriptorPools();
        } else if (extendedDescriptorPool != VK_NULL_HANDLE) {
            vkDeviceWaitIdle(device);
            vkDestroyDescriptorPool(device, extendedDescriptorPool, nullptr);
            extendedDescriptorPool = VK_NULL_HANDLE;
            extendedDescriptorSet = VK_NULL_HANDLE;
        }
        if (!externalTexture && spriteImageView != VK_NULL_HANDLE) {
            vkDestroyImageView(device, spriteImageView, nullptr);
        }
        if (!externalTexture && spriteImage != VK_NULL_HANDLE) {
            vkDestroyImage(device, spriteImage, nullptr);
        }
        if (!externalTexture && spriteImageMemory != VK_NULL_HANDLE) {
            vkFreeMemory(device, spriteImageMemory, nullptr);
        }
        spriteImageView = image_view;
        spriteImage = VK_NULL_HANDLE;
        spriteImageMemory = VK_NULL_HANDLE;
        externalTexture = true;
        spriteWidth = width;
        spriteHeight = height;
        spriteLoaded = true;
    }

◆ setFragmentShaderPath()

void mxvk::VK_Sprite::setFragmentShaderPath ( const std::string & path )

Replace the fragment shader path and rebuild the custom pipeline.

Definition at line 797 of file mxvk_sprite.cpp.

                                                               {
        if (path == fragmentShaderPath && fragmentShaderModule != VK_NULL_HANDLE) {
            return;
        }
 
        if (customPipeline != VK_NULL_HANDLE) {
            vkDestroyPipeline(device, customPipeline, nullptr);
            customPipeline = VK_NULL_HANDLE;
        }
        if (customPipelineLayout != VK_NULL_HANDLE) {
            vkDestroyPipelineLayout(device, customPipelineLayout, nullptr);
            customPipelineLayout = VK_NULL_HANDLE;
        }
        if (fragmentShaderModule != VK_NULL_HANDLE) {
            vkDestroyShaderModule(device, fragmentShaderModule, nullptr);
            fragmentShaderModule = VK_NULL_HANDLE;
        }
 
        fragmentShaderPath = path;
        hasCustomShader = false;
 
        if (fragmentShaderPath.empty()) {
            return;
        }
 
        const auto shaderCode = readShaderFile(fragmentShaderPath);
        fragmentShaderModule = mxvk::create_shader_module(device, shaderCode);
        hasCustomShader = true;
 
        if (colorAttachmentFormat != VK_FORMAT_UNDEFINED && descriptorSetLayout != VK_NULL_HANDLE) {
            createCustomPipeline();
        }
    }

◆ setMouseState()

void mxvk::VK_Sprite::setMouseState	(	float	mx,
		float	my,
		float	pressed,
		float	reserved = 0.0f )

Upload mouse state to the extended UBO.

Parameters

mx	Mouse X (normalised or pixels).
my	Mouse Y.
pressed	Mouse button state.
reserved	Reserved channel.

Definition at line 174 of file mxvk_sprite.cpp.

                                                                                   {
        extendedUBOData.mouse = glm::vec4(mx, my, pressed, reserved);
    }

◆ setPipelineCache()

void mxvk::VK_Sprite::setPipelineCache ( VkPipelineCache cache )

inline

Use the shared pipeline cache for custom/instanced pipeline creation.

Definition at line 214 of file mxvk_sprite.hpp.

214{ pipelineCache = cache; }

◆ setRenderPass()

void mxvk::VK_Sprite::setRenderPass ( VkRenderPass rp )

inline

Assign the render pass used to build the custom pipeline.

Definition at line 202 of file mxvk_sprite.hpp.

202{ renderPass = rp; }

◆ setShaderParams()

void mxvk::VK_Sprite::setShaderParams	(	float	p1 = 0.0f,
		float	p2 = 0.0f,
		float	p3 = 0.0f,
		float	p4 = 0.0f )

Set up to four custom shader float parameters.

Parameters

p1,p2,p3,p4 Parameter values packed into a vec4.

Definition at line 1669 of file mxvk_sprite.cpp.

                                                                          {
        shaderParams = glm::vec4(p1, p2, p3, p4);
    }

◆ setTextureFilter()

void mxvk::VK_Sprite::setTextureFilter ( VkFilter filter )

Select the hardware filter used when scaling this sprite.

Parameters

filter VK_FILTER_NEAREST for sharp pixels or VK_FILTER_LINEAR for smoothing.

Definition at line 38 of file mxvk_sprite.cpp.

                                                    {
        if (filter != VK_FILTER_NEAREST && filter != VK_FILTER_LINEAR) {
            throw mxvk::Exception("VKSprite::setTextureFilter supports only nearest or linear filtering");
        }
        if (textureFilter == filter) {
            return;
        }
 
        textureFilter = filter;
        if (spriteSampler != VK_NULL_HANDLE) {
            destroyTextureDescriptorPools();
            vkDestroySampler(device, spriteSampler, nullptr);
            spriteSampler = VK_NULL_HANDLE;
            createSampler();
        }
 
        std::cout << "mxvk: Sprite texture filter set to "
                  << (textureFilter == VK_FILTER_NEAREST ? "nearest\n" : "linear\n");
    }

◆ setUniform0()

void mxvk::VK_Sprite::setUniform0	(	float	x,
		float	y,
		float	z,
		float	w )

Upload user uniform 0 to the extended UBO.

Parameters

x,y,z,w Components.

Definition at line 178 of file mxvk_sprite.cpp.

                                                                  {
        extendedUBOData.u0 = glm::vec4(x, y, z, w);
    }

◆ setUniform1()

void mxvk::VK_Sprite::setUniform1	(	float	x,
		float	y,
		float	z,
		float	w )

Upload user uniform 1 to the extended UBO.

Parameters

x,y,z,w Components.

Definition at line 182 of file mxvk_sprite.cpp.

                                                                  {
        extendedUBOData.u1 = glm::vec4(x, y, z, w);
    }

◆ setUniform2()

void mxvk::VK_Sprite::setUniform2	(	float	x,
		float	y,
		float	z,
		float	w )

Upload user uniform 2 to the extended UBO.

Parameters

x,y,z,w Components.

Definition at line 186 of file mxvk_sprite.cpp.

                                                                  {
        extendedUBOData.u2 = glm::vec4(x, y, z, w);
    }

◆ setUniform3()

void mxvk::VK_Sprite::setUniform3	(	float	x,
		float	y,
		float	z,
		float	w )

Upload user uniform 3 to the extended UBO.

Parameters

x,y,z,w Components.

Definition at line 190 of file mxvk_sprite.cpp.

                                                                  {
        extendedUBOData.u3 = glm::vec4(x, y, z, w);
    }

◆ setVertexShaderPath()

void mxvk::VK_Sprite::setVertexShaderPath ( const std::string & path )

inline

Override the vertex shader path (used when rebuilding the pipeline).

Definition at line 222 of file mxvk_sprite.hpp.

222{ vertexShaderPath = path; }

◆ updateTexture() [1/2]

void mxvk::VK_Sprite::updateTexture	(	const void *	pixels,
		int	width,
		int	height,
		int	pitch = 0 )

Replace the sprite texture from a raw pixel buffer.

Parameters

pixels	Pointer to RGBA data.
width	Buffer width.
height	Buffer height.
pitch	Row stride in bytes (0 = auto).

Definition at line 1033 of file mxvk_sprite.cpp.

                                                                                      {
        if (!pixels) {
            throw mxvk::Exception("VKSprite::updateTexture called with null pixel data");
        }
        if (!spriteLoaded) {
            throw mxvk::Exception("VKSprite::updateTexture called before sprite was loaded");
        }
        if (width <= 0 || height <= 0) {
            throw mxvk::Exception("VKSprite::updateTexture invalid dimensions");
        }
        int srcPitch = (pitch > 0) ? pitch : width * 4;
        if (width == spriteWidth && height == spriteHeight && srcPitch == width * 4) {
#ifdef MXVK_CUDA
            if (updateTextureCudaHost(pixels, static_cast<uint32_t>(width), static_cast<uint32_t>(height), static_cast<uint32_t>(srcPitch))) {
                return;
            }
#endif
            updateSpriteTexture(pixels, width, height);
        } else if (width == spriteWidth && height == spriteHeight) {
#ifdef MXVK_CUDA
            if (updateTextureCudaHost(pixels, static_cast<uint32_t>(width), static_cast<uint32_t>(height), static_cast<uint32_t>(srcPitch))) {
                return;
            }
#endif
            std::vector<uint8_t> packed(width * height * 4);
            const uint8_t *src = static_cast<const uint8_t *>(pixels);
            for (int row = 0; row < height; ++row) {
                memcpy(packed.data() + row * width * 4, src + row * srcPitch, width * 4);
            }
            updateSpriteTexture(packed.data(), width, height);
        } else {
            if (stagingResourcesCreated && uploadFence != VK_NULL_HANDLE) {
                vkWaitForFences(device, 1, &uploadFence, VK_TRUE, UINT64_MAX);
            }
#ifdef MXVK_CUDA
            destroyCudaInterop();
#endif
            destroyTextureDescriptorPools();
            if (spriteImageView != VK_NULL_HANDLE) {
                vkDestroyImageView(device, spriteImageView, nullptr);
                spriteImageView = VK_NULL_HANDLE;
            }
            if (spriteImage != VK_NULL_HANDLE) {
                vkDestroyImage(device, spriteImage, nullptr);
                spriteImage = VK_NULL_HANDLE;
            }
            if (spriteImageMemory != VK_NULL_HANDLE) {
                vkFreeMemory(device, spriteImageMemory, nullptr);
                spriteImageMemory = VK_NULL_HANDLE;
            }
            spriteWidth = width;
            spriteHeight = height;
            std::vector<uint8_t> packed;
            const void *texData = pixels;
            if (srcPitch != width * 4) {
                packed.resize(width * height * 4);
                const uint8_t *src = static_cast<const uint8_t *>(pixels);
                for (int row = 0; row < height; ++row) {
                    memcpy(packed.data() + row * width * 4, src + row * srcPitch, width * 4);
                }
                texData = packed.data();
            }
            // Resize path: wrap raw pixels in a temporary SDL3 surface (no copy)
            SDL_Surface *tmpSurface = SDL_CreateSurfaceFrom(
                width, height, SDL_PIXELFORMAT_RGBA32,
                const_cast<void *>(texData), width * 4);
            if (!tmpSurface) {
                throw mxvk::Exception("VKSprite::updateTexture failed to create temp surface");
            }
            createSpriteTexture(tmpSurface);
            SDL_DestroySurface(tmpSurface);
            createDescriptorPool();
        }
    }

◆ updateTexture() [2/2]

void mxvk::VK_Sprite::updateTexture ( SDL_Surface * surface )

Replace the sprite texture from an SDL_Surface.

Parameters

surface New surface (not consumed).

Definition at line 985 of file mxvk_sprite.cpp.

                                                      {
        if (!surface) {
            throw mxvk::Exception("VKSprite::updateTexture called with null surface");
        }
        if (!spriteLoaded) {
            throw mxvk::Exception("VKSprite::updateTexture called before sprite was loaded");
        }
        SDL_Surface *rgbaSurface = convertToRGBA(surface);
        if (!rgbaSurface) {
            throw mxvk::Exception("Failed to convert surface to RGBA in updateTexture");
        }
        if (rgbaSurface->w == spriteWidth && rgbaSurface->h == spriteHeight) {
#ifdef MXVK_CUDA
            if (updateTextureCudaHost(rgbaSurface->pixels, static_cast<uint32_t>(rgbaSurface->w), static_cast<uint32_t>(rgbaSurface->h),
                                      static_cast<uint32_t>(rgbaSurface->pitch))) {
                SDL_DestroySurface(rgbaSurface);
                return;
            }
#endif
            updateSpriteTexture(rgbaSurface->pixels, rgbaSurface->w, rgbaSurface->h);
        } else {
            if (stagingResourcesCreated && uploadFence != VK_NULL_HANDLE) {
                vkWaitForFences(device, 1, &uploadFence, VK_TRUE, UINT64_MAX);
            }
#ifdef MXVK_CUDA
            destroyCudaInterop();
#endif
            destroyTextureDescriptorPools();
            if (spriteImageView != VK_NULL_HANDLE) {
                vkDestroyImageView(device, spriteImageView, nullptr);
                spriteImageView = VK_NULL_HANDLE;
            }
            if (spriteImage != VK_NULL_HANDLE) {
                vkDestroyImage(device, spriteImage, nullptr);
                spriteImage = VK_NULL_HANDLE;
            }
            if (spriteImageMemory != VK_NULL_HANDLE) {
                vkFreeMemory(device, spriteImageMemory, nullptr);
                spriteImageMemory = VK_NULL_HANDLE;
            }
            spriteWidth = rgbaSurface->w;
            spriteHeight = rgbaSurface->h;
            createSpriteTexture(rgbaSurface);
            createDescriptorPool();
        }
        SDL_DestroySurface(rgbaSurface);
    }

Member Data Documentation

◆ spriteSampler

VkSampler mxvk::VK_Sprite::spriteSampler = VK_NULL_HANDLE

Texture sampler.

Definition at line 238 of file mxvk_sprite.hpp.

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

mxvk/include/mxvk/mxvk_sprite.hpp
mxvk/src/mxvk_sprite.cpp

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

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ VK_Sprite() [1/3]

◆ ~VK_Sprite()

◆ VK_Sprite() [2/3]

◆ VK_Sprite() [3/3]

Member Function Documentation

◆ clearExternalTextureDescriptors()

◆ clearQueue()

◆ createEmptySprite()

◆ drawSprite() [1/3]

◆ drawSprite() [2/3]

◆ drawSprite() [3/3]

◆ drawSpriteRect()

◆ enableExtendedUBO()

◆ enableInstancing()

◆ getEffectsEnabled()

◆ getHeight()

◆ getPipeline()

◆ getPipelineLayout()

◆ getWidth()

◆ hasOwnPipeline()

◆ isExtendedUBOEnabled()

◆ isInstancingEnabled()

◆ loadSprite() [1/2]

◆ loadSprite() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ prepareForRendering()

◆ rebuildInstancedPipeline()

◆ rebuildPipeline()

◆ releaseUploadResources()

◆ renderSprites()

◆ setColorAttachmentFormat()

◆ setCommandPool()

◆ setDepthAttachmentFormat()

◆ setDescriptorSetLayout()

◆ setEffectsEnabled()

◆ setExternalTexture()

◆ setFragmentShaderPath()

◆ setMouseState()

◆ setPipelineCache()

◆ setRenderPass()

◆ setShaderParams()

◆ setTextureFilter()

◆ setUniform0()

◆ setUniform1()

◆ setUniform2()

◆ setUniform3()

◆ setVertexShaderPath()

◆ updateTexture() [1/2]

◆ updateTexture() [2/2]

Member Data Documentation

◆ spriteSampler