mxvk::VK_Sprite Class Reference

#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	createEmptySpriteRgba16 (int width, int height, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Create a blank RGBA16 UNORM sprite texture.
void	dispatchCompute (VkCommandBuffer cmdBuffer, VkImageView inputView, VkImageView outputView, uint32_t width, uint32_t height)
	Dispatch the compute effect between two full-frame images.
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	enableComputeShader (const std::string &path, uint32_t localSizeX, uint32_t localSizeY, uint32_t localSizeZ=1)
	Build a compute image-effect pipeline for this sprite.
void	enableExtendedUBO ()
	Allocate and initialise the extended uniform buffer object.
void	enableHistoryTexture (uint32_t width, uint32_t height, uint32_t layers)
	Allocate a shader-readable RGBA history texture array.
void	enableHistoryTextureRgba16Float (uint32_t width, uint32_t height, uint32_t layers)
	Allocate a shader-readable RGBA16F history texture array.
void	enableInstancing (uint32_t maxInstances, const std::string &instanceVertShaderPath, const std::string &instanceFragShaderPath)
	Enable GPU instancing for this sprite type.
uint32_t	enableSpectrumHistoryTexture (uint32_t bins, uint32_t layers)
	Allocate a shader-readable FFT spectrum-history array.
void	enableSpectrumTexture (uint32_t bins)
	Allocate a shader-readable 1-D floating-point spectrum texture.
bool	getEffectsEnabled () const
int	getHeight () const
uint32_t	getHistoryHead () const
uint32_t	getHistoryLayerCount () const
VkPipeline	getPipeline () const
VkPipelineLayout	getPipelineLayout () const
uint32_t	getSpectrumBinCount () const
uint32_t	getSpectrumHistoryHead () const
uint32_t	getSpectrumHistoryLayerCount () const
int	getWidth () const
bool	hasComputePipeline () 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	setAudioBands (float low, float mid, float high, float reserved=0.0f)
	Upload audio frequency-band energy to the extended UBO.
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	setCustomUniforms (const std::vector< float > &values)
	Upload ordered custom float values to the extended UBO.
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	shareHistoryTexture (const VK_Sprite &source)
	Bind another sprite's history array without taking ownership.
void	updateHistoryTexture (const void *pixels, int width, int height, int pitch=0)
	Upload one RGBA frame into the next history layer.
void	updateHistoryTextureRgba16 (const uint16_t *pixels, int width, int height, int pitch=0)
	Upload normalized RGBA16 pixels into an RGBA16F history layer.
void	updateSpectrumHistoryTexture (const float *magnitudes, uint32_t bins)
	Upload one FFT spectrum into the next history layer.
void	updateSpectrumTexture (const float *magnitudes, uint32_t bins)
	Replace the current floating-point spectrum data.
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.
void	updateTextureRgba16 (const uint16_t *pixels, int width, int height, int pitch=0)
	Replace an RGBA16 UNORM sprite from native-endian uint16 data.
	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.

Static Public Attributes
static constexpr std::size_t	MAX_CUSTOM_UNIFORMS = 64

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 49 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 83 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);
            std::cout << "vk: freeing sprite image memory\n";
            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);
        }
 
        destroyComputePipeline();
        if (computeShaderModule != VK_NULL_HANDLE) {
            vkDestroyShaderModule(device, computeShaderModule, nullptr);
            computeShaderModule = VK_NULL_HANDLE;
        }
 
        destroyExtendedUBO();
        destroyHistoryTexture();
        destroySpectrumTexture();
        destroySpectrumHistoryTexture();
        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 2622 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 2721 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 1658 of file mxvk_sprite.cpp.

{ createEmptySpriteWithFormat(width, height, VK_FORMAT_R8G8B8A8_UNORM, 4, vertexShaderPath, fragmentShaderPath); }

createEmptySpriteRgba16()

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

Create a blank RGBA16 UNORM sprite texture.

This preserves transfer-encoded 10/12-bit video input without quantizing it to RGBA8. It does not change render-target precision.

Definition at line 1660 of file mxvk_sprite.cpp.

{ createEmptySpriteWithFormat(width, height, VK_FORMAT_R16G16B16A16_UNORM, 8, vertexShaderPath, fragmentShaderPath); }

dispatchCompute()

void mxvk::VK_Sprite::dispatchCompute	(	VkCommandBuffer	cmdBuffer,
		VkImageView	inputView,
		VkImageView	outputView,
		uint32_t	width,
		uint32_t	height )

Dispatch the compute effect between two full-frame images.

Definition at line 1558 of file mxvk_sprite.cpp.

                                                                                                                                             {
        if (computePipeline == VK_NULL_HANDLE || computePipelineLayout == VK_NULL_HANDLE || inputView == VK_NULL_HANDLE || outputView == VK_NULL_HANDLE || width == 0 || height == 0) {
            throw mxvk::Exception("VKSprite::dispatchCompute received an incomplete compute pass");
        }
 
        setExternalTexture(inputView, static_cast<int>(width), static_cast<int>(height));
        if (computeOutputImageView != outputView) {
            if (extendedDescriptorPool != VK_NULL_HANDLE) {
                vkDeviceWaitIdle(device);
                vkDestroyDescriptorPool(device, extendedDescriptorPool, nullptr);
                extendedDescriptorPool = VK_NULL_HANDLE;
                extendedDescriptorSet = VK_NULL_HANDLE;
            }
            computeOutputImageView = outputView;
        }
        updateExtendedUBO();
        if (extendedDescriptorSet == VK_NULL_HANDLE) {
            createExtendedDescriptorSet();
        }
        if (extendedDescriptorSet == VK_NULL_HANDLE) {
            throw mxvk::Exception("VKSprite::dispatchCompute could not create its descriptor set");
        }
 
        vkCmdBindPipeline(cmdBuffer, VK_PIPELINE_BIND_POINT_COMPUTE, computePipeline);
        vkCmdBindDescriptorSets(cmdBuffer, VK_PIPELINE_BIND_POINT_COMPUTE, computePipelineLayout, 0, 1, &extendedDescriptorSet, 0, nullptr);
        vkCmdDispatch(cmdBuffer, (width + computeLocalSizeX - 1U) / computeLocalSizeX, (height + computeLocalSizeY - 1U) / computeLocalSizeY, 1U);
    }

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 2561 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 2563 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 2565 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 2573 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});
    }

enableComputeShader()

void mxvk::VK_Sprite::enableComputeShader	(	const std::string &	path,
		uint32_t	localSizeX,
		uint32_t	localSizeY,
		uint32_t	localSizeZ = 1 )

Build a compute image-effect pipeline for this sprite.

Compute shaders use the extended sprite descriptor ABI: binding 0 is the sampled input image, binding 1 is SpriteExtended, optional history/audio textures remain at bindings 2-4, and binding 5 is a write-only storage image matching the active render precision.

Definition at line 1535 of file mxvk_sprite.cpp.

                                                                                                                            {
        if (path.empty() || localSizeX == 0 || localSizeY == 0 || localSizeZ == 0) {
            throw mxvk::Exception("VKSprite::enableComputeShader requires a shader and positive local size");
        }
 
        vkDeviceWaitIdle(device);
        destroyComputePipeline();
        if (computeShaderModule != VK_NULL_HANDLE) {
            vkDestroyShaderModule(device, computeShaderModule, nullptr);
            computeShaderModule = VK_NULL_HANDLE;
        }
        computeShaderModule = mxvk::create_shader_module(device, readShaderFile(path));
        computeLocalSizeX = localSizeX;
        computeLocalSizeY = localSizeY;
 
        if (!extendedUBOEnabled) {
            enableExtendedUBO();
            createComputePipeline();
        } else {
            recreateExtendedDescriptorLayout();
        }
    }

enableExtendedUBO()

void mxvk::VK_Sprite::enableExtendedUBO

(

)

Allocate and initialise the extended uniform buffer object.

Definition at line 201 of file mxvk_sprite.cpp.

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

enableHistoryTexture()

void mxvk::VK_Sprite::enableHistoryTexture	(	uint32_t	width,
		uint32_t	height,
		uint32_t	layers )

Allocate a shader-readable RGBA history texture array.

Enables extended descriptors and exposes the array as a combined image sampler at set 0, binding 2. Replaces any previously allocated history texture. The texture is initialized to transparent black.

Parameters

width	Width of every history layer in pixels.
height	Height of every history layer in pixels.
layers	Number of layers in the circular history buffer.

Exceptions

mxvk::Exception

when any dimension is zero.

Definition at line 233 of file mxvk_sprite.cpp.

{ enableHistoryTextureWithFormat(width, height, layers, VK_FORMAT_R8G8B8A8_UNORM); }

enableHistoryTextureRgba16Float()

void mxvk::VK_Sprite::enableHistoryTextureRgba16Float	(	uint32_t	width,
		uint32_t	height,
		uint32_t	layers )

Allocate a shader-readable RGBA16F history texture array.

Definition at line 235 of file mxvk_sprite.cpp.

{ enableHistoryTextureWithFormat(width, height, layers, VK_FORMAT_R16G16B16A16_SFLOAT); }

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 1122 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);
    }

enableSpectrumHistoryTexture()

uint32_t mxvk::VK_Sprite::enableSpectrumHistoryTexture	(	uint32_t	bins,
		uint32_t	layers )

Allocate a shader-readable FFT spectrum-history array.

Enables extended descriptors and exposes the history as a combined image sampler at set 0, binding 4. The R32_SFLOAT 1-D array is initialized to zero and uses a circular write head.

Parameters

bins	Number of frequency bins in every history layer.
layers	Requested number of history layers. The active GPU's maximum image-array-layer limit is applied automatically.

Returns

Number of history layers actually allocated.

Exceptions

mxvk::Exception

when either requested dimension is zero.

Definition at line 563 of file mxvk_sprite.cpp.

                                                                                   {
        if (bins == 0 || layers == 0) {
            throw mxvk::Exception("VKSprite::enableSpectrumHistoryTexture requires positive bin and layer counts");
        }
        VkPhysicalDeviceProperties properties{};
        vkGetPhysicalDeviceProperties(physicalDevice, &properties);
        const uint32_t allocatedLayers = std::min(layers, properties.limits.maxImageArrayLayers);
        if (allocatedLayers == 0) {
            throw mxvk::Exception("VKSprite::enableSpectrumHistoryTexture is unavailable on this device");
        }
        if (spectrumHistoryTextureEnabled && spectrumHistoryBins == bins && spectrumHistoryLayers == allocatedLayers) {
            return spectrumHistoryLayers;
        }
        if (!extendedUBOEnabled) {
            enableExtendedUBO();
        }
 
        vkDeviceWaitIdle(device);
        destroySpectrumHistoryTexture();
 
        if (allocatedLayers != layers) {
            std::cerr << "vk: spectrum history clamped to device array-layer limit " << allocatedLayers << " (was " << layers << ")\n";
        }
        spectrumHistoryBins = bins;
        spectrumHistoryLayers = allocatedLayers;
        spectrumHistoryHead = 0;
        spectrumHistoryWriteIndex = 0;
        extendedUBOData.audio_history = glm::vec4(0.0f, static_cast<float>(allocatedLayers), static_cast<float>(bins), 0.0f);
 
        createImage(bins, 1, VK_FORMAT_R32_SFLOAT, VK_IMAGE_TILING_OPTIMAL, VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_SAMPLED_BIT, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT, spectrumHistoryImage, spectrumHistoryImageMemory, allocatedLayers, VK_IMAGE_TYPE_1D);
 
        const VkDeviceSize imageSize = static_cast<VkDeviceSize>(bins) * static_cast<VkDeviceSize>(allocatedLayers) * sizeof(float);
        VkBuffer stagingBuffer = VK_NULL_HANDLE;
        VkDeviceMemory stagingMemory = VK_NULL_HANDLE;
        createBuffer(imageSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, stagingBuffer, stagingMemory);
 
        void *data = nullptr;
        VK_CHECK_RESULT(vkMapMemory(device, stagingMemory, 0, imageSize, 0, &data));
        memset(data, 0, static_cast<std::size_t>(imageSize));
        vkUnmapMemory(device, stagingMemory);
 
        transitionImageLayout(spectrumHistoryImage, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 0, allocatedLayers);
        copyBufferToImage(stagingBuffer, spectrumHistoryImage, bins, 1, 0, allocatedLayers);
        transitionImageLayout(spectrumHistoryImage, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL, 0, allocatedLayers);
 
        vkDestroyBuffer(device, stagingBuffer, nullptr);
        vkFreeMemory(device, stagingMemory, nullptr);
 
        spectrumHistoryImageView = createImageView(spectrumHistoryImage, VK_FORMAT_R32_SFLOAT, VK_IMAGE_VIEW_TYPE_1D_ARRAY, allocatedLayers);
        spectrumHistoryTextureEnabled = true;
        recreateExtendedDescriptorLayout();
        return allocatedLayers;
    }

enableSpectrumTexture()

void mxvk::VK_Sprite::enableSpectrumTexture

(

uint32_t

bins

)

Allocate a shader-readable 1-D floating-point spectrum texture.

Enables extended descriptors and exposes the texture as a combined image sampler at set 0, binding 3. The texture is initialized to zero.

Parameters

bins	Number of R32_SFLOAT frequency bins.

Exceptions

mxvk::Exception

when bins is zero.

Definition at line 462 of file mxvk_sprite.cpp.

                                                       {
        if (bins == 0) {
            throw mxvk::Exception("VKSprite::enableSpectrumTexture requires a positive bin count");
        }
        if (spectrumTextureEnabled && spectrumBins == bins) {
            return;
        }
        if (!extendedUBOEnabled) {
            enableExtendedUBO();
        }
 
        vkDeviceWaitIdle(device);
        destroySpectrumTexture();
 
        spectrumBins = bins;
        createImage(bins, 1, VK_FORMAT_R32_SFLOAT, VK_IMAGE_TILING_OPTIMAL, VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_SAMPLED_BIT, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT, spectrumImage, spectrumImageMemory, 1, VK_IMAGE_TYPE_1D);
 
        const VkDeviceSize imageSize = static_cast<VkDeviceSize>(bins) * sizeof(float);
        VkBuffer stagingBuffer = VK_NULL_HANDLE;
        VkDeviceMemory stagingMemory = VK_NULL_HANDLE;
        createBuffer(imageSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT, VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT, stagingBuffer, stagingMemory);
 
        void *data = nullptr;
        VK_CHECK_RESULT(vkMapMemory(device, stagingMemory, 0, imageSize, 0, &data));
        memset(data, 0, static_cast<std::size_t>(imageSize));
        vkUnmapMemory(device, stagingMemory);
 
        transitionImageLayout(spectrumImage, VK_IMAGE_LAYOUT_UNDEFINED, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);
        copyBufferToImage(stagingBuffer, spectrumImage, bins, 1);
        transitionImageLayout(spectrumImage, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
 
        vkDestroyBuffer(device, stagingBuffer, nullptr);
        vkFreeMemory(device, stagingMemory, nullptr);
 
        spectrumImageView = createImageView(spectrumImage, VK_FORMAT_R32_SFLOAT, VK_IMAGE_VIEW_TYPE_1D);
        spectrumTextureEnabled = true;
        recreateExtendedDescriptorLayout();
    }

getEffectsEnabled()

bool mxvk::VK_Sprite::getEffectsEnabled ( ) const

inline

Returns

true if shader effects are enabled.

Definition at line 185 of file mxvk_sprite.hpp.

{ return effectsEnabled; }

getHeight()

int mxvk::VK_Sprite::getHeight ( ) const

inline

Returns

Sprite texture height in pixels.

Definition at line 208 of file mxvk_sprite.hpp.

{ return spriteHeight; }

getHistoryHead()

uint32_t mxvk::VK_Sprite::getHistoryHead ( ) const

inlinenodiscard

Returns

The logical oldest-layer index for a circular history sampler.

Definition at line 398 of file mxvk_sprite.hpp.

{ return historyHead; }

getHistoryLayerCount()

uint32_t mxvk::VK_Sprite::getHistoryLayerCount ( ) const

inlinenodiscard

Returns

Number of allocated texture-history layers.

Definition at line 401 of file mxvk_sprite.hpp.

{ return historyLayers; }

getPipeline()

VkPipeline mxvk::VK_Sprite::getPipeline ( ) const

inline

Returns

The custom VkPipeline handle (may be VK_NULL_HANDLE).

Definition at line 262 of file mxvk_sprite.hpp.

{ return customPipeline; }

getPipelineLayout()

VkPipelineLayout mxvk::VK_Sprite::getPipelineLayout ( ) const

inline

Returns

The custom pipeline layout handle.

Definition at line 264 of file mxvk_sprite.hpp.

{ return customPipelineLayout; }

getSpectrumBinCount()

uint32_t mxvk::VK_Sprite::getSpectrumBinCount ( ) const

inlinenodiscard

Returns

Number of allocated spectrum bins.

Definition at line 422 of file mxvk_sprite.hpp.

{ return spectrumBins; }

getSpectrumHistoryHead()

uint32_t mxvk::VK_Sprite::getSpectrumHistoryHead ( ) const

inlinenodiscard

Returns

Physical array layer containing the newest FFT spectrum.

Definition at line 448 of file mxvk_sprite.hpp.

{ return spectrumHistoryHead; }

getSpectrumHistoryLayerCount()

uint32_t mxvk::VK_Sprite::getSpectrumHistoryLayerCount ( ) const

inlinenodiscard

Returns

Number of allocated FFT spectrum-history layers.

Definition at line 451 of file mxvk_sprite.hpp.

{ return spectrumHistoryLayers; }

getWidth()

int mxvk::VK_Sprite::getWidth ( ) const

inline

Returns

Sprite texture width in pixels.

Definition at line 206 of file mxvk_sprite.hpp.

{ return spriteWidth; }

hasComputePipeline()

bool mxvk::VK_Sprite::hasComputePipeline ( ) const

inlinenodiscard

Returns

Whether this sprite owns an executable compute pipeline.

Definition at line 254 of file mxvk_sprite.hpp.

{ return computePipeline != VK_NULL_HANDLE; }

hasOwnPipeline()

bool mxvk::VK_Sprite::hasOwnPipeline ( ) const

inline

Returns

true if a custom pipeline has been built.

Definition at line 260 of file mxvk_sprite.hpp.

{ return customPipeline != VK_NULL_HANDLE; }

isExtendedUBOEnabled()

bool mxvk::VK_Sprite::isExtendedUBOEnabled ( ) const

inline

Returns

true if the extended UBO is active.

Definition at line 288 of file mxvk_sprite.hpp.

{ return extendedUBOEnabled; }

isInstancingEnabled()

bool mxvk::VK_Sprite::isInstancingEnabled ( ) const

inline

Returns

true if GPU instancing is active.

Definition at line 282 of file mxvk_sprite.hpp.

{ 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 1617 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 1627 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 2629 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 1586 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 1455 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 51 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 2635 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);
        }
    }

setAudioBands()

void mxvk::VK_Sprite::setAudioBands	(	float	low,
		float	mid,
		float	high,
		float	reserved = 0.0f )

Upload audio frequency-band energy to the extended UBO.

The values are appended after the custom-uniform array to preserve the existing SpriteExtended prefix and custom-uniform offsets.

Parameters

low	Energy below 300 Hz.
mid	Energy from 300 through 3000 Hz.
high	Energy above 3000 Hz.
reserved	Reserved channel.

Definition at line 220 of file mxvk_sprite.cpp.

{ extendedUBOData.audio_bands = glm::vec4(low, mid, high, reserved); }

setColorAttachmentFormat()

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

inline

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

Definition at line 221 of file mxvk_sprite.hpp.

{ 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 53 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;
    }

setCustomUniforms()

void mxvk::VK_Sprite::setCustomUniforms

(

const std::vector< float > &

values

)

Upload ordered custom float values to the extended UBO.

Custom shaders can append vec4 custom_uniforms[16] after u3 in their binding-1 SpriteExtended block. Value N is available at custom_uniforms[N/4][N%4]. Existing shaders that use only the original SpriteExtended prefix remain compatible.

Parameters

values

Up to MAX_CUSTOM_UNIFORMS values. Unused slots are zeroed.

Exceptions

mxvk::Exception

when too many values are supplied.

Definition at line 222 of file mxvk_sprite.cpp.

                                                                    {
        if (values.size() > MAX_CUSTOM_UNIFORMS) {
            throw mxvk::Exception(std::format("VKSprite::setCustomUniforms supports at most {} values", MAX_CUSTOM_UNIFORMS));
        }
 
        extendedUBOData.custom_uniforms.fill(glm::vec4(0.0f));
        for (std::size_t index = 0; index < values.size(); ++index) {
            extendedUBOData.custom_uniforms[index / 4][index % 4] = values[index];
        }
    }

setDepthAttachmentFormat()

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

inline

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

Definition at line 223 of file mxvk_sprite.hpp.

{ depthAttachmentFormat = format; }

setDescriptorSetLayout()

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

inline

Assign an external descriptor-set layout.

Definition at line 217 of file mxvk_sprite.hpp.

{ 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 182 of file mxvk_sprite.hpp.

{ effectsEnabled = enabled; }

setExternalTexture()

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

Definition at line 2583 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 1462 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 210 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 231 of file mxvk_sprite.hpp.

{ pipelineCache = cache; }

setRenderPass()

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

inline

Assign the render pass used to build the custom pipeline.

Definition at line 219 of file mxvk_sprite.hpp.

{ 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 2581 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 64 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 212 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 214 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 216 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 218 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 239 of file mxvk_sprite.hpp.

{ vertexShaderPath = path; }

shareHistoryTexture()

void mxvk::VK_Sprite::shareHistoryTexture

(

const VK_Sprite &

source

)

Bind another sprite's history array without taking ownership.

The source sprite must outlive this sprite. This is intended for post-processing passes which read one shared input history ring. No image, memory, or image view is allocated or freed by this sprite.

Parameters

source

Sprite which owns an enabled history texture.

Exceptions

mxvk::Exception

when the source has no history texture or belongs to a different Vulkan device.

Definition at line 314 of file mxvk_sprite.cpp.

                                                               {
        if (source.device != device) {
            throw mxvk::Exception("VKSprite::shareHistoryTexture requires sprites on the same Vulkan device");
        }
        if (!source.historyTextureEnabled || source.historyImageView == VK_NULL_HANDLE || source.historyLayers == 0) {
            throw mxvk::Exception("VKSprite::shareHistoryTexture source has no enabled history texture");
        }
        if (&source == this) {
            throw mxvk::Exception("VKSprite::shareHistoryTexture cannot share a sprite with itself");
        }
 
        if (!extendedUBOEnabled) {
            enableExtendedUBO();
        }
 
        vkDeviceWaitIdle(device);
        destroyHistoryTexture();
        historyImageView = source.historyImageView;
        historyImageFormat = source.historyImageFormat;
        historyWidth = source.historyWidth;
        historyHeight = source.historyHeight;
        historyLayers = source.historyLayers;
        historyHead = source.historyHead;
        historyTextureEnabled = true;
        historyTextureShared = true;
        recreateExtendedDescriptorLayout();
    }

updateHistoryTexture()

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

Upload one RGBA frame into the next history layer.

The write head advances after a successful upload. Input dimensions must match those passed to enableHistoryTexture().

Parameters

pixels	RGBA8 source pixels.
width	Source width in pixels.
height	Source height in pixels.
pitch	Source row stride in bytes, or zero for tightly packed data.

Exceptions

mxvk::Exception

for null data, invalid dimensions, or an inactive cache.

Definition at line 342 of file mxvk_sprite.cpp.

                                                                                             {
        if (historyImageFormat == VK_FORMAT_R16G16B16A16_SFLOAT) {
            const int source_pitch = pitch > 0 ? pitch : width * 4;
            if (pixels == nullptr || width <= 0 || height <= 0 || source_pitch < width * 4) {
                throw mxvk::Exception("VKSprite::updateHistoryTexture received invalid RGBA8 pixels");
            }
            std::vector<uint16_t> converted(static_cast<std::size_t>(width) * height * 4U);
            const auto *source = static_cast<const uint8_t *>(pixels);
            for (int row = 0; row < height; ++row) {
                const uint8_t *source_row = source + static_cast<std::size_t>(row) * source_pitch;
                uint16_t *destination_row = converted.data() + static_cast<std::size_t>(row) * width * 4U;
                for (int component = 0; component < width * 4; ++component) {
                    destination_row[component] = float_to_half(source_row[component] / 255.0F);
                }
            }
            uploadHistoryTextureBytes(converted.data(), width, height, width * 8, 8);
            return;
        }
        uploadHistoryTextureBytes(pixels, width, height, pitch, 4);
    }

updateHistoryTextureRgba16()

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

Upload normalized RGBA16 pixels into an RGBA16F history layer.

Definition at line 363 of file mxvk_sprite.cpp.

                                                                                                       {
        if (historyImageFormat != VK_FORMAT_R16G16B16A16_SFLOAT) {
            throw mxvk::Exception("VKSprite::updateHistoryTextureRgba16 requires RGBA16F history");
        }
        const int source_pitch = pitch > 0 ? pitch : width * 8;
        if (pixels == nullptr || width <= 0 || height <= 0 || source_pitch < width * 8) {
            throw mxvk::Exception("VKSprite::updateHistoryTextureRgba16 received invalid pixels");
        }
        std::vector<uint16_t> converted(static_cast<std::size_t>(width) * height * 4U);
        const auto *source = reinterpret_cast<const uint8_t *>(pixels);
        for (int row = 0; row < height; ++row) {
            const auto *source_row = reinterpret_cast<const uint16_t *>(source + static_cast<std::size_t>(row) * source_pitch);
            uint16_t *destination_row = converted.data() + static_cast<std::size_t>(row) * width * 4U;
            for (int component = 0; component < width * 4; ++component) {
                destination_row[component] = float_to_half(source_row[component] / 65535.0F);
            }
        }
        uploadHistoryTextureBytes(converted.data(), width, height, width * 8, 8);
    }

updateSpectrumHistoryTexture()

void mxvk::VK_Sprite::updateSpectrumHistoryTexture	(	const float *	magnitudes,
		uint32_t	bins )

Upload one FFT spectrum into the next history layer.

Parameters

magnitudes	Pointer to bins frequency magnitudes.
bins	Number of values; must match the configured history.

Definition at line 617 of file mxvk_sprite.cpp.

                                                                                       {
        if (!spectrumHistoryTextureEnabled || spectrumHistoryImage == VK_NULL_HANDLE) {
            throw mxvk::Exception("VKSprite::updateSpectrumHistoryTexture called before enableSpectrumHistoryTexture");
        }
        if (magnitudes == nullptr) {
            throw mxvk::Exception("VKSprite::updateSpectrumHistoryTexture called with null data");
        }
        if (bins != spectrumHistoryBins) {
            throw mxvk::Exception("VKSprite::updateSpectrumHistoryTexture bin count does not match the history texture");
        }
 
        const VkDeviceSize imageSize = static_cast<VkDeviceSize>(bins) * sizeof(float);
        createStagingResources(imageSize);
        VK_CHECK_RESULT(vkWaitForFences(device, 1, &uploadFence, VK_TRUE, UINT64_MAX));
        VK_CHECK_RESULT(vkResetFences(device, 1, &uploadFence));
        memcpy(persistentStagingMapped, magnitudes, static_cast<std::size_t>(imageSize));
 
        VK_CHECK_RESULT(vkResetCommandBuffer(uploadCmdBuffer, 0));
        VkCommandBufferBeginInfo beginInfo{};
        beginInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
        beginInfo.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
        VK_CHECK_RESULT(vkBeginCommandBuffer(uploadCmdBuffer, &beginInfo));
 
        VkImageMemoryBarrier barrier{};
        barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
        barrier.oldLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
        barrier.newLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
        barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.image = spectrumHistoryImage;
        barrier.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        barrier.subresourceRange.baseMipLevel = 0;
        barrier.subresourceRange.levelCount = 1;
        barrier.subresourceRange.baseArrayLayer = spectrumHistoryWriteIndex;
        barrier.subresourceRange.layerCount = 1;
        barrier.srcAccessMask = VK_ACCESS_SHADER_READ_BIT;
        barrier.dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
        vkCmdPipelineBarrier(uploadCmdBuffer, VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_TRANSFER_BIT, 0, 0, nullptr, 0, nullptr, 1, &barrier);
 
        VkBufferImageCopy region{};
        region.imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        region.imageSubresource.mipLevel = 0;
        region.imageSubresource.baseArrayLayer = spectrumHistoryWriteIndex;
        region.imageSubresource.layerCount = 1;
        region.imageExtent = {bins, 1, 1};
        vkCmdCopyBufferToImage(uploadCmdBuffer, persistentStagingBuffer, spectrumHistoryImage, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &region);
 
        barrier.oldLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
        barrier.newLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
        barrier.srcAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
        barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT;
        vkCmdPipelineBarrier(uploadCmdBuffer, VK_PIPELINE_STAGE_TRANSFER_BIT, VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, 0, 0, nullptr, 0, nullptr, 1, &barrier);
 
        VK_CHECK_RESULT(vkEndCommandBuffer(uploadCmdBuffer));
        VkSubmitInfo submitInfo{};
        submitInfo.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO;
        submitInfo.commandBufferCount = 1;
        submitInfo.pCommandBuffers = &uploadCmdBuffer;
        VK_CHECK_RESULT(vkQueueSubmit(graphicsQueue, 1, &submitInfo, uploadFence));
        VK_CHECK_RESULT(vkWaitForFences(device, 1, &uploadFence, VK_TRUE, UINT64_MAX));
 
        spectrumHistoryHead = spectrumHistoryWriteIndex;
        spectrumHistoryWriteIndex = (spectrumHistoryWriteIndex + 1) % spectrumHistoryLayers;
        extendedUBOData.audio_history = glm::vec4(static_cast<float>(spectrumHistoryHead), static_cast<float>(spectrumHistoryLayers), static_cast<float>(spectrumHistoryBins), 0.0f);
    }

updateSpectrumTexture()

void mxvk::VK_Sprite::updateSpectrumTexture	(	const float *	magnitudes,
		uint32_t	bins )

Replace the current floating-point spectrum data.

Parameters

magnitudes	Pointer to bins frequency magnitudes.
bins	Number of values; must match enableSpectrumTexture().

Definition at line 501 of file mxvk_sprite.cpp.

                                                                                {
        if (!spectrumTextureEnabled || spectrumImage == VK_NULL_HANDLE) {
            throw mxvk::Exception("VKSprite::updateSpectrumTexture called before enableSpectrumTexture");
        }
        if (magnitudes == nullptr) {
            throw mxvk::Exception("VKSprite::updateSpectrumTexture called with null data");
        }
        if (bins != spectrumBins) {
            throw mxvk::Exception("VKSprite::updateSpectrumTexture bin count does not match the spectrum texture");
        }
 
        const VkDeviceSize imageSize = static_cast<VkDeviceSize>(bins) * sizeof(float);
        createStagingResources(imageSize);
        VK_CHECK_RESULT(vkWaitForFences(device, 1, &uploadFence, VK_TRUE, UINT64_MAX));
        VK_CHECK_RESULT(vkResetFences(device, 1, &uploadFence));
        memcpy(persistentStagingMapped, magnitudes, static_cast<std::size_t>(imageSize));
 
        VK_CHECK_RESULT(vkResetCommandBuffer(uploadCmdBuffer, 0));
        VkCommandBufferBeginInfo beginInfo{};
        beginInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
        beginInfo.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
        VK_CHECK_RESULT(vkBeginCommandBuffer(uploadCmdBuffer, &beginInfo));
 
        VkImageMemoryBarrier barrier{};
        barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
        barrier.oldLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
        barrier.newLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
        barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.image = spectrumImage;
        barrier.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        barrier.subresourceRange.baseMipLevel = 0;
        barrier.subresourceRange.levelCount = 1;
        barrier.subresourceRange.baseArrayLayer = 0;
        barrier.subresourceRange.layerCount = 1;
        barrier.srcAccessMask = VK_ACCESS_SHADER_READ_BIT;
        barrier.dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
        vkCmdPipelineBarrier(uploadCmdBuffer, VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, VK_PIPELINE_STAGE_TRANSFER_BIT, 0, 0, nullptr, 0, nullptr, 1, &barrier);
 
        VkBufferImageCopy region{};
        region.imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        region.imageSubresource.mipLevel = 0;
        region.imageSubresource.baseArrayLayer = 0;
        region.imageSubresource.layerCount = 1;
        region.imageExtent = {bins, 1, 1};
        vkCmdCopyBufferToImage(uploadCmdBuffer, persistentStagingBuffer, spectrumImage, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &region);
 
        barrier.oldLayout = VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL;
        barrier.newLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
        barrier.srcAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
        barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT;
        vkCmdPipelineBarrier(uploadCmdBuffer, VK_PIPELINE_STAGE_TRANSFER_BIT, VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT, 0, 0, nullptr, 0, nullptr, 1, &barrier);
 
        VK_CHECK_RESULT(vkEndCommandBuffer(uploadCmdBuffer));
        VkSubmitInfo submitInfo{};
        submitInfo.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO;
        submitInfo.commandBufferCount = 1;
        submitInfo.pCommandBuffers = &uploadCmdBuffer;
        VK_CHECK_RESULT(vkQueueSubmit(graphicsQueue, 1, &submitInfo, uploadFence));
        VK_CHECK_RESULT(vkWaitForFences(device, 1, &uploadFence, VK_TRUE, UINT64_MAX));
    }

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 1787 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");
        }
        if (spriteImageFormat != VK_FORMAT_R8G8B8A8_UNORM || spriteBytesPerPixel != 4) {
            throw mxvk::Exception("VKSprite::updateTexture cannot update an RGBA16 sprite; use "
                                  "updateTextureRgba16");
        }
        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 1740 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);
    }

updateTextureRgba16()

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

Replace an RGBA16 UNORM sprite from native-endian uint16 data.

Parameters

pixels	Pointer to four uint16 components per pixel.
width	Buffer width.
height	Buffer height.
pitch	Row stride in bytes (0 = tightly packed).

Definition at line 1864 of file mxvk_sprite.cpp.

                                                                                                {
        if (pixels == nullptr) {
            throw mxvk::Exception("VKSprite::updateTextureRgba16 called with null pixel data");
        }
        if (!spriteLoaded || spriteImageFormat != VK_FORMAT_R16G16B16A16_UNORM || spriteBytesPerPixel != 8) {
            throw mxvk::Exception("VKSprite::updateTextureRgba16 requires an RGBA16 sprite");
        }
        if (width != spriteWidth || height != spriteHeight || width <= 0 || height <= 0) {
            throw mxvk::Exception("VKSprite::updateTextureRgba16 dimensions do not match");
        }
 
        const int rowBytes = width * 8;
        const int sourcePitch = pitch > 0 ? pitch : rowBytes;
        if (sourcePitch < rowBytes) {
            throw mxvk::Exception("VKSprite::updateTextureRgba16 pitch is too small");
        }
        if (sourcePitch == rowBytes) {
            updateSpriteTexture(pixels, static_cast<uint32_t>(width), static_cast<uint32_t>(height));
            return;
        }
 
        std::vector<uint16_t> packed(static_cast<size_t>(width) * static_cast<size_t>(height) * 4U);
        const auto *source = reinterpret_cast<const uint8_t *>(pixels);
        auto *destination = reinterpret_cast<uint8_t *>(packed.data());
        for (int row = 0; row < height; ++row) {
            std::memcpy(destination + static_cast<size_t>(row) * rowBytes, source + static_cast<size_t>(row) * sourcePitch, static_cast<size_t>(rowBytes));
        }
        updateSpriteTexture(packed.data(), static_cast<uint32_t>(width), static_cast<uint32_t>(height));
    }

Member Data Documentation

MAX_CUSTOM_UNIFORMS

std::size_t mxvk::VK_Sprite::MAX_CUSTOM_UNIFORMS = 64

staticconstexpr

Definition at line 58 of file mxvk_sprite.hpp.

spriteSampler

VkSampler mxvk::VK_Sprite::spriteSampler = VK_NULL_HANDLE

Texture sampler.

Definition at line 271 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