example::MasterPieceWindow Class Reference

Inheritance diagram for example::MasterPieceWindow:

Public Types
enum class	PresentModePreference { LowLatency , Vsync }

Public Member Functions
VK_Sprite *	attachPostProcessingShader (const std::string &fragmentShaderPath, float p1=0.0f, float p2=0.0f, float p3=0.0f, float p4=0.0f)
	Attach a full-screen post-processing fragment shader.
std::vector< VK_Sprite * >	attachPostProcessingShaders (const std::vector< PostProcessingEffect > &effects)
void	clearTextQueue ()
	Clear all queued text draw calls for the current frame.
VulkanContext	context () const
VK_Sprite *	createSprite (const std::string &pngPath, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Create a sprite from a PNG file and register it with this window.
VK_Sprite *	createSprite (int width, int height, const std::string &vertexShaderPath, const std::string &fragmentShaderPath, uint32_t spectrumBinCount, uint32_t spectrumHistoryLayerCount)
	Create a blank sprite with live FFT and FFT-history descriptors.
VK_Sprite *	createSprite (int width, int height, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="", uint32_t spectrumBinCount=0)
	Create a blank sprite texture and register it with this window.
VK_Sprite *	createSprite (SDL_Surface *surface, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Create a sprite from an SDL surface and register it with this window.
VK_Sprite3D *	createSprite3D (const std::string &pngPath, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Create a world-space billboard sprite from a PNG file.
VK_Sprite3D *	createSprite3D (SDL_Surface *surface, const std::string &vertexShaderPath="", const std::string &fragmentShaderPath="")
	Create a world-space billboard sprite from an SDL surface.
void	detachPostProcessingShader ()
	Detach the current post-processing shader and return to direct swapchain rendering.
void	enablePostProcessing (VK_Sprite *sprite)
bool	ensureRenderResources ()
	Ensure deferred render resources are initialized.
void	event (SDL_Event &e) override
	Handle one SDL event.
void	event (SDL_Event &e) override
	Handle one SDL event.
VkCommandPool	getCommandPool () const noexcept
	Get the command pool used for graphics/upload work.
VkFormat	getDepthFormat () const noexcept
	Get the depth format used for dynamic rendering attachments.
VkDevice	getDevice () const noexcept
	Get the Vulkan logical device handle.
VkQueue	getGraphicsQueue () const noexcept
	Get the graphics queue handle.
VkPhysicalDevice	getPhysicalDevice () const noexcept
	Get the Vulkan physical device handle.
VkPipelineCache	getPipelineCache () const noexcept
	Get the persistent Vulkan pipeline cache used by framework pipelines.
VkExtent2D	getRenderExtent () const noexcept
	Get the active scene/post-processing extent.
SDL_Window *	getSDLWindow () const noexcept
	Get the underlying SDL window handle.
VkExtent2D	getSwapchainExtent () const noexcept
	Get the current swapchain extent.
VkFormat	getSwapchainFormat () const noexcept
	Get the swapchain color format.
size_t	getSwapchainImageCount () const noexcept
	Get the number of swapchain images currently allocated.
bool	getTextDimensions (const std::string &text, int &width, int &height)
	Measure text dimensions in pixels.
bool	getTextDimensions (const std::string &text, int &width, int &height, const Font &font)
bool	getTextDimensions (const std::string &text, int &width, int &height, TTF_Font *font)
virtual bool	initVulkan (bool validiation)
	Initialize Vulkan state.
void	loop ()
	Run the main event/render loop.
	MasterPieceWindow (const std::string &path, int width, int height, bool fullscreen, bool enable_vsync)
	MasterPieceWindow (const std::string &path, int width, int height, bool fullscreen, bool enable_vsync, const FramebufferDimensions &framebuffer)
virtual void	onPrepareFrameRendering (VkCommandBuffer cmd, uint32_t image_index)
	Record resource transitions that must happen before dynamic rendering begins.
void	printPreviewText (const std::string &text, int x, int y, const SDL_Color &col)
	Queue preview-only text after frame readback.
void	printPreviewText (const std::string &text, int x, int y, const SDL_Color &col, const Font &font)
void	printText (const std::string &text, int x, int y, const SDL_Color &col)
	Queue a text string for rendering during the current frame.
void	printText (const std::string &text, int x, int y, const SDL_Color &col, const Font &font)
void	printText (const std::string &text, int x, int y, const SDL_Color &col, TTF_Font *font)
void	proc () override
	Execute one processing/update step.
void	proc () override
	Execute one processing/update step.
void	release ()
	Release Vulkan and SDL resources.
virtual void	render ()
	Render one frame.
void	saveSnapshot (const std::string &path)
	Save the most recently rendered window contents as a PNG file.
bool	screenshotEnabled () const noexcept
	Check whether F10 screenshot capture is enabled.
void	setClearColor (float r, float g, float b, float a=1.0f)
	Set the per-frame color attachment clear color.
void	setEnableScreenshot (bool enabled) noexcept
	Enable or disable F10 screenshot capture.
void	setFont (const std::string &fontPath, int fontSize=24)
	Set the active text-render font.
void	setFrameReadbackEnabled (bool enabled) noexcept
	Enable or disable readback of each rendered swapchain frame.
void	setPostProcessingEnabled (bool enabled)
void	setPostProcessingShaderParams (float p1=0.0f, float p2=0.0f, float p3=0.0f, float p4=0.0f)
	Set the post-processing shader params passed as a vec4 push constant.
void	setPostProcessingShaderParams (size_t effectIndex, float p1=0.0f, float p2=0.0f, float p3=0.0f, float p4=0.0f)
void	setPostProcessingShaderTimeEnabled (bool enabled)
	Keep shader param 1 updated with elapsed render time in seconds.
void	setPostProcessingShaderTimeEnabled (size_t effectIndex, bool enabled)
void	setPostProcessingTextureConsumerEnabled (bool enabled) noexcept
	Route the completed effect chain to a derived renderer as a sampled texture.
void	setPreviewFont (const std::string &fontPath, int fontSize=24)
	Set the preview-only HUD font independently of output text.
void	setRenderExtent (uint32_t width, uint32_t height)
	Render post-processing at a fixed extent independent of the preview window.
void	showCursor (bool on)
void	trimMemory ()
	Return transient Vulkan command-pool allocations to the driver when supported.
bool	validationEnabled () const
	Check whether Vulkan validation layers are currently enabled.
	~MasterPieceWindow () override
	~MasterPieceWindow () override

Static Public Member Functions
static VkBool32	debugCallback (VkDebugUtilsMessageSeverityFlagBitsEXT severity, VkDebugUtilsMessageTypeFlagsEXT type, const VkDebugUtilsMessengerCallbackDataEXT *callback_data, void *user_data)

Protected Member Functions
void	captureSnapshotPixels (std::vector< std::uint8_t > &rgba_pixels, uint32_t &width, uint32_t &height)
	Capture the most recently presented swapchain image as tightly packed RGBA8 pixels.
void	createDevice ()
	Create final device resources.
void	createLogicalDevice ()
	Create a logical Vulkan device from the selected physical device.
void	destroyFrameReadbackResources ()
void	dispatchFrameReadback (FrameReadbackSlot &slot)
void	ensureFrameReadbackResources ()
void	exit ()
	Request loop termination.
void	flushFrameReadbacks ()
	Wait for and deliver all pending pipelined frame readbacks.
bool	initWindow (const std::string &title, int width, int height, SDL_WindowFlags flags)
	Initialize SDL window resources.
virtual void	onConfigureDepthStencilAttachments (VkRenderingAttachmentInfo &depth_attachment, VkRenderingAttachmentInfo &stencil_attachment, uint32_t image_index)
	Allow derived classes to customize depth/stencil attachments for the main dynamic rendering pass.
virtual void	onFrameReadback (std::vector< std::uint8_t > &rgba_pixels, uint32_t width, uint32_t height)
	Receive one tightly packed RGBA8 copy of the rendered frame.
virtual void	onFrameReadbackScheduled ()
	Called after a presented frame has scheduled a readback.
virtual void	onRecordCustomRendering (VkCommandBuffer cmd, uint32_t image_index)
	Optional hook for derived classes to record extra draw commands.
virtual void	onRecordPostProcessingTexture (VkCommandBuffer cmd, uint32_t image_index, VkImageView texture_view, VkExtent2D texture_extent)
	Render a completed post-processing chain as custom scene input.
virtual void	onSwapchainAboutToRecreate ()
	Called right before swapchain-dependent resources are recreated.
virtual void	onSwapchainRecreated ()
	Called after swapchain and render resources are recreated.
void	pickDevice ()
	Pick a suitable Vulkan physical device.
void	renderStandaloneSprite (VK_Sprite &sprite, VkCommandBuffer cmd)
	Render one standalone sprite using the window's shared sprite pipeline.
void	renderStandaloneSprite (VK_Sprite &sprite, VkCommandBuffer cmd, VkExtent2D extent)

Static Protected Member Functions
static VkShaderModule	createShaderModule (VkDevice device, const std::vector< char > &spv_bytes)
	Create a shader module from SPIR-V bytecode.
static std::vector< char >	loadSpv (const std::string &path)
	Load a SPIR-V file from disk.

Protected Attributes
bool	active = false
VkClearColorValue	clear_color {{0.0f, 0.0f, 0.0f, 1.0f}}
std::vector< VkCommandBuffer >	command_buffers {}
VkCommandPool	command_pool = VK_NULL_HANDLE
uint32_t	current_frame = 0
VkDebugUtilsMessengerEXT	debug_messenger = VK_NULL_HANDLE
VkFormat	depth_format = VK_FORMAT_UNDEFINED
std::vector< bool >	depth_image_initialized {}
std::vector< VkDeviceMemory >	depth_image_memories {}
std::vector< VkImageView >	depth_image_views {}
std::vector< VkImage >	depth_images {}
VkDevice	device = VK_NULL_HANDLE
bool	font_configured = false
std::string	font_path {}
int	font_size = 24
bool	force_swapchain_recreate = false
bool	fps_counter_enabled = false
Font	fps_counter_font {}
bool	fps_counter_font_ready = false
uint32_t	fps_counter_frame_count = 0
std::chrono::steady_clock::time_point	fps_counter_sample_time {}
std::string	fps_counter_text = "FPS: --"
bool	frame_readback_enabled = false
std::array< FrameReadbackSlot, max_frames_in_flight >	frame_readback_slots {}
bool	framebuffer_resized = false
VkQueue	graphics_queue = VK_NULL_HANDLE
uint32_t	graphics_queue_family = invalid_queue_index
std::array< VkSemaphore, max_frames_in_flight >	image_available {}
std::vector< VkFence >	image_fences {}
std::array< VkFence, max_frames_in_flight >	in_flight_fences {}
VkInstance	instance = VK_NULL_HANDLE
std::chrono::steady_clock::time_point	last_memory_trim_time = std::chrono::steady_clock::now()
uint32_t	last_presented_image_index = invalid_queue_index
uint64_t	last_resize_event_ms = 0
uint32_t	latest_frame_readback_height = 0
std::vector< std::uint8_t >	latest_frame_readback_rgba {}
uint32_t	latest_frame_readback_width = 0
VK_Sprite *	owned_post_process_sprite = nullptr
std::vector< VK_Sprite * >	owned_post_process_sprites {}
VkPhysicalDevice	physical_device = VK_NULL_HANDLE
VkPipelineCache	pipeline_cache = VK_NULL_HANDLE
VK_Sprite *	post_process_composite_sprite = nullptr
std::vector< std::array< float, 4 > >	post_process_effect_params {}
std::vector< ShaderStage >	post_process_effect_stages {}
std::vector< std::chrono::steady_clock::time_point >	post_process_effect_start_times {}
std::vector< bool >	post_process_effect_time_enabled {}
bool	post_process_enabled = true
std::vector< std::vector< VkImage > >	post_process_images {}
std::vector< std::vector< bool > >	post_process_initialized {}
std::vector< std::vector< VkDeviceMemory > >	post_process_memories {}
std::array< float, 4 >	post_process_params {}
VK_Sprite *	post_process_present_sprite = nullptr
VK_Sprite *	post_process_sprite = nullptr
std::vector< VK_Sprite * >	post_process_sprites {}
std::chrono::steady_clock::time_point	post_process_start_time = std::chrono::steady_clock::now()
bool	post_process_texture_consumer_enabled = false
bool	post_process_time_enabled = false
std::vector< std::vector< VkImageView > >	post_process_views {}
PresentModePreference	present_mode_preference = PresentModePreference::LowLatency
VkQueue	present_queue = VK_NULL_HANDLE
uint32_t	present_queue_family = invalid_queue_index
bool	preview_text_queued = false
std::unique_ptr< VK_Text >	preview_text_renderer {}
VkExtent2D	render_extent_override {}
std::vector< VkSemaphore >	render_finished {}
std::vector< VkSwapchainKHR >	retired_swapchains
bool	screenshot_enabled = defaultEnableScreenshot()
uint32_t	screenshot_index = 0
std::string	screenshot_prefix = defaultExecutableName()
std::condition_variable	screenshot_queue_cv
std::mutex	screenshot_queue_mutex
std::deque< ScreenshotSaveTask >	screenshot_save_queue
std::thread	screenshot_worker
bool	screenshot_worker_stop = false
bool	sdl_initialized = false
VkDescriptorSetLayout	sprite_descriptor_set_layout = VK_NULL_HANDLE
VkPipeline	sprite_pipeline = VK_NULL_HANDLE
VkPipelineLayout	sprite_pipeline_layout = VK_NULL_HANDLE
bool	sprite_state_dirty = false
std::vector< std::unique_ptr< VK_Sprite > >	sprites {}
std::vector< std::unique_ptr< VK_Sprite3D > >	sprites3d {}
VkSurfaceKHR	surface = VK_NULL_HANDLE
VkSwapchainKHR	swapchain = VK_NULL_HANDLE
VkExtent2D	swapchain_extent {}
VkFormat	swapchain_format = VK_FORMAT_UNDEFINED
std::vector< bool >	swapchain_image_initialized {}
std::vector< VkImageView >	swapchain_image_views {}
std::vector< VkImage >	swapchain_images {}
bool	swapchain_supports_transfer_src = false
VkDescriptorSetLayout	text_descriptor_set_layout = VK_NULL_HANDLE
VkPipeline	text_pipeline = VK_NULL_HANDLE
VkPipelineLayout	text_pipeline_layout = VK_NULL_HANDLE
std::unique_ptr< VK_Text >	text_renderer {}
bool	text_state_dirty = false
bool	validation_enabled = false
bool	vulkan_library_loaded = false
std::unique_ptr< SDL_Window, SDLWindowDeleter >	window {}

Static Protected Attributes
static constexpr std::chrono::seconds	MEMORY_TRIM_INTERVAL {30}
static constexpr VkFormat	post_process_compute_format
static constexpr uint64_t	resize_settle_delay_ms = 150

Detailed Description

Definition at line 298 of file main.cpp.

Member Enumeration Documentation

PresentModePreference

enum class mxvk::VK_Window::PresentModePreference

stronginherited

Enumerator
LowLatency
Vsync

Definition at line 40 of file mxvk.hpp.

                                         {
            LowLatency,
            Vsync
        };

Constructor & Destructor Documentation

MasterPieceWindow() [1/2]

example::MasterPieceWindow::MasterPieceWindow ( const std::string & path, int width, int height, bool fullscreen, bool enable_vsync, const FramebufferDimensions & framebuffer )

inline

Definition at line 300 of file main.cpp.

            : mxvk::VK_Window("3D Math MasterPiece", width, height, fullscreen, MXVK_VALIDATION, enable_vsync),
              asset_root(resolveAssetRoot(path)),
              puzzle_asset_root(resolvePuzzleAssetRoot(resolveAssetRoot(path))),
              high_scores(scorePath(asset_root)),
              frame_width(framebuffer.width),
              frame_height(framebuffer.height) {
            setClearColor(0.0f, 0.0f, 0.0f, 1.0f);
            mxvk::BuildTables();
 
            const std::string font_path = dataPath("font.ttf");
            title_font.reset(font_path, 34);
            ui_font.reset(font_path, 20);
            setFont(font_path, 20);
 
            loadSprites();
            resetGame();
            setScreen(Screen::Intro);
            tryOpenFirstGamepad();
        }

~MasterPieceWindow() [1/2]

example::MasterPieceWindow::~MasterPieceWindow ( )

inlineoverride

Definition at line 321 of file main.cpp.

                                      {
            closeGamepad();
        }

MasterPieceWindow() [2/2]

example::MasterPieceWindow::MasterPieceWindow ( const std::string & path, int width, int height, bool fullscreen, bool enable_vsync )

inline

Definition at line 247 of file main.cpp.

            : mxvk::VK_Window("MasterPiece", width, height, fullscreen, MXVK_VALIDATION, enable_vsync),
              asset_root(resolveAssetRoot(path)),
              puzzle_asset_root(resolvePuzzleAssetRoot(resolveAssetRoot(path))),
              high_scores(scorePath(asset_root)) {
            setClearColor(0.02f, 0.02f, 0.03f, 1.0f);
 
            const std::string font_path = dataPath("font.ttf");
            title_font.reset(font_path, 34);
            ui_font.reset(font_path, 20);
            setFont(font_path, 20);
 
            loadSprites();
            resetGame();
            setScreen(Screen::Intro);
            tryOpenFirstGamepad();
        }

~MasterPieceWindow() [2/2]

example::MasterPieceWindow::~MasterPieceWindow ( )

inlineoverride

Definition at line 265 of file main.cpp.

                                      {
            closeGamepad();
        }

Member Function Documentation

attachPostProcessingShader()

VK_Sprite * mxvk::VK_Window::attachPostProcessingShader ( const std::string & fragmentShaderPath, float p1 = 0.0f, float p2 = 0.0f, float p3 = 0.0f, float p4 = 0.0f )

inherited

Attach a full-screen post-processing fragment shader.

The window renders the normal scene into an offscreen color target, then draws that target through the supplied sprite-compatible fragment shader into the swapchain. Shader params are passed through the existing sprite push-constant vec4.

Parameters

fragmentShaderPath	Post-process fragment shader SPIR-V path.
p1	First shader parameter.
p2	Second shader parameter.
p3	Third shader parameter.
p4	Fourth shader parameter.

Returns

Non-owning pointer to the internal post-process sprite for advanced setup.

Definition at line 1499 of file mxvk.cpp.

                                                                                                                                {
        const std::vector<VK_Sprite *> sprites = attachPostProcessingShaders({PostProcessingEffect{fragmentShaderPath, {p1, p2, p3, p4}, false}});
        return sprites.empty() ? nullptr : sprites.front();
    }

attachPostProcessingShaders()

std::vector< VK_Sprite * > mxvk::VK_Window::attachPostProcessingShaders ( const std::vector< PostProcessingEffect > & effects )

inherited

Definition at line 1504 of file mxvk.cpp.

                                                                                                                {
        detachPostProcessingShader();
 
        std::vector<VK_Sprite *> attachedSprites;
        attachedSprites.reserve(effects.size());
        for (size_t effect_index = 0; effect_index < effects.size();
             ++effect_index) {
            const PostProcessingEffect &effect = effects[effect_index];
            if (effect.fragmentShaderPath.empty()) {
                throw mxvk::Exception(
                    "Cannot attach a post-processing pass with an empty shader path");
            }
 
            const ShaderModuleInfo module_info =
                inspect_spirv(load_spv(effect.fragmentShaderPath));
            const ShaderStage stage = effect.stage == ShaderStage::Unknown
                                          ? module_info.stage
                                          : effect.stage;
            if (stage != ShaderStage::Fragment && stage != ShaderStage::Compute) {
                throw mxvk::Exception(
                    "Post-processing shaders must contain a fragment or compute entry point");
            }
            if (effect.stage != ShaderStage::Unknown &&
                effect.stage != module_info.stage) {
                throw mxvk::Exception(
                    "Post-processing shader stage does not match its SPIR-V entry point");
            }
 
            VK_Sprite *sprite = createSprite(
                1,
                1,
                resolveRuntimeShaderPath("sprite.vert.spv", MXVK_SPRITE_SHADER_DIR),
                "",
                effect.spectrumBinCount,
                effect.spectrumHistoryLayerCount);
            sprite->enableExtendedUBO();
            if (effect.historySource != nullptr) {
                sprite->shareHistoryTexture(*effect.historySource);
            }
            const bool final_fragment =
                stage == ShaderStage::Fragment &&
                effect_index + 1U == effects.size();
            if (stage == ShaderStage::Fragment) {
                if (!final_fragment) {
                    sprite->setColorAttachmentFormat(post_process_compute_format);
                }
                sprite->setFragmentShaderPath(effect.fragmentShaderPath);
            } else if (stage == ShaderStage::Compute) {
                sprite->enableComputeShader(
                    effect.fragmentShaderPath, module_info.localSizeX,
                    module_info.localSizeY, module_info.localSizeZ);
            }
            const uint32_t black_pixel = 0xFF000000u;
            sprite->updateTexture(&black_pixel, 1, 1);
            sprite->setShaderParams(effect.params[0], effect.params[1], effect.params[2], effect.params[3]);
 
            attachedSprites.push_back(sprite);
            owned_post_process_sprites.push_back(sprite);
            post_process_sprites.push_back(sprite);
            post_process_effect_params.push_back(effect.params);
            post_process_effect_time_enabled.push_back(effect.timeEnabled);
            post_process_effect_start_times.push_back(std::chrono::steady_clock::now());
            post_process_effect_stages.push_back(stage);
        }
 
        if (!post_process_effect_stages.empty()) {
            post_process_present_sprite = createSprite(1, 1);
            const uint32_t black_pixel = 0xFF000000u;
            post_process_present_sprite->updateTexture(&black_pixel, 1, 1);
            owned_post_process_sprites.push_back(post_process_present_sprite);
 
            post_process_composite_sprite = createSprite(1, 1);
            post_process_composite_sprite->updateTexture(&black_pixel, 1, 1);
            owned_post_process_sprites.push_back(post_process_composite_sprite);
        }
 
        post_process_sprite = attachedSprites.empty() ? nullptr : attachedSprites.front();
        owned_post_process_sprite = post_process_sprite;
        post_process_params = post_process_effect_params.empty() ? std::array<float, 4>{} : post_process_effect_params.front();
        post_process_time_enabled = !post_process_effect_time_enabled.empty() && post_process_effect_time_enabled.front();
        post_process_start_time = post_process_effect_start_times.empty() ? std::chrono::steady_clock::now() : post_process_effect_start_times.front();
        if (device != VK_NULL_HANDLE && !swapchain_images.empty()) {
            createPostProcessTargets();
        }
        sprite_state_dirty = true;
        return attachedSprites;
    }

captureSnapshotPixels()

void mxvk::VK_Window::captureSnapshotPixels ( std::vector< std::uint8_t > & rgba_pixels, uint32_t & width, uint32_t & height )

protectedinherited

Capture the most recently presented swapchain image as tightly packed RGBA8 pixels.

This performs a synchronous GPU readback and may briefly stall rendering.

Definition at line 827 of file mxvk.cpp.

                                                                                                               {
        if (!latest_frame_readback_rgba.empty()) {
            rgba_pixels = latest_frame_readback_rgba;
            width = latest_frame_readback_width;
            height = latest_frame_readback_height;
            return;
        }
        if (device == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE || graphics_queue == VK_NULL_HANDLE) {
            throw mxvk::Exception("captureSnapshotPixels called before Vulkan render resources are ready");
        }
        if (last_presented_image_index == invalid_queue_index ||
            last_presented_image_index >= swapchain_images.size() ||
            last_presented_image_index >= image_fences.size()) {
            throw mxvk::Exception("captureSnapshotPixels called before a frame has been presented");
        }
        const bool capture_offscreen =
            render_extent_override.width > 0U &&
            render_extent_override.height > 0U &&
            !post_process_images.empty() &&
            !post_process_initialized.empty() &&
            last_presented_image_index < post_process_images.front().size() &&
            last_presented_image_index <
                post_process_initialized.front().size() &&
            post_process_images.front()[last_presented_image_index] !=
                VK_NULL_HANDLE &&
            post_process_initialized.front()[last_presented_image_index];
        if (!capture_offscreen && !swapchain_supports_transfer_src) {
            throw mxvk::Exception(
                "captureSnapshotPixels requires swapchain transfer-source support");
        }
        const VkExtent2D source_extent =
            capture_offscreen ? getRenderExtent() : swapchain_extent;
        const VkImage source_image =
            capture_offscreen
                ? post_process_images.front()[last_presented_image_index]
                : swapchain_images[last_presented_image_index];
        const VkImageLayout source_layout =
            capture_offscreen ? VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL
                              : VK_IMAGE_LAYOUT_PRESENT_SRC_KHR;
        if (source_extent.width == 0U || source_extent.height == 0U) {
            throw mxvk::Exception("captureSnapshotPixels cannot capture an empty swapchain extent");
        }
 
        const bool format_is_bgra =
            swapchain_format == VK_FORMAT_B8G8R8A8_UNORM ||
            swapchain_format == VK_FORMAT_B8G8R8A8_SRGB;
        const bool format_is_rgba =
            swapchain_format == VK_FORMAT_R8G8B8A8_UNORM ||
            swapchain_format == VK_FORMAT_R8G8B8A8_SRGB;
        if (!format_is_bgra && !format_is_rgba) {
            throw mxvk::Exception(std::format("captureSnapshotPixels unsupported swapchain format: {}", static_cast<int>(swapchain_format)));
        }
 
        const VkDeviceSize row_bytes =
            static_cast<VkDeviceSize>(source_extent.width) * 4U;
        const VkDeviceSize image_bytes =
            row_bytes * static_cast<VkDeviceSize>(source_extent.height);
 
        VkBuffer readback_buffer = VK_NULL_HANDLE;
        VkDeviceMemory readback_memory = VK_NULL_HANDLE;
        VkCommandBuffer command_buffer = VK_NULL_HANDLE;
        VkFence copy_fence = VK_NULL_HANDLE;
 
        auto cleanup = [&]() {
            if (copy_fence != VK_NULL_HANDLE) {
                vkDestroyFence(device, copy_fence, nullptr);
            }
            if (command_buffer != VK_NULL_HANDLE) {
                vkFreeCommandBuffers(device, command_pool, 1, &command_buffer);
            }
            if (readback_buffer != VK_NULL_HANDLE) {
                vkDestroyBuffer(device, readback_buffer, nullptr);
            }
            if (readback_memory != VK_NULL_HANDLE) {
                vkFreeMemory(device, readback_memory, nullptr);
            }
        };
 
        try {
            VkBufferCreateInfo buffer_info{};
            buffer_info.sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO;
            buffer_info.size = image_bytes;
            buffer_info.usage = VK_BUFFER_USAGE_TRANSFER_DST_BIT;
            buffer_info.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
            if (vkCreateBuffer(device, &buffer_info, nullptr, &readback_buffer) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to create readback buffer");
            }
 
            VkMemoryRequirements memory_requirements{};
            vkGetBufferMemoryRequirements(device, readback_buffer, &memory_requirements);
 
            VkPhysicalDeviceMemoryProperties memory_properties{};
            vkGetPhysicalDeviceMemoryProperties(physical_device, &memory_properties);
            uint32_t memory_type_index = invalid_queue_index;
            constexpr VkMemoryPropertyFlags REQUIRED_PROPERTIES =
                VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT;
            constexpr VkMemoryPropertyFlags PREFERRED_PROPERTIES =
                REQUIRED_PROPERTIES | VK_MEMORY_PROPERTY_HOST_CACHED_BIT;
            for (VkMemoryPropertyFlags properties :
                 {PREFERRED_PROPERTIES, REQUIRED_PROPERTIES}) {
                for (uint32_t index = 0;
                     index < memory_properties.memoryTypeCount; ++index) {
                    const bool type_matches =
                        (memory_requirements.memoryTypeBits & (1U << index)) != 0U;
                    const bool properties_match =
                        (memory_properties.memoryTypes[index].propertyFlags &
                         properties) == properties;
                    if (type_matches && properties_match) {
                        memory_type_index = index;
                        break;
                    }
                }
                if (memory_type_index != invalid_queue_index) {
                    break;
                }
            }
            if (memory_type_index == invalid_queue_index) {
                throw mxvk::Exception("captureSnapshotPixels failed to find host-visible coherent memory");
            }
 
            VkMemoryAllocateInfo allocation_info{};
            allocation_info.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
            allocation_info.allocationSize = memory_requirements.size;
            allocation_info.memoryTypeIndex = memory_type_index;
            if (vkAllocateMemory(device, &allocation_info, nullptr, &readback_memory) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to allocate readback memory");
            }
            if (vkBindBufferMemory(device, readback_buffer, readback_memory, 0) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to bind readback memory");
            }
 
            VkCommandBufferAllocateInfo command_buffer_info{};
            command_buffer_info.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO;
            command_buffer_info.commandPool = command_pool;
            command_buffer_info.level = VK_COMMAND_BUFFER_LEVEL_PRIMARY;
            command_buffer_info.commandBufferCount = 1;
            if (vkAllocateCommandBuffers(device, &command_buffer_info, &command_buffer) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to allocate command buffer");
            }
 
            VkFenceCreateInfo fence_info{};
            fence_info.sType = VK_STRUCTURE_TYPE_FENCE_CREATE_INFO;
            if (vkCreateFence(device, &fence_info, nullptr, &copy_fence) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to create copy fence");
            }
 
            VkFence source_fence = image_fences[last_presented_image_index];
            if (source_fence != VK_NULL_HANDLE) {
                const VkResult wait_result = vkWaitForFences(device, 1, &source_fence, VK_TRUE, UINT64_MAX);
                if (wait_result != VK_SUCCESS) {
                    throw mxvk::Exception(std::format("captureSnapshotPixels failed waiting for rendered frame: {}", static_cast<int>(wait_result)));
                }
            }
 
            const VkResult idle_result = vkDeviceWaitIdle(device);
            if (idle_result != VK_SUCCESS) {
                throw mxvk::Exception(std::format("captureSnapshotPixels failed waiting for device idle: {}", static_cast<int>(idle_result)));
            }
 
            VkCommandBufferBeginInfo begin_info{};
            begin_info.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
            begin_info.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
            if (vkBeginCommandBuffer(command_buffer, &begin_info) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to begin copy command buffer");
            }
 
            VkImageMemoryBarrier2 to_transfer_barrier{};
            to_transfer_barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2;
            to_transfer_barrier.srcStageMask =
                capture_offscreen ? VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT
                                  : VK_PIPELINE_STAGE_2_NONE;
            to_transfer_barrier.srcAccessMask =
                capture_offscreen ? VK_ACCESS_2_SHADER_SAMPLED_READ_BIT
                                  : VK_ACCESS_2_NONE;
            to_transfer_barrier.dstStageMask = VK_PIPELINE_STAGE_2_TRANSFER_BIT;
            to_transfer_barrier.dstAccessMask = VK_ACCESS_2_TRANSFER_READ_BIT;
            to_transfer_barrier.oldLayout = source_layout;
            to_transfer_barrier.newLayout = VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL;
            to_transfer_barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
            to_transfer_barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
            to_transfer_barrier.image = source_image;
            to_transfer_barrier.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
            to_transfer_barrier.subresourceRange.baseMipLevel = 0;
            to_transfer_barrier.subresourceRange.levelCount = 1;
            to_transfer_barrier.subresourceRange.baseArrayLayer = 0;
            to_transfer_barrier.subresourceRange.layerCount = 1;
 
            VkDependencyInfo to_transfer_dependency{};
            to_transfer_dependency.sType = VK_STRUCTURE_TYPE_DEPENDENCY_INFO;
            to_transfer_dependency.imageMemoryBarrierCount = 1;
            to_transfer_dependency.pImageMemoryBarriers = &to_transfer_barrier;
            vkCmdPipelineBarrier2(command_buffer, &to_transfer_dependency);
 
            VkBufferImageCopy copy_region{};
            copy_region.bufferOffset = 0;
            copy_region.bufferRowLength = 0;
            copy_region.bufferImageHeight = 0;
            copy_region.imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
            copy_region.imageSubresource.mipLevel = 0;
            copy_region.imageSubresource.baseArrayLayer = 0;
            copy_region.imageSubresource.layerCount = 1;
            copy_region.imageOffset = {0, 0, 0};
            copy_region.imageExtent = {source_extent.width, source_extent.height,
                                       1};
            vkCmdCopyImageToBuffer(command_buffer,
                                   source_image,
                                   VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
                                   readback_buffer,
                                   1,
                                   &copy_region);
 
            VkImageMemoryBarrier2 to_present_barrier{};
            to_present_barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER_2;
            to_present_barrier.srcStageMask = VK_PIPELINE_STAGE_2_TRANSFER_BIT;
            to_present_barrier.srcAccessMask = VK_ACCESS_2_TRANSFER_READ_BIT;
            to_present_barrier.dstStageMask =
                capture_offscreen ? VK_PIPELINE_STAGE_2_FRAGMENT_SHADER_BIT
                                  : VK_PIPELINE_STAGE_2_NONE;
            to_present_barrier.dstAccessMask =
                capture_offscreen ? VK_ACCESS_2_SHADER_SAMPLED_READ_BIT
                                  : VK_ACCESS_2_NONE;
            to_present_barrier.oldLayout = VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL;
            to_present_barrier.newLayout = source_layout;
            to_present_barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
            to_present_barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
            to_present_barrier.image = source_image;
            to_present_barrier.subresourceRange = to_transfer_barrier.subresourceRange;
 
            VkDependencyInfo to_present_dependency{};
            to_present_dependency.sType = VK_STRUCTURE_TYPE_DEPENDENCY_INFO;
            to_present_dependency.imageMemoryBarrierCount = 1;
            to_present_dependency.pImageMemoryBarriers = &to_present_barrier;
            vkCmdPipelineBarrier2(command_buffer, &to_present_dependency);
 
            if (vkEndCommandBuffer(command_buffer) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to end copy command buffer");
            }
 
            VkCommandBufferSubmitInfo command_submit_info{};
            command_submit_info.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_SUBMIT_INFO;
            command_submit_info.commandBuffer = command_buffer;
 
            VkSubmitInfo2 submit_info{};
            submit_info.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO_2;
            submit_info.commandBufferInfoCount = 1;
            submit_info.pCommandBufferInfos = &command_submit_info;
 
            const VkResult submit_result = vkQueueSubmit2(graphics_queue, 1, &submit_info, copy_fence);
            if (submit_result != VK_SUCCESS) {
                throw mxvk::Exception(std::format("captureSnapshotPixels failed to submit copy command: {}", static_cast<int>(submit_result)));
            }
            const VkResult copy_wait_result = vkWaitForFences(device, 1, &copy_fence, VK_TRUE, UINT64_MAX);
            if (copy_wait_result != VK_SUCCESS) {
                throw mxvk::Exception(std::format("captureSnapshotPixels failed waiting for copy: {}", static_cast<int>(copy_wait_result)));
            }
 
            void *mapped = nullptr;
            if (vkMapMemory(device, readback_memory, 0, image_bytes, 0, &mapped) != VK_SUCCESS) {
                throw mxvk::Exception("captureSnapshotPixels failed to map readback memory");
            }
 
            const auto *src = static_cast<const std::uint8_t *>(mapped);
            rgba_pixels.resize(static_cast<std::size_t>(image_bytes));
            for (std::size_t i = 0; i < rgba_pixels.size(); i += 4U) {
                if (format_is_bgra) {
                    rgba_pixels[i + 0U] = src[i + 2U];
                    rgba_pixels[i + 1U] = src[i + 1U];
                    rgba_pixels[i + 2U] = src[i + 0U];
                    rgba_pixels[i + 3U] = src[i + 3U];
                } else {
                    rgba_pixels[i + 0U] = src[i + 0U];
                    rgba_pixels[i + 1U] = src[i + 1U];
                    rgba_pixels[i + 2U] = src[i + 2U];
                    rgba_pixels[i + 3U] = src[i + 3U];
                }
            }
            vkUnmapMemory(device, readback_memory);
            width = source_extent.width;
            height = source_extent.height;
        } catch (...) {
            cleanup();
            throw;
        }
 
        cleanup();
    }

clearTextQueue()

void mxvk::VK_Window::clearTextQueue ( )

inherited

Clear all queued text draw calls for the current frame.

Definition at line 4096 of file mxvk.cpp.

                                   {
        if (text_renderer) {
            text_renderer->clearQueue();
        }
        if (preview_text_renderer) {
            preview_text_renderer->clearQueue();
        }
        preview_text_queued = false;
    }

context()

VulkanContext mxvk::VK_Window::context ( ) const

inherited

Definition at line 59 of file mxvk.cpp.

                                           {
        return VulkanContext{
            .device = getDevice(),
            .physical_device = getPhysicalDevice(),
            .graphics_queue = getGraphicsQueue(),
            .command_pool = getCommandPool(),
        };
    }

createDevice()

void mxvk::VK_Window::createDevice ( )

protectedinherited

Create final device resources.

Definition at line 2086 of file mxvk.cpp.

                                 {
        std::cout << "mxvk: entering createDevice\n";
        if (device == VK_NULL_HANDLE) {
            std::cout << "vk: skipping createDevice because logical device is null\n";
            return;
        }
 
        const bool sync_ready =
            std::ranges::all_of(image_available.begin(), image_available.end(), [](VkSemaphore semaphore) { return semaphore != VK_NULL_HANDLE; }) &&
            render_finished.size() == swapchain_images.size() &&
            std::ranges::all_of(render_finished.begin(), render_finished.end(), [](VkSemaphore semaphore) { return semaphore != VK_NULL_HANDLE; }) &&
            std::ranges::all_of(in_flight_fences.begin(), in_flight_fences.end(), [](VkFence fence) { return fence != VK_NULL_HANDLE; });
 
        if (swapchain != VK_NULL_HANDLE && command_pool != VK_NULL_HANDLE && !command_buffers.empty() &&
            sync_ready && image_fences.size() == swapchain_images.size()) {
            std::cout << "vk: createDevice skipped because render resources are already initialized\n";
            return;
        }
 
        std::cout << "vk: creating swapchain\n";
        if (!createSwapchain(VK_NULL_HANDLE)) {
            std::cout << "vk: createSwapchain failed\n";
            return;
        }
 
        std::cout << "vk: creating render resources\n";
        if (!createRenderResources()) {
            std::cout << "vk: createRenderResources failed\n";
            return;
        }
 
        std::cout << "vk: creating synchronization objects\n";
        if (!createSyncObjects()) {
            std::cout << "vk: createSyncObjects failed\n";
            return;
        }
 
        std::cout << "mxvk: createDevice complete\n";
    }

createLogicalDevice()

void mxvk::VK_Window::createLogicalDevice ( )

protectedinherited

Create a logical Vulkan device from the selected physical device.

Definition at line 1955 of file mxvk.cpp.

                                        {
        std::cout << "mxvk: entering createLogicalDevice\n";
        if (physical_device == VK_NULL_HANDLE) {
            std::cout << "vk: cannot create logical device without a selected physical device\n";
            return;
        }
 
        std::vector<uint32_t> queue_families{};
        queue_families.push_back(graphics_queue_family);
        if (present_queue_family != graphics_queue_family) {
            queue_families.push_back(present_queue_family);
        }
 
        constexpr float queue_priority = 1.0f;
        std::vector<VkDeviceQueueCreateInfo> queue_create_infos{};
        queue_create_infos.reserve(queue_families.size());
        for (const uint32_t family : queue_families) {
            VkDeviceQueueCreateInfo queue_create_info{};
            queue_create_info.sType = VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO;
            queue_create_info.queueFamilyIndex = family;
            queue_create_info.queueCount = 1;
            queue_create_info.pQueuePriorities = &queue_priority;
            queue_create_infos.push_back(queue_create_info);
        }
        uint32_t device_extension_count = 0;
        vkEnumerateDeviceExtensionProperties(physical_device, nullptr, &device_extension_count, nullptr);
        std::vector<VkExtensionProperties> device_extensions(device_extension_count);
        if (device_extension_count > 0U) {
            vkEnumerateDeviceExtensionProperties(physical_device, nullptr, &device_extension_count, device_extensions.data());
        }
 
        [[maybe_unused]] const auto has_device_extension = [&device_extensions](const char *extension_name) {
            return std::ranges::any_of(
                device_extensions,
                [extension_name](const VkExtensionProperties &ext) {
                    return std::strcmp(ext.extensionName, extension_name) == 0;
                });
        };
 
        std::vector<const char *> required_device_extensions = {VK_KHR_SWAPCHAIN_EXTENSION_NAME};
#if defined(MXVK_CUDA) && defined(__linux__)
        if (has_device_extension(VK_KHR_EXTERNAL_MEMORY_FD_EXTENSION_NAME)) {
            if (has_device_extension(VK_KHR_EXTERNAL_MEMORY_EXTENSION_NAME)) {
                required_device_extensions.push_back(VK_KHR_EXTERNAL_MEMORY_EXTENSION_NAME);
            }
            required_device_extensions.push_back(VK_KHR_EXTERNAL_MEMORY_FD_EXTENSION_NAME);
            std::cout << "vk: enabling external memory FD support for CUDA interop\n";
        } else {
            std::cout << "vk: external memory FD support unavailable; CUDA texture interop will fall back\n";
        }
#endif
 
#if defined(MXVK_USE_MOLTENVK)
        const bool has_portability_subset = std::ranges::any_of(
            device_extensions,
            [](const VkExtensionProperties &ext) {
                return std::strcmp(ext.extensionName, VK_KHR_PORTABILITY_SUBSET_EXTENSION_NAME) == 0;
            });
 
        if (has_portability_subset) {
            required_device_extensions.push_back(VK_KHR_PORTABILITY_SUBSET_EXTENSION_NAME);
        }
#endif
        VkPhysicalDeviceFeatures2 features2{};
        features2.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2;
        VkPhysicalDeviceVulkan13Features supported_vulkan13_features{};
        supported_vulkan13_features.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES;
        features2.pNext = &supported_vulkan13_features;
        vkGetPhysicalDeviceFeatures2(physical_device, &features2);
 
        std::cout << std::format(
            "vk: feature support - synchronization2={}, dynamicRendering={}, shaderFloat64={}, fillModeNonSolid={}, samplerAnisotropy={}\n",
            supported_vulkan13_features.synchronization2 == VK_TRUE ? "true" : "false",
            supported_vulkan13_features.dynamicRendering == VK_TRUE ? "true" : "false",
            features2.features.shaderFloat64 == VK_TRUE ? "true" : "false",
            features2.features.fillModeNonSolid == VK_TRUE ? "true" : "false",
            features2.features.samplerAnisotropy == VK_TRUE ? "true" : "false");
 
        if (supported_vulkan13_features.synchronization2 != VK_TRUE) {
            std::cout << "vk: synchronization2 is unsupported on selected physical device\n";
            return;
        }
        if (supported_vulkan13_features.dynamicRendering != VK_TRUE) {
            std::cout << "vk: dynamic rendering is unsupported on selected physical device\n";
            return;
        }
        VkPhysicalDeviceVulkan13Features vulkan13_features{};
        vulkan13_features.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_VULKAN_1_3_FEATURES;
        vulkan13_features.synchronization2 = VK_TRUE;
        vulkan13_features.dynamicRendering = VK_TRUE;
 
        VkPhysicalDeviceFeatures2 enabled_features2{};
        enabled_features2.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2;
        enabled_features2.features.shaderFloat64 = features2.features.shaderFloat64;
        enabled_features2.features.fillModeNonSolid = features2.features.fillModeNonSolid;
        enabled_features2.features.samplerAnisotropy = features2.features.samplerAnisotropy;
 
        enabled_features2.pNext = &vulkan13_features;
 
        VkDeviceCreateInfo create_info{};
        create_info.sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO;
        create_info.pNext = &enabled_features2;
        create_info.queueCreateInfoCount = static_cast<uint32_t>(queue_create_infos.size());
        create_info.pQueueCreateInfos = queue_create_infos.data();
        create_info.enabledExtensionCount = static_cast<uint32_t>(required_device_extensions.size());
        create_info.ppEnabledExtensionNames = required_device_extensions.data();
        create_info.enabledLayerCount = 0;
        create_info.ppEnabledLayerNames = nullptr;
        create_info.pEnabledFeatures = nullptr;
 
        std::cout << "vk: creating logical device\n";
        if (vkCreateDevice(physical_device, &create_info, nullptr, &device) != VK_SUCCESS) {
            std::cout << "vk: logical device creation failed\n";
            device = VK_NULL_HANDLE;
            return;
        }
 
        std::cout << "vk: loading device-level function pointers via volk\n";
        volkLoadDevice(device);
        if (vkQueueSubmit2 == nullptr || vkCmdBeginRendering == nullptr || vkCmdEndRendering == nullptr || vkCmdPipelineBarrier2 == nullptr) {
            std::cout << "vk: required dynamic rendering/synchronization function pointers are unavailable\n";
            vkDestroyDevice(device, nullptr);
            device = VK_NULL_HANDLE;
            return;
        }
        std::cout << "vk: retrieving graphics and present queues\n";
        vkGetDeviceQueue(device, graphics_queue_family, 0, &graphics_queue);
        vkGetDeviceQueue(device, present_queue_family, 0, &present_queue);
        std::cout << "mxvk: createLogicalDevice complete\n";
    }

createShaderModule()

VkShaderModule mxvk::VK_Window::createShaderModule ( VkDevice device, const std::vector< char > & spv_bytes )

staticprotectedinherited

Create a shader module from SPIR-V bytecode.

Parameters

device	Logical Vulkan device used to create the module.
spv_bytes	SPIR-V bytecode payload.

Returns

Created shader module handle.

Exceptions

mxvk::Exception

when inputs are invalid or module creation fails.

Definition at line 145 of file mxvk.cpp.

                                                                                                  {
        return mxvk::create_shader_module(device, spv_bytes);
    }

createSprite() [1/4]

VK_Sprite * mxvk::VK_Window::createSprite ( const std::string & pngPath, const std::string & vertexShaderPath = "", const std::string & fragmentShaderPath = "" )

inherited

Create a sprite from a PNG file and register it with this window.

Parameters

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

Returns

Non-owning pointer to the created sprite.

Definition at line 4608 of file mxvk.cpp.

                                                                                                                                       {
        if (device == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create sprite before Vulkan device initialization");
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            createDevice();
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create sprite before swapchain and command resources are available");
        }
 
        if (sprite_descriptor_set_layout == VK_NULL_HANDLE) {
            createSpriteDescriptorSetLayout();
        }
 
        auto sprite = std::make_unique<VK_Sprite>(device, physical_device, graphics_queue, command_pool);
        sprite->setPipelineCache(pipeline_cache);
        sprite->setDescriptorSetLayout(sprite_descriptor_set_layout);
        sprite->setColorAttachmentFormat(swapchain_format);
        sprite->setDepthAttachmentFormat(depth_format);
 
        if (!vertexShaderPath.empty()) {
            sprite->setVertexShaderPath(vertexShaderPath);
        }
 
        sprite->loadSprite(pngPath, fragmentShaderPath);
 
        VK_Sprite *const sprite_ptr = sprite.get();
        sprites.push_back(std::move(sprite));
        sprite_state_dirty = true;
        return sprite_ptr;
    }

createSprite() [2/4]

VK_Sprite * mxvk::VK_Window::createSprite ( int width, int height, const std::string & vertexShaderPath, const std::string & fragmentShaderPath, uint32_t spectrumBinCount, uint32_t spectrumHistoryLayerCount )

inherited

Create a blank sprite with live FFT and FFT-history descriptors.

Parameters

width	Texture width in pixels.
height	Texture height in pixels.
vertexShaderPath	Optional custom vertex shader SPIR-V path.
fragmentShaderPath	Optional custom fragment shader SPIR-V path.
spectrumBinCount	Binding-3 1-D spectrum size.
spectrumHistoryLayerCount	Requested binding-4 history depth.

Returns

Non-owning pointer to the created sprite.

Definition at line 4685 of file mxvk.cpp.

                                                                           {
        if (width <= 0 || height <= 0) {
            throw mxvk::Exception("Sprite dimensions must be positive");
        }
        if (device == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create sprite before Vulkan device initialization");
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            createDevice();
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create sprite before swapchain and command resources are available");
        }
 
        if (sprite_descriptor_set_layout == VK_NULL_HANDLE) {
            createSpriteDescriptorSetLayout();
        }
 
        auto sprite = std::make_unique<VK_Sprite>(device, physical_device, graphics_queue, command_pool);
        sprite->setPipelineCache(pipeline_cache);
        sprite->setDescriptorSetLayout(sprite_descriptor_set_layout);
        sprite->setColorAttachmentFormat(swapchain_format);
        sprite->setDepthAttachmentFormat(depth_format);
        if (!fragmentShaderPath.empty()) {
            sprite->enableExtendedUBO();
        }
        if (spectrumBinCount > 0) {
            sprite->enableSpectrumTexture(spectrumBinCount);
        }
        if (spectrumHistoryLayerCount > 0) {
            if (spectrumBinCount == 0) {
                throw mxvk::Exception(
                    "Spectrum history requires a positive spectrum bin count");
            }
            sprite->enableSpectrumHistoryTexture(
                spectrumBinCount, spectrumHistoryLayerCount);
        }
 
        sprite->createEmptySprite(width, height, vertexShaderPath, fragmentShaderPath);
 
        VK_Sprite *const sprite_ptr = sprite.get();
        sprites.push_back(std::move(sprite));
        sprite_state_dirty = true;
        return sprite_ptr;
    }

createSprite() [3/4]

VK_Sprite * mxvk::VK_Window::createSprite ( int width, int height, const std::string & vertexShaderPath = "", const std::string & fragmentShaderPath = "", uint32_t spectrumBinCount = 0 )

inherited

Create a blank sprite texture and register it with this window.

Parameters

width	Texture width in pixels.
height	Texture height in pixels.
vertexShaderPath	Optional custom vertex shader SPIR-V path.
fragmentShaderPath	Optional custom fragment shader SPIR-V path.
spectrumBinCount	Optional binding-3 1-D spectrum size to create before the pipeline.

Returns

Non-owning pointer to the created sprite.

Definition at line 4680 of file mxvk.cpp.

                                                                                                                                                               {
        return createSprite(width, height, vertexShaderPath, fragmentShaderPath,
                            spectrumBinCount, 0);
    }

createSprite() [4/4]

VK_Sprite * mxvk::VK_Window::createSprite ( SDL_Surface * surface, const std::string & vertexShaderPath = "", const std::string & fragmentShaderPath = "" )

inherited

Create a sprite from an SDL surface and register it with this window.

Parameters

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

Returns

Non-owning pointer to the created sprite.

Definition at line 4641 of file mxvk.cpp.

                                                                                                                                   {
        if (surface == nullptr) {
            throw mxvk::Exception("Cannot create sprite from a null SDL surface");
        }
        if (device == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create sprite before Vulkan device initialization");
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            createDevice();
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create sprite before swapchain and command resources are available");
        }
 
        if (sprite_descriptor_set_layout == VK_NULL_HANDLE) {
            createSpriteDescriptorSetLayout();
        }
 
        auto sprite = std::make_unique<VK_Sprite>(device, physical_device, graphics_queue, command_pool);
        sprite->setPipelineCache(pipeline_cache);
        sprite->setDescriptorSetLayout(sprite_descriptor_set_layout);
        sprite->setColorAttachmentFormat(swapchain_format);
        sprite->setDepthAttachmentFormat(depth_format);
 
        if (!vertexShaderPath.empty()) {
            sprite->setVertexShaderPath(vertexShaderPath);
        }
        if (!fragmentShaderPath.empty()) {
            sprite->enableExtendedUBO();
        }
 
        sprite->loadSprite(surface, fragmentShaderPath);
 
        VK_Sprite *const sprite_ptr = sprite.get();
        sprites.push_back(std::move(sprite));
        sprite_state_dirty = true;
        return sprite_ptr;
    }

createSprite3D() [1/2]

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

inherited

Create a world-space billboard sprite from a PNG file.

Parameters

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

Returns

Non-owning pointer to the created 3D sprite batch.

Definition at line 4735 of file mxvk.cpp.

                                                                                                                                           {
        if (device == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create 3D sprite before Vulkan device initialization");
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            createDevice();
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create 3D sprite before swapchain and command resources are available");
        }
 
        const std::string vertPath = vertexShaderPath.empty()
                                         ? resolveRuntimeShaderPath("sprite3d.vert.spv", MXVK_SPRITE3D_SHADER_DIR)
                                         : vertexShaderPath;
        const std::string fragPath = fragmentShaderPath.empty()
                                         ? resolveRuntimeShaderPath("sprite3d.frag.spv", MXVK_SPRITE3D_SHADER_DIR)
                                         : fragmentShaderPath;
 
        auto sprite = std::make_unique<VK_Sprite3D>();
        sprite->load(this, pngPath, vertPath, fragPath);
 
        VK_Sprite3D *const sprite_ptr = sprite.get();
        sprites3d.push_back(std::move(sprite));
        return sprite_ptr;
    }

createSprite3D() [2/2]

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

inherited

Create a world-space billboard sprite from an SDL surface.

Parameters

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

Returns

Non-owning pointer to the created 3D sprite batch.

Definition at line 4761 of file mxvk.cpp.

                                                                                                                                       {
        if (surface == nullptr) {
            throw mxvk::Exception("Cannot create 3D sprite from a null SDL surface");
        }
        if (device == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create 3D sprite before Vulkan device initialization");
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            createDevice();
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot create 3D sprite before swapchain and command resources are available");
        }
 
        const std::string vertPath = vertexShaderPath.empty()
                                         ? resolveRuntimeShaderPath("sprite3d.vert.spv", MXVK_SPRITE3D_SHADER_DIR)
                                         : vertexShaderPath;
        const std::string fragPath = fragmentShaderPath.empty()
                                         ? resolveRuntimeShaderPath("sprite3d.frag.spv", MXVK_SPRITE3D_SHADER_DIR)
                                         : fragmentShaderPath;
 
        auto sprite = std::make_unique<VK_Sprite3D>();
        sprite->load(this, surface, vertPath, fragPath);
 
        VK_Sprite3D *const sprite_ptr = sprite.get();
        sprites3d.push_back(std::move(sprite));
        return sprite_ptr;
    }

debugCallback()

VkBool32 mxvk::VK_Window::debugCallback ( VkDebugUtilsMessageSeverityFlagBitsEXT severity, VkDebugUtilsMessageTypeFlagsEXT type, const VkDebugUtilsMessengerCallbackDataEXT * callback_data, void * user_data )

staticinherited

Definition at line 44 of file mxvk.cpp.

                                                                                                                                                                                                                                                               {
        const char *message = (callback_data != nullptr && callback_data->pMessage != nullptr)
                                  ? callback_data->pMessage
                                  : "Unknown Vulkan validation message";
 
        if ((severity & VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT) != 0U) {
            std::cerr << std::format("vk validation error: {}\n", message);
        } else if ((severity & VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) != 0U) {
            std::cerr << std::format("vk validation warning: {}\n", message);
        } else {
            std::cout << std::format("vk validation: {}\n", message);
        }
        return VK_FALSE;
    }

destroyFrameReadbackResources()

void mxvk::VK_Window::destroyFrameReadbackResources ( )

protectedinherited

Definition at line 1301 of file mxvk.cpp.

                                                  {
        for (FrameReadbackSlot &slot : frame_readback_slots) {
            if (device != VK_NULL_HANDLE && slot.mapped != nullptr &&
                slot.memory != VK_NULL_HANDLE) {
                vkUnmapMemory(device, slot.memory);
            }
            slot.mapped = nullptr;
            if (device != VK_NULL_HANDLE && slot.buffer != VK_NULL_HANDLE) {
                vkDestroyBuffer(device, slot.buffer, nullptr);
            }
            slot.buffer = VK_NULL_HANDLE;
            if (device != VK_NULL_HANDLE && slot.memory != VK_NULL_HANDLE) {
                vkFreeMemory(device, slot.memory, nullptr);
            }
            slot.memory = VK_NULL_HANDLE;
            slot.size = 0;
            slot.width = 0;
            slot.height = 0;
            slot.format = VK_FORMAT_UNDEFINED;
            slot.pending = false;
        }
        latest_frame_readback_rgba.clear();
        latest_frame_readback_width = 0;
        latest_frame_readback_height = 0;
    }

detachPostProcessingShader()

void mxvk::VK_Window::detachPostProcessingShader ( )

inherited

Detach the current post-processing shader and return to direct swapchain rendering.

Definition at line 1592 of file mxvk.cpp.

                                               {
        if (device != VK_NULL_HANDLE && !post_process_sprites.empty()) {
            vkDeviceWaitIdle(device);
        }
 
        post_process_sprite = nullptr;
        destroyPostProcessTargets();
        post_process_present_sprite = nullptr;
        post_process_composite_sprite = nullptr;
        post_process_time_enabled = false;
 
        if (!owned_post_process_sprites.empty()) {
            const std::vector<VK_Sprite *> sprites_to_remove = owned_post_process_sprites;
            sprites.erase(
                std::remove_if(
                    sprites.begin(),
                    sprites.end(),
                    [&sprites_to_remove](const std::unique_ptr<VK_Sprite> &sprite) {
                        return std::ranges::find(sprites_to_remove, sprite.get()) != sprites_to_remove.end();
                    }),
                sprites.end());
            sprite_state_dirty = true;
        }
        owned_post_process_sprite = nullptr;
        owned_post_process_sprites.clear();
        post_process_sprites.clear();
        post_process_effect_params.clear();
        post_process_effect_time_enabled.clear();
        post_process_effect_start_times.clear();
        post_process_effect_stages.clear();
    }

dispatchFrameReadback()

void mxvk::VK_Window::dispatchFrameReadback ( FrameReadbackSlot & slot )

protectedinherited

Definition at line 1122 of file mxvk.cpp.

                                                                 {
        if (!slot.pending) {
            return;
        }
        if (slot.mapped == nullptr || slot.width == 0U || slot.height == 0U) {
            slot.pending = false;
            return;
        }
 
        const auto *source = static_cast<const std::uint8_t *>(slot.mapped);
        const std::size_t pixel_bytes =
            static_cast<std::size_t>(slot.width) * slot.height * 4U;
        latest_frame_readback_rgba.resize(pixel_bytes);
        const bool format_is_bgra =
            slot.format == VK_FORMAT_B8G8R8A8_UNORM ||
            slot.format == VK_FORMAT_B8G8R8A8_SRGB;
        for (std::size_t offset = 0; offset < pixel_bytes; offset += 4U) {
            if (format_is_bgra) {
                latest_frame_readback_rgba[offset + 0U] = source[offset + 2U];
                latest_frame_readback_rgba[offset + 1U] = source[offset + 1U];
                latest_frame_readback_rgba[offset + 2U] = source[offset + 0U];
                latest_frame_readback_rgba[offset + 3U] = source[offset + 3U];
            } else {
                latest_frame_readback_rgba[offset + 0U] = source[offset + 0U];
                latest_frame_readback_rgba[offset + 1U] = source[offset + 1U];
                latest_frame_readback_rgba[offset + 2U] = source[offset + 2U];
                latest_frame_readback_rgba[offset + 3U] = source[offset + 3U];
            }
        }
 
        latest_frame_readback_width = slot.width;
        latest_frame_readback_height = slot.height;
        slot.pending = false;
        onFrameReadback(latest_frame_readback_rgba, latest_frame_readback_width,
                        latest_frame_readback_height);
    }

enablePostProcessing()

void mxvk::VK_Window::enablePostProcessing ( VK_Sprite * sprite )

inherited

Definition at line 1668 of file mxvk.cpp.

                                                          {
        if (owned_post_process_sprite != nullptr && sprite != owned_post_process_sprite) {
            std::vector<VK_Sprite *> sprites_to_remove = owned_post_process_sprites;
            if (sprites_to_remove.empty()) {
                sprites_to_remove.push_back(owned_post_process_sprite);
            }
            sprites.erase(
                std::remove_if(
                    sprites.begin(),
                    sprites.end(),
                    [&sprites_to_remove](const std::unique_ptr<VK_Sprite> &existing_sprite) {
                        return std::ranges::find(sprites_to_remove, existing_sprite.get()) != sprites_to_remove.end();
                    }),
                sprites.end());
            owned_post_process_sprite = nullptr;
            owned_post_process_sprites.clear();
            sprite_state_dirty = true;
        }
        post_process_sprite = sprite;
        post_process_sprites = sprite == nullptr ? std::vector<VK_Sprite *>{} : std::vector<VK_Sprite *>{sprite};
        post_process_effect_params.assign(post_process_sprites.size(), post_process_params);
        post_process_effect_time_enabled.assign(post_process_sprites.size(), post_process_time_enabled);
        post_process_effect_start_times.assign(post_process_sprites.size(), post_process_start_time);
        if (device != VK_NULL_HANDLE && !swapchain_images.empty()) {
            createPostProcessTargets();
        }
    }

ensureFrameReadbackResources()

void mxvk::VK_Window::ensureFrameReadbackResources ( )

protectedinherited

Definition at line 1183 of file mxvk.cpp.

                                                 {
        if (!frame_readback_enabled) {
            return;
        }
        if (!swapchain_supports_transfer_src) {
            throw mxvk::Exception("frame readback requires swapchain transfer-source support");
        }
 
        const VkExtent2D readback_extent = getRenderExtent();
        const VkDeviceSize required_size =
            static_cast<VkDeviceSize>(readback_extent.width) *
            readback_extent.height * 4U;
        if (required_size == 0U) {
            throw mxvk::Exception("frame readback cannot use an empty swapchain extent");
        }
        const bool resources_ready = std::ranges::all_of(
            frame_readback_slots, [&](const FrameReadbackSlot &slot) {
                return slot.buffer != VK_NULL_HANDLE && slot.mapped != nullptr &&
                       slot.size >= required_size;
            });
        if (resources_ready) {
            return;
        }
 
        if (device != VK_NULL_HANDLE) {
            flushFrameReadbacks();
            vkDeviceWaitIdle(device);
        }
        destroyFrameReadbackResources();
 
        VkBufferCreateInfo buffer_info{};
        buffer_info.sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO;
        buffer_info.size = required_size;
        buffer_info.usage = VK_BUFFER_USAGE_TRANSFER_DST_BIT;
        buffer_info.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
        VkPhysicalDeviceMemoryProperties memory_properties{};
        vkGetPhysicalDeviceMemoryProperties(physical_device, &memory_properties);
        constexpr VkMemoryPropertyFlags REQUIRED_PROPERTIES =
            VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT;
        constexpr VkMemoryPropertyFlags PREFERRED_PROPERTIES =
            REQUIRED_PROPERTIES | VK_MEMORY_PROPERTY_HOST_CACHED_BIT;
        bool memory_type_logged = false;
        try {
            for (FrameReadbackSlot &slot : frame_readback_slots) {
                if (vkCreateBuffer(device, &buffer_info, nullptr, &slot.buffer) !=
                    VK_SUCCESS) {
                    throw mxvk::Exception(
                        "failed to create pipelined frame-readback buffer");
                }
 
                VkMemoryRequirements memory_requirements{};
                vkGetBufferMemoryRequirements(device, slot.buffer,
                                              &memory_requirements);
                uint32_t memory_type_index = invalid_queue_index;
                for (VkMemoryPropertyFlags properties :
                     {PREFERRED_PROPERTIES, REQUIRED_PROPERTIES}) {
                    for (uint32_t index = 0;
                         index < memory_properties.memoryTypeCount; ++index) {
                        const bool type_matches =
                            (memory_requirements.memoryTypeBits & (1U << index)) != 0U;
                        const bool properties_match =
                            (memory_properties.memoryTypes[index].propertyFlags &
                             properties) == properties;
                        if (type_matches && properties_match) {
                            memory_type_index = index;
                            break;
                        }
                    }
                    if (memory_type_index != invalid_queue_index) {
                        break;
                    }
                }
                if (memory_type_index == invalid_queue_index) {
                    throw mxvk::Exception(
                        "failed to find host-visible frame-readback memory");
                }
                if (!memory_type_logged) {
                    const VkMemoryPropertyFlags selected_properties =
                        memory_properties.memoryTypes[memory_type_index]
                            .propertyFlags;
                    std::cout << std::format(
                        "mxvk: frame readback memory type {} ({})\n",
                        memory_type_index,
                        (selected_properties & VK_MEMORY_PROPERTY_HOST_CACHED_BIT) !=
                                0U
                            ? "host cached"
                            : "host coherent fallback");
                    memory_type_logged = true;
                }
 
                VkMemoryAllocateInfo allocation_info{};
                allocation_info.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
                allocation_info.allocationSize = memory_requirements.size;
                allocation_info.memoryTypeIndex = memory_type_index;
                if (vkAllocateMemory(device, &allocation_info, nullptr,
                                     &slot.memory) != VK_SUCCESS) {
                    throw mxvk::Exception(
                        "failed to allocate frame-readback memory");
                }
                if (vkBindBufferMemory(device, slot.buffer, slot.memory, 0) !=
                    VK_SUCCESS) {
                    throw mxvk::Exception("failed to bind frame-readback memory");
                }
                if (vkMapMemory(device, slot.memory, 0, required_size, 0,
                                &slot.mapped) != VK_SUCCESS) {
                    throw mxvk::Exception("failed to map frame-readback memory");
                }
                slot.size = required_size;
            }
        } catch (...) {
            destroyFrameReadbackResources();
            throw;
        }
        latest_frame_readback_rgba.clear();
        latest_frame_readback_width = 0;
        latest_frame_readback_height = 0;
    }

ensureRenderResources()

bool mxvk::VK_Window::ensureRenderResources ( )

inherited

Ensure deferred render resources are initialized.

Returns

true when swapchain, command pool, and sync objects are ready.

Definition at line 1847 of file mxvk.cpp.

                                          {
        const auto sync_ready = [this]() {
            return std::ranges::all_of(image_available.begin(), image_available.end(), [](VkSemaphore semaphore) { return semaphore != VK_NULL_HANDLE; }) &&
                   render_finished.size() == swapchain_images.size() &&
                   std::ranges::all_of(render_finished.begin(), render_finished.end(), [](VkSemaphore semaphore) { return semaphore != VK_NULL_HANDLE; }) &&
                   std::ranges::all_of(in_flight_fences.begin(), in_flight_fences.end(), [](VkFence fence) { return fence != VK_NULL_HANDLE; });
        };
 
        if (device == VK_NULL_HANDLE) {
            return false;
        }
 
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE || command_buffers.empty() || !sync_ready() ||
            image_fences.size() != swapchain_images.size()) {
            createDevice();
        }
 
        return (swapchain != VK_NULL_HANDLE && command_pool != VK_NULL_HANDLE && !command_buffers.empty() && sync_ready() &&
                image_fences.size() == swapchain_images.size());
    }

event() [1/2]

void example::MasterPieceWindow::event ( SDL_Event & e )

inlineoverridevirtual

Handle one SDL event.

Parameters

e	SDL event to process.

Reimplemented from mxvk::VK_Window.

Definition at line 325 of file main.cpp.

                                          {
            if (e.type == SDL_EVENT_QUIT) {
                exit();
                return;
            }
 
            if (e.type == SDL_EVENT_GAMEPAD_ADDED) {
                openGamepad(e.gdevice.which);
                return;
            }
 
            if (e.type == SDL_EVENT_GAMEPAD_REMOVED) {
                if (gamepad != nullptr && e.gdevice.which == gamepadId) {
                    closeGamepad();
                    tryOpenFirstGamepad();
                }
                return;
            }
 
            if (e.type == SDL_EVENT_GAMEPAD_BUTTON_DOWN) {
                handleControllerButton(e.gbutton.button);
                return;
            }
 
            if (screen == Screen::NameEntry && e.type == SDL_EVENT_TEXT_INPUT) {
                handleNameText(e.text.text);
                return;
            }
 
            if (e.type != SDL_EVENT_KEY_DOWN) {
                return;
            }
 
            switch (screen) {
            case Screen::Intro:
                if (isConfirmKey(e.key.key) || e.key.key == SDLK_ESCAPE) {
                    setScreen(Screen::Menu);
                }
                break;
            case Screen::Menu:
                handleMenuKey(e.key.key);
                break;
            case Screen::Game:
                handleGameKey(e.key.key);
                break;
            case Screen::Scores:
            case Screen::Credits:
                if (e.key.key == SDLK_RETURN || e.key.key == SDLK_ESCAPE) {
                    setScreen(Screen::Menu);
                }
                break;
            case Screen::NameEntry:
                handleNameKey(e.key.key);
                break;
            }
        }

event() [2/2]

void example::MasterPieceWindow::event ( SDL_Event & e )

inlineoverridevirtual

Handle one SDL event.

Parameters

e	SDL event to process.

Reimplemented from mxvk::VK_Window.

Definition at line 269 of file main.cpp.

                                          {
            if (e.type == SDL_EVENT_QUIT) {
                exit();
                return;
            }
 
            if (e.type == SDL_EVENT_GAMEPAD_ADDED) {
                openGamepad(e.gdevice.which);
                return;
            }
 
            if (e.type == SDL_EVENT_GAMEPAD_REMOVED) {
                if (gamepad != nullptr && e.gdevice.which == gamepadId) {
                    closeGamepad();
                    tryOpenFirstGamepad();
                }
                return;
            }
 
            if (e.type == SDL_EVENT_GAMEPAD_BUTTON_DOWN) {
                handleControllerButton(e.gbutton.button);
                return;
            }
 
            if (screen == Screen::NameEntry && e.type == SDL_EVENT_TEXT_INPUT) {
                handleNameText(e.text.text);
                return;
            }
 
            if (e.type != SDL_EVENT_KEY_DOWN) {
                return;
            }
 
            switch (screen) {
            case Screen::Intro:
                if (isConfirmKey(e.key.key) || e.key.key == SDLK_ESCAPE) {
                    setScreen(Screen::Menu);
                }
                break;
            case Screen::Menu:
                handleMenuKey(e.key.key);
                break;
            case Screen::Game:
                handleGameKey(e.key.key);
                break;
            case Screen::Scores:
            case Screen::Credits:
                if (e.key.key == SDLK_RETURN || e.key.key == SDLK_ESCAPE) {
                    setScreen(Screen::Menu);
                }
                break;
            case Screen::NameEntry:
                handleNameKey(e.key.key);
                break;
            }
        }

exit()

void mxvk::VK_Window::exit ( )

protectedinherited

Request loop termination.

Definition at line 1429 of file mxvk.cpp.

                         {
        active = false;
    }

flushFrameReadbacks()

void mxvk::VK_Window::flushFrameReadbacks ( )

protectedinherited

Wait for and deliver all pending pipelined frame readbacks.

Derived recorders should call this before closing their output writer.

Definition at line 1159 of file mxvk.cpp.

                                        {
        if (device == VK_NULL_HANDLE) {
            return;
        }
        const bool has_pending = std::ranges::any_of(
            frame_readback_slots,
            [](const FrameReadbackSlot &slot) { return slot.pending; });
        if (!has_pending) {
            return;
        }
 
        const VkResult wait_result = vkDeviceWaitIdle(device);
        if (wait_result != VK_SUCCESS) {
            throw mxvk::Exception(std::format(
                "frame readback flush failed waiting for the device (VkResult={})",
                static_cast<int>(wait_result)));
        }
        for (uint32_t offset = 0; offset < max_frames_in_flight; ++offset) {
            const uint32_t slot_index =
                (current_frame + offset) % max_frames_in_flight;
            dispatchFrameReadback(frame_readback_slots[slot_index]);
        }
    }

getCommandPool()

VkCommandPool mxvk::VK_Window::getCommandPool ( ) const

inlinenodiscardnoexceptinherited

Get the command pool used for graphics/upload work.

Definition at line 201 of file mxvk.hpp.

{ return command_pool; }

getDepthFormat()

VkFormat mxvk::VK_Window::getDepthFormat ( ) const

inlinenodiscardnoexceptinherited

Get the depth format used for dynamic rendering attachments.

Definition at line 224 of file mxvk.hpp.

{ return depth_format; }

getDevice()

VkDevice mxvk::VK_Window::getDevice ( ) const

inlinenodiscardnoexceptinherited

Get the Vulkan logical device handle.

Definition at line 192 of file mxvk.hpp.

{ return device; }

getGraphicsQueue()

VkQueue mxvk::VK_Window::getGraphicsQueue ( ) const

inlinenodiscardnoexceptinherited

Get the graphics queue handle.

Definition at line 198 of file mxvk.hpp.

{ return graphics_queue; }

getPhysicalDevice()

VkPhysicalDevice mxvk::VK_Window::getPhysicalDevice ( ) const

inlinenodiscardnoexceptinherited

Get the Vulkan physical device handle.

Definition at line 195 of file mxvk.hpp.

{ return physical_device; }

getPipelineCache()

VkPipelineCache mxvk::VK_Window::getPipelineCache ( ) const

inlinenodiscardnoexceptinherited

Get the persistent Vulkan pipeline cache used by framework pipelines.

Definition at line 204 of file mxvk.hpp.

{ return pipeline_cache; }

getRenderExtent()

VkExtent2D mxvk::VK_Window::getRenderExtent ( ) const

nodiscardnoexceptinherited

Get the active scene/post-processing extent.

Definition at line 1492 of file mxvk.cpp.

                                                         {
        return render_extent_override.width > 0U &&
                       render_extent_override.height > 0U
                   ? render_extent_override
                   : swapchain_extent;
    }

getSDLWindow()

SDL_Window * mxvk::VK_Window::getSDLWindow ( ) const

inlinenodiscardnoexceptinherited

Get the underlying SDL window handle.

Definition at line 189 of file mxvk.hpp.

{ return window.get(); }

getSwapchainExtent()

VkExtent2D mxvk::VK_Window::getSwapchainExtent ( ) const

inlinenodiscardnoexceptinherited

Get the current swapchain extent.

Definition at line 210 of file mxvk.hpp.

{ return swapchain_extent; }

getSwapchainFormat()

VkFormat mxvk::VK_Window::getSwapchainFormat ( ) const

inlinenodiscardnoexceptinherited

Get the swapchain color format.

Definition at line 207 of file mxvk.hpp.

{ return swapchain_format; }

getSwapchainImageCount()

size_t mxvk::VK_Window::getSwapchainImageCount ( ) const

inlinenodiscardnoexceptinherited

Get the number of swapchain images currently allocated.

Definition at line 227 of file mxvk.hpp.

{ return swapchain_images.size(); }

getTextDimensions() [1/3]

bool mxvk::VK_Window::getTextDimensions ( const std::string & text, int & width, int & height )

nodiscardinherited

Measure text dimensions in pixels.

Parameters

text	Text string to measure.
width	Output width in pixels.
height	Output height in pixels.

Returns

true when measurement succeeded.

Definition at line 4142 of file mxvk.cpp.

                                                                                    {
        if (!font_configured) {
            throw mxvk::Exception("getTextDimensions requires setFont() to be called first");
        }
 
        if (!text_renderer) {
            ensureTextRenderer();
        }
        if (!text_renderer) {
            width = 0;
            height = 0;
            return false;
        }
        return text_renderer->getTextDimensions(text, width, height);
    }

getTextDimensions() [2/3]

bool mxvk::VK_Window::getTextDimensions ( const std::string & text, int & width, int & height, const Font & font )

nodiscardinherited

Definition at line 4174 of file mxvk.cpp.

                                                                                                      {
        if (!font) {
            width = 0;
            height = 0;
            return false;
        }
 
        ensureTextRenderer(font.path(), font.size());
        if (!text_renderer) {
            width = 0;
            height = 0;
            return false;
        }
        return text_renderer->getTextDimensions(text, width, height, font);
    }

getTextDimensions() [3/3]

bool mxvk::VK_Window::getTextDimensions ( const std::string & text, int & width, int & height, TTF_Font * font )

nodiscardinherited

Definition at line 4158 of file mxvk.cpp.

                                                                                                    {
        if (font == nullptr) {
            width = 0;
            height = 0;
            return false;
        }
 
        ensureTextRenderer(resolveDefaultFontPath(), font_size);
        if (!text_renderer) {
            width = 0;
            height = 0;
            return false;
        }
        return text_renderer->getTextDimensions(text, width, height, font);
    }

initVulkan()

bool mxvk::VK_Window::initVulkan ( bool validiation )

virtualinherited

Initialize Vulkan state.

Parameters

validiation

Enables validation-related behavior when true.

Returns

true on success, false otherwise.

Definition at line 334 of file mxvk.cpp.

                                               {
        std::cout << std::format("mxvk: entering initVulkan (validation={})\n", validiation);
        validation_enabled = validiation;
 
        if (window == nullptr) {
            std::cerr << "mxvk: Cannot initialize Vulkan without an SDL window\n";
            return false;
        }
 
        if (instance != VK_NULL_HANDLE) {
            std::cout << "vk: instance already initialized; skipping initVulkan\n";
            return true;
        }
 
        std::cout << "vk: initializing volk from SDL's Vulkan loader\n";
        const auto get_instance_proc_addr = reinterpret_cast<PFN_vkGetInstanceProcAddr>(
            SDL_Vulkan_GetVkGetInstanceProcAddr());
        if (get_instance_proc_addr == nullptr) {
            std::cerr << std::format(
                "mxvk: SDL did not provide vkGetInstanceProcAddr: {}\n", SDL_GetError());
            return false;
        }
        volkInitializeCustom(get_instance_proc_addr);
 
        unsigned int extension_count = 0;
        std::cout << "SDL3: querying Vulkan instance extensions required by SDL\n";
        const char *const *extensions = SDL_Vulkan_GetInstanceExtensions(&extension_count);
        if (extensions == nullptr || extension_count == 0U) {
            std::cerr << std::format("mxvk: Failed to get Vulkan instance extensions: {}\n", SDL_GetError());
            return false;
        }
        std::cout << std::format("vk: SDL provided {} required instance extension(s)\n", extension_count);
 
        std::vector<const char *> enabled_extensions(extensions, extensions + extension_count);
 
#if defined(MXVK_USE_MOLTENVK)
        const auto append_instance_extension_if_missing = [&enabled_extensions](const char *extension_name) {
            const bool exists = std::ranges::any_of(
                enabled_extensions,
                [extension_name](const char *existing) { return std::strcmp(existing, extension_name) == 0; });
            if (!exists) {
                enabled_extensions.push_back(extension_name);
            }
        };
        append_instance_extension_if_missing(VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME);
        append_instance_extension_if_missing(VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME);
#endif
 
        std::vector<const char *> enabled_layers{};
        VkDebugUtilsMessengerCreateInfoEXT debug_create_info{};
        if (validation_enabled) {
            if (!hasValidationLayerSupport()) {
                if (shouldLogMissingValidationLayer()) {
                    std::cerr << std::format(
                        "mxvk: validation layer '{}' is not available; continuing without validation\n",
                        validation_layer_name);
                }
                validation_enabled = false;
            } else {
                enabled_layers.push_back(validation_layer_name);
                enabled_extensions.push_back(VK_EXT_DEBUG_UTILS_EXTENSION_NAME);
                const std::optional<VkDebugUtilsMessengerCreateInfoEXT> maybe_debug_create_info =
                    makeDebugMessengerCreateInfo();
                if (!maybe_debug_create_info.has_value()) {
                    std::cerr << "mxvk: failed to construct debug messenger create info\n";
                    validation_enabled = false;
                    enabled_layers.clear();
                } else {
                    debug_create_info = maybe_debug_create_info.value();
                }
            }
        }
 
        VkApplicationInfo app_info{};
        app_info.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
        app_info.pApplicationName = "mxvk";
        app_info.applicationVersion = VK_MAKE_VERSION(0, 1, 0);
        app_info.pEngineName = "mxvk";
        app_info.engineVersion = VK_MAKE_VERSION(MXVK_VERSION_CODE_MAJOR, MXVK_VERSION_CODE_MINOR, MXVK_VERSION_CODE_PATCH);
        app_info.apiVersion = VK_API_VERSION_1_4;
 
        VkInstanceCreateInfo create_info{};
        create_info.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
        create_info.pApplicationInfo = &app_info;
        create_info.enabledExtensionCount = extension_count;
        create_info.ppEnabledExtensionNames = enabled_extensions.data();
        create_info.enabledLayerCount = static_cast<uint32_t>(enabled_layers.size());
        create_info.ppEnabledLayerNames = enabled_layers.empty() ? nullptr : enabled_layers.data();
        create_info.pNext = validation_enabled ? &debug_create_info : nullptr;
 
        create_info.enabledExtensionCount = static_cast<uint32_t>(enabled_extensions.size());
#if defined(MXVK_USE_MOLTENVK)
        create_info.flags |= VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR;
#endif
 
        std::cout << "vk: creating Vulkan instance\n";
        if (vkCreateInstance(&create_info, nullptr, &instance) != VK_SUCCESS) {
            std::cerr << "mxvk: Failed to create Vulkan instance\n";
            instance = VK_NULL_HANDLE;
            return false;
        }
 
        std::cout << "vk: loading Vulkan instance function pointers via volk\n";
        volkLoadInstance(instance);
 
        setupDebugMessenger();
 
        uint32_t instanceVersion = 0;
        if (vkEnumerateInstanceVersion != nullptr) {
            vkEnumerateInstanceVersion(&instanceVersion);
        }
        std::cout << "vk: Vulkan instance version: "
                  << VK_VERSION_MAJOR(instanceVersion) << "."
                  << VK_VERSION_MINOR(instanceVersion) << "."
                  << VK_VERSION_PATCH(instanceVersion) << "\n";
        std::cout << "mxvk: engine version: "
                  << MXVK_VERSION_CODE_MAJOR << "."
                  << MXVK_VERSION_CODE_MINOR << "."
                  << MXVK_VERSION_CODE_PATCH << "\n";
 
        std::cout << "SDL3: creating Vulkan presentation surface from SDL window\n";
        if (!SDL_Vulkan_CreateSurface(window.get(), instance, nullptr, &surface)) {
            std::cerr << std::format("mxvk: Failed to create Vulkan surface: {}\n", SDL_GetError());
            cleanupDebugMessenger();
            vkDestroyInstance(instance, nullptr);
            instance = VK_NULL_HANDLE;
            surface = VK_NULL_HANDLE;
            return false;
        }
 
        std::cout << "mxvk: selecting suitable physical device\n";
        pickDevice();
        if (physical_device == VK_NULL_HANDLE) {
            std::cerr << "mxvk: Failed to find a Vulkan physical device with present support\n";
            return false;
        }
 
        std::cout << "mxvk: creating logical device and queues\n";
        createLogicalDevice();
        if (device == VK_NULL_HANDLE) {
            std::cerr << "mxvk: Failed to create Vulkan logical device\n";
            return false;
        }
        createPipelineCache();
 
        std::cout << "mxvk: deferring swapchain/render/sync resource creation until first frame\n";
 
        std::cout << "mxvk: initVulkan complete\n";
        return true;
    }

initWindow()

bool mxvk::VK_Window::initWindow ( const std::string & title, int width, int height, SDL_WindowFlags flags )

protectedinherited

Initialize SDL window resources.

Parameters

title	Window title string.
width	Window width in pixels.
height	Window height in pixels.
flags	Additional SDL window creation flags.

Returns

true on success, false otherwise.

Definition at line 1348 of file mxvk.cpp.

                                                                                                   {
        std::cout << std::format("mxvk: entering initWindow (title='{}', width={}, height={})\n", title, width, height);
        if (width <= 0 || height <= 0) {
            std::cerr << "mxvk: Window dimensions must be positive\n";
            return false;
        }
 
        if (!sdl_initialized) {
            constexpr SDL_InitFlags sdlInitFlags = SDL_INIT_VIDEO | SDL_INIT_GAMEPAD;
            std::cout << "SDL3: initializing video/gamepad subsystems\n";
            if (!SDL_Init(sdlInitFlags)) {
                std::cerr << "mxvk: Error on SDL init: " << SDL_GetError() << "\n";
                return false;
            }
            sdl_initialized = true;
            SDL_SetGamepadEventsEnabled(true);
            SDL_SetJoystickEventsEnabled(true);
            std::cout << "SDL3: video/gamepad subsystems initialized\n";
        }
 
        if (!vulkan_library_loaded) {
            std::cout << "SDL3: loading the Vulkan loader library\n";
            if (!SDL_Vulkan_LoadLibrary(nullptr)) {
                std::cerr << std::format(
                    "mxvk: SDL_Vulkan_LoadLibrary failed: {}\n", SDL_GetError());
                SDL_QuitSubSystem(SDL_INIT_VIDEO | SDL_INIT_GAMEPAD);
                sdl_initialized = false;
                return false;
            }
            vulkan_library_loaded = true;
        }
 
        const bool fullscreen = (flags & SDL_WINDOW_FULLSCREEN) != 0;
        const SDL_DisplayMode *fullscreen_mode = nullptr;
        if (fullscreen) {
            const SDL_DisplayID display = SDL_GetPrimaryDisplay();
            fullscreen_mode = display != 0 ? SDL_GetCurrentDisplayMode(display) : nullptr;
            if (fullscreen_mode != nullptr && fullscreen_mode->w > 0 && fullscreen_mode->h > 0) {
                width = fullscreen_mode->w;
                height = fullscreen_mode->h;
                std::cout << std::format("SDL3: using current display mode for fullscreen window: {}x{}\n", width, height);
            }
        }
 
        std::cout << "SDL3: creating SDL window with Vulkan capability\n";
        SDL_Window *raw_window = SDL_CreateWindow(title.c_str(), width, height, flags);
        if (raw_window == nullptr) {
            std::cerr << std::format("Error creating window: {}\n", SDL_GetError());
            SDL_Vulkan_UnloadLibrary();
            vulkan_library_loaded = false;
            std::cout << "SDL3: rolling back SDL video/gamepad subsystems after window creation failure\n";
            SDL_QuitSubSystem(SDL_INIT_VIDEO | SDL_INIT_GAMEPAD);
            sdl_initialized = false;
            return false;
        }
 
        window.reset(raw_window);
        if (fullscreen && fullscreen_mode != nullptr && !SDL_SetWindowFullscreenMode(window.get(), fullscreen_mode)) {
            std::cerr << std::format("mxvk: SDL_SetWindowFullscreenMode failed: {}\n", SDL_GetError());
        }
        std::cout << "SDL3: showing created window\n";
        SDL_ShowWindow(window.get());
        if (fullscreen && !SDL_SyncWindow(window.get())) {
            std::cerr << std::format("mxvk: SDL_SyncWindow failed after fullscreen show: {}\n", SDL_GetError());
        }
        if (fullscreen) {
            for (int attempt = 0; attempt < 50; ++attempt) {
                int pixel_width = 0;
                int pixel_height = 0;
                SDL_GetWindowSizeInPixels(window.get(), &pixel_width, &pixel_height);
                if (pixel_width == width && pixel_height == height) {
                    break;
                }
                SDL_PumpEvents();
                SDL_Delay(10);
            }
        }
        std::cout << "mxvk: initWindow complete\n";
        return true;
    }

loadSpv()

std::vector< char > mxvk::VK_Window::loadSpv ( const std::string & path )

staticprotectedinherited

Load a SPIR-V file from disk.

Parameters

path	Absolute or relative path to a .spv file.

Returns

Raw bytes loaded from file.

Exceptions

mxvk::Exception

when the file cannot be opened, is empty, or is not 4-byte aligned.

Definition at line 141 of file mxvk.cpp.

                                                            {
        return mxvk::load_spv(path);
    }

loop()

void mxvk::VK_Window::loop ( )

inherited

Run the main event/render loop.

Definition at line 627 of file mxvk.cpp.

                         {
        SDL_Event e;
        active = true;
        while (active) {
            while (SDL_PollEvent(&e)) {
                switch (e.type) {
                case SDL_EVENT_QUIT:
                    active = false;
                    break;
                case SDL_EVENT_WINDOW_PIXEL_SIZE_CHANGED:
                    if (window != nullptr) {
                        framebuffer_resized = true;
                        last_resize_event_ms = SDL_GetTicks();
                        force_swapchain_recreate = false;
                    }
                    break;
                case SDL_EVENT_KEY_DOWN:
                    if ((e.key.key == SDLK_F12 || e.key.scancode == SDL_SCANCODE_F12) && !e.key.repeat) {
                        toggleFpsCounter();
                    }
                    if (screenshot_enabled &&
                        (e.key.key == SDLK_F10 || e.key.scancode == SDL_SCANCODE_F10) &&
                        !e.key.repeat) {
                        try {
                            saveScreenshot();
                        } catch (const mxvk::Exception &ex) {
                            std::cerr << std::format("mxvk: screenshot failed: {}\n", ex.text());
                        } catch (const std::exception &ex) {
                            std::cerr << std::format("mxvk: screenshot failed: {}\n", ex.what());
                        }
                        continue;
                    }
                    break;
                default:
                    break;
                }
                event(e);
            }
            if (framebuffer_resized) {
                const uint64_t now_ms = SDL_GetTicks();
                if (!force_swapchain_recreate &&
                    last_resize_event_ms != 0 &&
                    (now_ms - last_resize_event_ms) < resize_settle_delay_ms) {
                    proc();
                    render();
                    SDL_Delay(1);
                    continue;
                }
                recreateSwapchain();
            }
            proc();
            render();
            maybeTrimMemory();
        }
    }

onConfigureDepthStencilAttachments()

void mxvk::VK_Window::onConfigureDepthStencilAttachments ( VkRenderingAttachmentInfo & depth_attachment, VkRenderingAttachmentInfo & stencil_attachment, uint32_t image_index )

protectedvirtualinherited

Allow derived classes to customize depth/stencil attachments for the main dynamic rendering pass.

Override this when custom rendering needs hardware stencil testing or a custom depth/stencil image. The callback is invoked immediately before vkCmdBeginRendering.

Reimplemented in example::StencilWindow.

Definition at line 1447 of file mxvk.cpp.

                                                                                              {}

onFrameReadback()

void mxvk::VK_Window::onFrameReadback ( std::vector< std::uint8_t > & rgba_pixels, uint32_t width, uint32_t height )

protectedvirtualinherited

Receive one tightly packed RGBA8 copy of the rendered frame.

Parameters

rgba_pixels	Frame pixels in top-to-bottom row order.
width	Frame width in pixels.
height	Frame height in pixels.

Definition at line 1114 of file mxvk.cpp.

                                                                           {
    }

onFrameReadbackScheduled()

void mxvk::VK_Window::onFrameReadbackScheduled ( )

protectedvirtualinherited

Called after a presented frame has scheduled a readback.

Derived classes can use this hook to queue frame-specific metadata that must remain associated with the later onFrameReadback() callback.

Definition at line 1119 of file mxvk.cpp.

                                             {
    }

onPrepareFrameRendering()

void mxvk::VK_Window::onPrepareFrameRendering ( VkCommandBuffer cmd, uint32_t image_index )

virtualinherited

Record resource transitions that must happen before dynamic rendering begins.

This callback is invoked after the command buffer begins recording and before vkCmdBeginRendering. Override this for resources that need per-frame image transitions or uploads before they are sampled by custom rendering.

Parameters

cmd	Active command buffer in recording state, outside a rendering scope.
image_index	Current swapchain image index.

Reimplemented in defender::DefenderWindow, example::StencilWindow, and example::WaterWindow.

Definition at line 1437 of file mxvk.cpp.

{}

onRecordCustomRendering()

void mxvk::VK_Window::onRecordCustomRendering ( VkCommandBuffer cmd, uint32_t image_index )

protectedvirtualinherited

Optional hook for derived classes to record extra draw commands.

This callback is invoked inside the dynamic-rendering scope started by the window, after viewport/scissor are configured and before rendering ends.

Parameters

cmd	Active command buffer in recording state.
image_index	Current swapchain image index.

Reimplemented in anonymous_namespace{breakout.cpp}::BreakoutWindow, anonymous_namespace{pong.cpp}::PongWindow, anonymous_namespace{puzzle_drop.cpp}::PuzzleDropWindow, anonymous_namespace{tetris.cpp}::TetrisWindow, ComputeWindow, defender::DefenderWindow, demo::PoolWindow, example::BinaryMatrixWindow, example::DarkWindow, example::ExampleWindow, example::ExampleWindow, example::ExampleWindow, example::FireworksWindow, example::FractalWindow, example::GlitchCubeWindow, example::ModelWindow, example::ModelWindow, example::MoonWindow, example::OpenCVModelWindow, example::PlanetWindow, example::PointSpriteWindow, example::StarfieldWindow, example::StarshipWindow, example::StaticWindow, example::StencilWindow, example::WaterWindow, space::Asteroids3DWindow, space::Asteroids3DWindow, viewer::ModelViewerWindow, walk::WalkWindow, and walk::WalkWindow.

Definition at line 1439 of file mxvk.cpp.

{}

onRecordPostProcessingTexture()

void mxvk::VK_Window::onRecordPostProcessingTexture ( VkCommandBuffer cmd, uint32_t image_index, VkImageView texture_view, VkExtent2D texture_extent )

protectedvirtualinherited

Render a completed post-processing chain as custom scene input.

Called inside a fresh final-color rendering scope when texture-consumer mode is enabled. The supplied view is in shader-read-only layout.

Definition at line 1441 of file mxvk.cpp.

                                                    {}

onSwapchainAboutToRecreate()

void mxvk::VK_Window::onSwapchainAboutToRecreate ( )

protectedvirtualinherited

Called right before swapchain-dependent resources are recreated.

Derived classes can release swapchain-dependent resources here.

Reimplemented in anonymous_namespace{pong.cpp}::PongWindow, example::ExampleWindow, example::FractalWindow, example::PlanetWindow, example::StaticWindow, example::StencilWindow, and example::WaterWindow.

Definition at line 1433 of file mxvk.cpp.

{}

onSwapchainRecreated()

void mxvk::VK_Window::onSwapchainRecreated ( )

protectedvirtualinherited

Called after swapchain and render resources are recreated.

Derived classes can rebuild swapchain-dependent resources here.

Reimplemented in anonymous_namespace{breakout.cpp}::BreakoutWindow, anonymous_namespace{pong.cpp}::PongWindow, anonymous_namespace{puzzle_drop.cpp}::PuzzleDropWindow, anonymous_namespace{tetris.cpp}::TetrisWindow, ComputeWindow, defender::DefenderWindow, demo::PoolWindow, example::BinaryMatrixWindow, example::DarkWindow, example::ExampleWindow, example::ExampleWindow, example::ExampleWindow, example::FireworksWindow, example::FractalWindow, example::GlitchCubeWindow, example::MatrixWindow, example::ModelWindow, example::ModelWindow, example::MoonWindow, example::OpenCVModelWindow, example::PlanetWindow, example::PointSpriteWindow, example::StarfieldWindow, example::StarshipWindow, space::Asteroids3DWindow, space::Asteroids3DWindow, surface::SurfaceWindow, surface::SurfaceWindow, viewer::ModelViewerWindow, walk::WalkWindow, and walk::WalkWindow.

Definition at line 1435 of file mxvk.cpp.

{}

pickDevice()

void mxvk::VK_Window::pickDevice ( )

protectedinherited

Pick a suitable Vulkan physical device.

Definition at line 1868 of file mxvk.cpp.

                               {
        std::cout << "mxvk: entering pickDevice\n";
        if (instance == VK_NULL_HANDLE || surface == VK_NULL_HANDLE) {
            std::cout << "vk: cannot pick device because instance or surface is missing\n";
            return;
        }
 
        uint32_t device_count = 0;
        std::cout << "vk: enumerating physical devices\n";
        vkEnumeratePhysicalDevices(instance, &device_count, nullptr);
        if (device_count == 0U) {
            std::cout << "vk: no physical devices found\n";
            return;
        }
        std::cout << std::format("vk: found {} physical device(s)\n", device_count);
 
        std::vector<VkPhysicalDevice> devices(device_count);
        vkEnumeratePhysicalDevices(instance, &device_count, devices.data());
 
        for (const VkPhysicalDevice candidate : devices) {
            std::cout << "vk: evaluating candidate physical device\n";
            uint32_t queue_family_count = 0;
            vkGetPhysicalDeviceQueueFamilyProperties(candidate, &queue_family_count, nullptr);
            std::vector<VkQueueFamilyProperties> queue_families(queue_family_count);
            vkGetPhysicalDeviceQueueFamilyProperties(candidate, &queue_family_count, queue_families.data());
 
            uint32_t candidate_graphics = invalid_queue_index;
            uint32_t candidate_present = invalid_queue_index;
 
            for (uint32_t i = 0; i < queue_family_count; ++i) {
                if ((queue_families[i].queueFlags & VK_QUEUE_GRAPHICS_BIT) != 0U) {
                    candidate_graphics = i;
                }
 
                VkBool32 present_support = VK_FALSE;
                vkGetPhysicalDeviceSurfaceSupportKHR(candidate, i, surface, &present_support);
                if (present_support == VK_TRUE) {
                    candidate_present = i;
                }
            }
 
            if (candidate_graphics == invalid_queue_index || candidate_present == invalid_queue_index) {
                std::cout << "vk: candidate rejected due to missing graphics/present queue support\n";
                continue;
            }
 
            const SwapchainSupport swapchain_support = querySwapchainSupport(candidate, surface);
            if (swapchain_support.formats.empty() || swapchain_support.present_modes.empty()) {
                std::cout << "vk: candidate rejected due to incomplete swapchain support\n";
                continue;
            }
 
            VkPhysicalDeviceProperties properties{};
            vkGetPhysicalDeviceProperties(candidate, &properties);
 
            const char *device_type = "unknown";
            switch (properties.deviceType) {
            case VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU:
                device_type = "integrated";
                break;
            case VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU:
                device_type = "discrete";
                break;
            case VK_PHYSICAL_DEVICE_TYPE_VIRTUAL_GPU:
                device_type = "virtual";
                break;
            case VK_PHYSICAL_DEVICE_TYPE_CPU:
                device_type = "cpu";
                break;
            default:
                break;
            }
 
            physical_device = candidate;
            graphics_queue_family = candidate_graphics;
            present_queue_family = candidate_present;
            std::cout << std::format(
                "vk: selected GPU='{}' type={} vendor=0x{:04x} device=0x{:04x}\n",
                properties.deviceName,
                device_type,
                properties.vendorID,
                properties.deviceID);
            return;
        }
 
        std::cout << "vk: no suitable physical device selected\n";
    }

printPreviewText() [1/2]

void mxvk::VK_Window::printPreviewText ( const std::string & text, int x, int y, const SDL_Color & col )

inherited

Queue preview-only text after frame readback.

Unlike printText(), this text is visible in the presentation window but excluded from screenshots and frame-readback consumers.

Definition at line 4106 of file mxvk.cpp.

                                                           {
        if (text.empty()) {
            return;
        }
        if (!font_configured) {
            throw mxvk::Exception(
                "printPreviewText requires setFont() to be called first");
        }
        ensurePreviewTextRenderer();
        if (!preview_text_renderer) {
            throw mxvk::Exception(
                "printPreviewText could not initialize the text renderer");
        }
        preview_text_renderer->printTextG_Solid(text, x, y, col);
        preview_text_queued = true;
    }

printPreviewText() [2/2]

void mxvk::VK_Window::printPreviewText ( const std::string & text, int x, int y, const SDL_Color & col, const Font & font )

inherited

Definition at line 4124 of file mxvk.cpp.

                                                                             {
        if (text.empty()) {
            return;
        }
        if (!font) {
            throw mxvk::Exception(
                "printPreviewText requires a valid mxvk::Font");
        }
        ensurePreviewTextRenderer(font.path(), font.size());
        if (!preview_text_renderer) {
            throw mxvk::Exception(
                "printPreviewText could not initialize the text renderer");
        }
        preview_text_renderer->printTextG_Solid(text, x, y, col, font);
        preview_text_queued = true;
    }

printText() [1/3]

void mxvk::VK_Window::printText ( const std::string & text, int x, int y, const SDL_Color & col )

inherited

Queue a text string for rendering during the current frame.

Parameters

text	UTF-8 text.
x	Pixel X coordinate.
y	Pixel Y coordinate.
col	Text color.

Definition at line 4051 of file mxvk.cpp.

                                                                                       {
        if (text.empty()) {
            return;
        }
 
        if (!font_configured) {
            throw mxvk::Exception("printText requires setFont() to be called first");
        }
 
        ensureTextRenderer();
        text_renderer->printTextG_Solid(text, x, y, col);
    }

printText() [2/3]

void mxvk::VK_Window::printText ( const std::string & text, int x, int y, const SDL_Color & col, const Font & font )

inherited

Definition at line 4080 of file mxvk.cpp.

                                                                                                         {
        if (text.empty()) {
            return;
        }
 
        if (!font) {
            throw mxvk::Exception("printText requires a valid mxvk::Font");
        }
 
        ensureTextRenderer(font.path(), font.size());
        if (!text_renderer) {
            throw mxvk::Exception("printText with an explicit font could not initialize the text renderer");
        }
        text_renderer->printTextG_Solid(text, x, y, col, font);
    }

printText() [3/3]

void mxvk::VK_Window::printText ( const std::string & text, int x, int y, const SDL_Color & col, TTF_Font * font )

inherited

Definition at line 4064 of file mxvk.cpp.

                                                                                                       {
        if (text.empty()) {
            return;
        }
 
        if (font == nullptr) {
            throw mxvk::Exception("printText requires a non-null TTF_Font");
        }
 
        ensureTextRenderer(resolveDefaultFontPath(), font_size);
        if (!text_renderer) {
            throw mxvk::Exception("printText with an explicit font could not initialize the text renderer");
        }
        text_renderer->printTextG_Solid(text, x, y, col, font);
    }

proc() [1/2]

void example::MasterPieceWindow::proc ( )

inlineoverridevirtual

Execute one processing/update step.

Reimplemented from mxvk::VK_Window.

Definition at line 382 of file main.cpp.

                             {
            const Uint64 now = SDL_GetTicks();
            layout = computeLayout();
            updateGridViewInput(now);
            pollController(now);
 
            switch (screen) {
            case Screen::Intro:
                if (!drawIntro(now)) {
                    break;
                }
                drawMenu();
                break;
            case Screen::Menu:
                drawMenu();
                break;
            case Screen::Game:
                updateGame(now);
                if (screen == Screen::Game) {
                    drawGame(now);
                } else if (screen == Screen::Scores) {
                    drawScores(false);
                } else if (screen == Screen::Credits) {
                    drawCredits();
                } else if (screen == Screen::NameEntry) {
                    drawScores(true);
                } else if (screen == Screen::Menu) {
                    drawMenu();
                }
                break;
            case Screen::Scores:
                drawScores(false);
                break;
            case Screen::Credits:
                drawCredits();
                break;
            case Screen::NameEntry:
                drawScores(true);
                break;
            }
        }

proc() [2/2]

void example::MasterPieceWindow::proc ( )

inlineoverridevirtual

Execute one processing/update step.

Reimplemented from mxvk::VK_Window.

Definition at line 326 of file main.cpp.

                             {
            const Uint64 now = SDL_GetTicks();
            layout = computeLayout();
            pollController(now);
 
            switch (screen) {
            case Screen::Intro:
                if (!drawIntro(now)) {
                    break;
                }
                drawMenu();
                break;
            case Screen::Menu:
                drawMenu();
                break;
            case Screen::Game:
                updateGame(now);
                if (screen == Screen::Game) {
                    drawGame(now);
                } else if (screen == Screen::Scores) {
                    drawScores(false);
                } else if (screen == Screen::Credits) {
                    drawCredits();
                } else if (screen == Screen::NameEntry) {
                    drawScores(true);
                } else if (screen == Screen::Menu) {
                    drawMenu();
                }
                break;
            case Screen::Scores:
                drawScores(false);
                break;
            case Screen::Credits:
                drawCredits();
                break;
            case Screen::NameEntry:
                drawScores(true);
                break;
            }
        }

release()

void mxvk::VK_Window::release ( )

inherited

Release Vulkan and SDL resources.

Safe to call multiple times.

Definition at line 218 of file mxvk.cpp.

                            {
        std::cout << "mxvk: starting resource teardown\n";
        stopScreenshotWorker();
 
        if (device != VK_NULL_HANDLE) {
            std::cout << "vk: waiting for device idle before teardown\n";
            vkDeviceWaitIdle(device);
        }
 
        destroyFrameReadbackResources();
 
        post_process_sprite = nullptr;
        owned_post_process_sprite = nullptr;
        post_process_present_sprite = nullptr;
        post_process_composite_sprite = nullptr;
        post_process_sprites.clear();
        owned_post_process_sprites.clear();
        post_process_effect_stages.clear();
        post_process_effect_params.clear();
        post_process_effect_time_enabled.clear();
        post_process_effect_start_times.clear();
 
        if (!sprites.empty()) {
            std::cout << std::format("vk: releasing {} sprite(s)\n", sprites.size());
            sprites.clear();
            std::cout << "vk: sprite resources released\n";
        }
        if (!sprites3d.empty()) {
            std::cout << std::format("vk: releasing {} 3D sprite batch(es)\n", sprites3d.size());
            sprites3d.clear();
        }
        sprite_state_dirty = false;
        destroySpritePipeline();
        if (sprite_descriptor_set_layout != VK_NULL_HANDLE && device != VK_NULL_HANDLE) {
            vkDestroyDescriptorSetLayout(device, sprite_descriptor_set_layout, nullptr);
            sprite_descriptor_set_layout = VK_NULL_HANDLE;
        }
 
        if (text_renderer) {
            text_renderer.reset();
        }
        if (preview_text_renderer) {
            preview_text_renderer.reset();
        }
        preview_text_queued = false;
        text_state_dirty = false;
        destroyTextPipeline();
        if (text_descriptor_set_layout != VK_NULL_HANDLE && device != VK_NULL_HANDLE) {
            vkDestroyDescriptorSetLayout(device, text_descriptor_set_layout, nullptr);
            text_descriptor_set_layout = VK_NULL_HANDLE;
        }
 
        cleanupSyncObjects();
 
        if (!retired_swapchains.empty()) {
            for (VkSwapchainKHR retired : retired_swapchains) {
                vkDestroySwapchainKHR(device, retired, nullptr);
            }
            retired_swapchains.clear();
        }
        std::cout << "vk: tearing down swapchain-dependent resources\n";
        cleanupSwapchain(true);
 
        if (command_pool != VK_NULL_HANDLE && device != VK_NULL_HANDLE) {
            std::cout << "vk: destroying command pool\n";
            vkDestroyCommandPool(device, command_pool, nullptr);
            command_pool = VK_NULL_HANDLE;
        }
 
        if (device != VK_NULL_HANDLE) {
            savePipelineCache();
            destroyPipelineCache();
            std::cout << "vk: destroying logical device\n";
            vkDestroyDevice(device, nullptr);
            device = VK_NULL_HANDLE;
            graphics_queue = VK_NULL_HANDLE;
            present_queue = VK_NULL_HANDLE;
        }
 
        graphics_queue_family = invalid_queue_index;
        present_queue_family = invalid_queue_index;
        physical_device = VK_NULL_HANDLE;
 
        if (surface != VK_NULL_HANDLE && instance != VK_NULL_HANDLE) {
            std::cout << "vk: destroying presentation surface\n";
            vkDestroySurfaceKHR(instance, surface, nullptr);
            surface = VK_NULL_HANDLE;
        }
 
        cleanupDebugMessenger();
 
        if (instance != VK_NULL_HANDLE) {
            std::cout << "vk: destroying Vulkan instance\n";
            vkDestroyInstance(instance, nullptr);
            instance = VK_NULL_HANDLE;
        }
 
        std::cout << "SDL3: destroying SDL window handle\n";
        window.reset();
 
        if (vulkan_library_loaded) {
            std::cout << "SDL3: unloading Vulkan loader library\n";
            SDL_Vulkan_UnloadLibrary();
            vulkan_library_loaded = false;
        }
 
        if (sdl_initialized) {
            std::cout << "SDL3: shutting down SDL video/gamepad subsystems\n";
            SDL_QuitSubSystem(SDL_INIT_VIDEO | SDL_INIT_GAMEPAD);
            sdl_initialized = false;
        }
 
        active = false;
        std::cout << "mxvk: resource teardown complete\n";
    }

render()

void mxvk::VK_Window::render ( )

virtualinherited

Render one frame.

Reimplemented in example::FractalWindow, and viewer::ModelViewerWindow.

Definition at line 805 of file mxvk.cpp.

                           {
        drawFrame();
    }

renderStandaloneSprite() [1/2]

void mxvk::VK_Window::renderStandaloneSprite ( VK_Sprite & sprite, VkCommandBuffer cmd )

protectedinherited

Render one standalone sprite using the window's shared sprite pipeline.

This is intended for derived classes that want to draw a sprite before or after their own scene content without registering it in the window-managed sprite list.

Definition at line 1451 of file mxvk.cpp.

                                                                                 {
        renderStandaloneSprite(sprite, cmd, swapchain_extent);
    }

renderStandaloneSprite() [2/2]

void mxvk::VK_Window::renderStandaloneSprite ( VK_Sprite & sprite, VkCommandBuffer cmd, VkExtent2D extent )

protectedinherited

Definition at line 1455 of file mxvk.cpp.

                                                              {
        if (device == VK_NULL_HANDLE || extent.width == 0U || extent.height == 0U) {
            return;
        }
 
        if (sprite_pipeline == VK_NULL_HANDLE) {
            return;
        }
        vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, sprite_pipeline);
        sprite.renderSprites(cmd, sprite_pipeline_layout, extent.width, extent.height);
    }

saveSnapshot()

void mxvk::VK_Window::saveSnapshot ( const std::string & path )

inherited

Save the most recently rendered window contents as a PNG file.

Parameters

path	Destination PNG path.

This performs a synchronous GPU readback and may briefly stall rendering.

Definition at line 809 of file mxvk.cpp.

                                                      {
        if (path.empty()) {
            throw mxvk::Exception("saveSnapshot requires a non-empty output path");
        }
 
        std::vector<std::uint8_t> rgba{};
        uint32_t width = 0;
        uint32_t height = 0;
        captureSnapshotPixels(rgba, width, height);
 
        if (!mxvk::SavePNG_RGBA(path.c_str(),
                                rgba.data(),
                                static_cast<int>(width),
                                static_cast<int>(height))) {
            throw mxvk::Exception("saveSnapshot failed to write PNG: " + path);
        }
    }

screenshotEnabled()

bool mxvk::VK_Window::screenshotEnabled ( ) const

inlinenodiscardnoexceptinherited

Check whether F10 screenshot capture is enabled.

Definition at line 176 of file mxvk.hpp.

{ return screenshot_enabled; }

setClearColor()

void mxvk::VK_Window::setClearColor ( float r, float g, float b, float a = 1.0f )

inherited

Set the per-frame color attachment clear color.

Parameters

r	Red channel [0, 1].
g	Green channel [0, 1].
b	Blue channel [0, 1].
a	Alpha channel [0, 1].

Definition at line 613 of file mxvk.cpp.

                                                                    {
        clear_color.float32[0] = std::clamp(r, 0.0f, 1.0f);
        clear_color.float32[1] = std::clamp(g, 0.0f, 1.0f);
        clear_color.float32[2] = std::clamp(b, 0.0f, 1.0f);
        clear_color.float32[3] = std::clamp(a, 0.0f, 1.0f);
    }

setEnableScreenshot()

void mxvk::VK_Window::setEnableScreenshot ( bool enabled )

noexceptinherited

Enable or disable F10 screenshot capture.

Definition at line 620 of file mxvk.cpp.

                                                             {
        screenshot_enabled = enabled;
        if (enabled) {
            frame_readback_enabled = true;
        }
    }

setFont()

void mxvk::VK_Window::setFont ( const std::string & fontPath, int fontSize = 24 )

inherited

Set the active text-render font.

Parameters

fontPath	Path to a TTF font file.
fontSize	Font point size.

Definition at line 4002 of file mxvk.cpp.

                                                                   {
        if (fontPath.empty() || fontSize <= 0) {
            throw mxvk::Exception("setFont requires a non-empty path and positive font size");
        }
 
        font_path = fontPath;
        font_size = fontSize;
        font_configured = true;
 
        if (device == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot set font before Vulkan device initialization");
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            createDevice();
        }
        if (swapchain == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE) {
            throw mxvk::Exception("Cannot initialize text renderer before swapchain and command resources are available");
        }
 
        if (!text_renderer) {
            ensureTextRenderer();
        } else {
            text_renderer->setFont(font_path, font_size);
        }
        if (preview_text_renderer) {
            preview_text_renderer->setFont(font_path, font_size);
        }
        text_state_dirty = true;
    }

setFrameReadbackEnabled()

void mxvk::VK_Window::setFrameReadbackEnabled ( bool enabled )

inlinenoexceptinherited

Enable or disable readback of each rendered swapchain frame.

Readback is recorded while the swapchain image is acquired and delivered through onFrameReadback() after the corresponding frame-in-flight fence completes. Readbacks are pipelined so recording does not add a same-frame GPU wait.

Definition at line 186 of file mxvk.hpp.

{ frame_readback_enabled = enabled; }

setPostProcessingEnabled()

void mxvk::VK_Window::setPostProcessingEnabled ( bool enabled )

inlineinherited

Definition at line 339 of file mxvk.hpp.

{ post_process_enabled = enabled; }

setPostProcessingShaderParams() [1/2]

void mxvk::VK_Window::setPostProcessingShaderParams ( float p1 = 0.0f, float p2 = 0.0f, float p3 = 0.0f, float p4 = 0.0f )

inherited

Set the post-processing shader params passed as a vec4 push constant.

Definition at line 1624 of file mxvk.cpp.

                                                                                        {
        post_process_params = {p1, p2, p3, p4};
        if (post_process_sprites.empty()) {
            return;
        }
        setPostProcessingShaderParams(0, p1, p2, p3, p4);
    }

setPostProcessingShaderParams() [2/2]

void mxvk::VK_Window::setPostProcessingShaderParams ( size_t effectIndex, float p1 = 0.0f, float p2 = 0.0f, float p3 = 0.0f, float p4 = 0.0f )

inherited

Definition at line 1632 of file mxvk.cpp.

                                                                                                            {
        if (effectIndex >= post_process_sprites.size()) {
            return;
        }
        post_process_params = {p1, p2, p3, p4};
        if (effectIndex < post_process_effect_params.size()) {
            post_process_effect_params[effectIndex] = post_process_params;
        }
        if (post_process_sprites[effectIndex] != nullptr) {
            post_process_sprites[effectIndex]->setShaderParams(p1, p2, p3, p4);
        }
    }

setPostProcessingShaderTimeEnabled() [1/2]

void mxvk::VK_Window::setPostProcessingShaderTimeEnabled ( bool enabled )

inherited

Keep shader param 1 updated with elapsed render time in seconds.

Definition at line 1645 of file mxvk.cpp.

                                                                   {
        post_process_time_enabled = enabled;
        post_process_start_time = std::chrono::steady_clock::now();
        if (post_process_sprites.empty()) {
            return;
        }
        setPostProcessingShaderTimeEnabled(0, enabled);
    }

setPostProcessingShaderTimeEnabled() [2/2]

void mxvk::VK_Window::setPostProcessingShaderTimeEnabled ( size_t effectIndex, bool enabled )

inherited

Definition at line 1654 of file mxvk.cpp.

                                                                                       {
        if (effectIndex >= post_process_sprites.size()) {
            return;
        }
        post_process_time_enabled = enabled;
        post_process_start_time = std::chrono::steady_clock::now();
        if (effectIndex < post_process_effect_time_enabled.size()) {
            post_process_effect_time_enabled[effectIndex] = enabled;
        }
        if (effectIndex < post_process_effect_start_times.size()) {
            post_process_effect_start_times[effectIndex] = post_process_start_time;
        }
    }

setPostProcessingTextureConsumerEnabled()

void mxvk::VK_Window::setPostProcessingTextureConsumerEnabled ( bool enabled )

inlinenoexceptinherited

Route the completed effect chain to a derived renderer as a sampled texture.

Definition at line 342 of file mxvk.hpp.

                                                                            {
            post_process_texture_consumer_enabled = enabled;
        }

setPreviewFont()

void mxvk::VK_Window::setPreviewFont ( const std::string & fontPath, int fontSize = 24 )

inherited

Set the preview-only HUD font independently of output text.

Definition at line 4032 of file mxvk.cpp.

                                                                          {
        if (fontPath.empty() || fontSize <= 0) {
            throw mxvk::Exception(
                "setPreviewFont requires a non-empty path and positive font size");
        }
        if (device == VK_NULL_HANDLE) {
            throw mxvk::Exception(
                "Cannot set preview font before Vulkan device initialization");
        }
        if (!preview_text_renderer) {
            ensurePreviewTextRenderer(fontPath, fontSize);
        }
        if (!preview_text_renderer) {
            throw mxvk::Exception("Cannot initialize preview text renderer");
        }
        preview_text_renderer->setFont(fontPath, fontSize);
        text_state_dirty = true;
    }

setRenderExtent()

void mxvk::VK_Window::setRenderExtent ( uint32_t width, uint32_t height )

inherited

Render post-processing at a fixed extent independent of the preview window.

The final source-sized image is read back before a fitted copy is presented to the swapchain. Pass zero dimensions to return to swapchain-sized rendering.

Definition at line 1468 of file mxvk.cpp.

                                                                   {
        if ((width == 0U) != (height == 0U)) {
            throw mxvk::Exception("render extent requires two positive dimensions or two zeros");
        }
        if (render_extent_override.width == width &&
            render_extent_override.height == height) {
            return;
        }
        if (device != VK_NULL_HANDLE && swapchain != VK_NULL_HANDLE) {
            vkDeviceWaitIdle(device);
            destroyFrameReadbackResources();
            destroyPostProcessTargets();
        }
        render_extent_override = {width, height};
        sprite_state_dirty = true;
        if (device != VK_NULL_HANDLE && !swapchain_images.empty() &&
            !post_process_sprites.empty()) {
            createPostProcessTargets();
        }
        std::cout << std::format("mxvk: fixed render extent {}\n",
                                 width > 0U ? std::format("{}x{}", width, height)
                                            : "disabled");
    }

showCursor()

void mxvk::VK_Window::showCursor ( bool on )

inherited

Definition at line 4790 of file mxvk.cpp.

                                      {
        if (on)
            SDL_ShowCursor();
        else
            SDL_HideCursor();
    }

trimMemory()

void mxvk::VK_Window::trimMemory ( )

inherited

Return transient Vulkan command-pool allocations to the driver when supported.

MXVK currently uses direct Vulkan memory allocations rather than VMA, so VMA defragmentation is not applicable. This hook schedules the available Vulkan memory maintenance operation and is safe to call during idle/loading points.

Definition at line 1330 of file mxvk.cpp.

                               {
        if (device == VK_NULL_HANDLE || command_pool == VK_NULL_HANDLE || vkTrimCommandPool == nullptr) {
            return;
        }
 
        vkTrimCommandPool(device, command_pool, 0);
    }

validationEnabled()

bool mxvk::VK_Window::validationEnabled ( ) const

nodiscardinherited

Check whether Vulkan validation layers are currently enabled.

Returns

true if validation layers are enabled, false otherwise.

Definition at line 3922 of file mxvk.cpp.

                                            {
        return validation_enabled;
    }

Member Data Documentation

active

bool mxvk::VK_Window::active = false

protectedinherited

Definition at line 629 of file mxvk.hpp.

clear_color

VkClearColorValue mxvk::VK_Window::clear_color {{0.0f, 0.0f, 0.0f, 1.0f}}

protectedinherited

Definition at line 705 of file mxvk.hpp.

command_buffers

std::vector<VkCommandBuffer> mxvk::VK_Window::command_buffers {}

protectedinherited

Definition at line 617 of file mxvk.hpp.

command_pool

VkCommandPool mxvk::VK_Window::command_pool = VK_NULL_HANDLE

protectedinherited

Definition at line 616 of file mxvk.hpp.

current_frame

uint32_t mxvk::VK_Window::current_frame = 0

protectedinherited

Definition at line 623 of file mxvk.hpp.

debug_messenger

VkDebugUtilsMessengerEXT mxvk::VK_Window::debug_messenger = VK_NULL_HANDLE

protectedinherited

Definition at line 593 of file mxvk.hpp.

depth_format

VkFormat mxvk::VK_Window::depth_format = VK_FORMAT_UNDEFINED

protectedinherited

Definition at line 605 of file mxvk.hpp.

depth_image_initialized

std::vector<bool> mxvk::VK_Window::depth_image_initialized {}

protectedinherited

Definition at line 614 of file mxvk.hpp.

depth_image_memories

std::vector<VkDeviceMemory> mxvk::VK_Window::depth_image_memories {}

protectedinherited

Definition at line 612 of file mxvk.hpp.

depth_image_views

std::vector<VkImageView> mxvk::VK_Window::depth_image_views {}

protectedinherited

Definition at line 613 of file mxvk.hpp.

depth_images

std::vector<VkImage> mxvk::VK_Window::depth_images {}

protectedinherited

Definition at line 611 of file mxvk.hpp.

device

VkDevice mxvk::VK_Window::device = VK_NULL_HANDLE

protectedinherited

Definition at line 596 of file mxvk.hpp.

font_configured

bool mxvk::VK_Window::font_configured = false

protectedinherited

Definition at line 696 of file mxvk.hpp.

font_path

std::string mxvk::VK_Window::font_path {}

protectedinherited

Definition at line 697 of file mxvk.hpp.

font_size

int mxvk::VK_Window::font_size = 24

protectedinherited

Definition at line 698 of file mxvk.hpp.

force_swapchain_recreate

bool mxvk::VK_Window::force_swapchain_recreate = false

protectedinherited

Definition at line 655 of file mxvk.hpp.

fps_counter_enabled

bool mxvk::VK_Window::fps_counter_enabled = false

protectedinherited

Definition at line 699 of file mxvk.hpp.

fps_counter_font

Font mxvk::VK_Window::fps_counter_font {}

protectedinherited

Definition at line 701 of file mxvk.hpp.

fps_counter_font_ready

bool mxvk::VK_Window::fps_counter_font_ready = false

protectedinherited

Definition at line 700 of file mxvk.hpp.

fps_counter_frame_count

uint32_t mxvk::VK_Window::fps_counter_frame_count = 0

protectedinherited

Definition at line 703 of file mxvk.hpp.

fps_counter_sample_time

std::chrono::steady_clock::time_point mxvk::VK_Window::fps_counter_sample_time {}

protectedinherited

Definition at line 702 of file mxvk.hpp.

fps_counter_text

std::string mxvk::VK_Window::fps_counter_text = "FPS: --"

protectedinherited

Definition at line 704 of file mxvk.hpp.

frame_readback_enabled

bool mxvk::VK_Window::frame_readback_enabled = false

protectedinherited

Definition at line 644 of file mxvk.hpp.

frame_readback_slots

std::array<FrameReadbackSlot, max_frames_in_flight> mxvk::VK_Window::frame_readback_slots {}

protectedinherited

Definition at line 645 of file mxvk.hpp.

framebuffer_resized

bool mxvk::VK_Window::framebuffer_resized = false

protectedinherited

Definition at line 654 of file mxvk.hpp.

graphics_queue

VkQueue mxvk::VK_Window::graphics_queue = VK_NULL_HANDLE

protectedinherited

Definition at line 599 of file mxvk.hpp.

graphics_queue_family

uint32_t mxvk::VK_Window::graphics_queue_family = invalid_queue_index

protectedinherited

Definition at line 597 of file mxvk.hpp.

image_available

std::array<VkSemaphore, max_frames_in_flight> mxvk::VK_Window::image_available {}

protectedinherited

Definition at line 619 of file mxvk.hpp.

image_fences

std::vector<VkFence> mxvk::VK_Window::image_fences {}

protectedinherited

Definition at line 622 of file mxvk.hpp.

in_flight_fences

std::array<VkFence, max_frames_in_flight> mxvk::VK_Window::in_flight_fences {}

protectedinherited

Definition at line 621 of file mxvk.hpp.

instance

VkInstance mxvk::VK_Window::instance = VK_NULL_HANDLE

protectedinherited

Definition at line 592 of file mxvk.hpp.

last_memory_trim_time

std::chrono::steady_clock::time_point mxvk::VK_Window::last_memory_trim_time = std::chrono::steady_clock::now()

protectedinherited

Definition at line 658 of file mxvk.hpp.

last_presented_image_index

uint32_t mxvk::VK_Window::last_presented_image_index = invalid_queue_index

protectedinherited

Definition at line 624 of file mxvk.hpp.

last_resize_event_ms

uint64_t mxvk::VK_Window::last_resize_event_ms = 0

protectedinherited

Definition at line 656 of file mxvk.hpp.

latest_frame_readback_height

uint32_t mxvk::VK_Window::latest_frame_readback_height = 0

protectedinherited

Definition at line 648 of file mxvk.hpp.

latest_frame_readback_rgba

std::vector<std::uint8_t> mxvk::VK_Window::latest_frame_readback_rgba {}

protectedinherited

Definition at line 646 of file mxvk.hpp.

latest_frame_readback_width

uint32_t mxvk::VK_Window::latest_frame_readback_width = 0

protectedinherited

Definition at line 647 of file mxvk.hpp.

MEMORY_TRIM_INTERVAL

std::chrono::seconds mxvk::VK_Window::MEMORY_TRIM_INTERVAL {30}

staticconstexprprotectedinherited

Definition at line 659 of file mxvk.hpp.

owned_post_process_sprite

VK_Sprite* mxvk::VK_Window::owned_post_process_sprite = nullptr

protectedinherited

Definition at line 668 of file mxvk.hpp.

owned_post_process_sprites

std::vector<VK_Sprite *> mxvk::VK_Window::owned_post_process_sprites {}

protectedinherited

Definition at line 675 of file mxvk.hpp.

physical_device

VkPhysicalDevice mxvk::VK_Window::physical_device = VK_NULL_HANDLE

protectedinherited

Definition at line 595 of file mxvk.hpp.

pipeline_cache

VkPipelineCache mxvk::VK_Window::pipeline_cache = VK_NULL_HANDLE

protectedinherited

Definition at line 601 of file mxvk.hpp.

post_process_composite_sprite

VK_Sprite* mxvk::VK_Window::post_process_composite_sprite = nullptr

protectedinherited

Definition at line 677 of file mxvk.hpp.

post_process_compute_format

VkFormat mxvk::VK_Window::post_process_compute_format

staticconstexprprotectedinherited

Initial value:

                                                  =
VK_FORMAT_R8G8B8A8_UNORM

Definition at line 686 of file mxvk.hpp.

post_process_effect_params

std::vector<std::array<float, 4> > mxvk::VK_Window::post_process_effect_params {}

protectedinherited

Definition at line 679 of file mxvk.hpp.

post_process_effect_stages

std::vector<ShaderStage> mxvk::VK_Window::post_process_effect_stages {}

protectedinherited

Definition at line 678 of file mxvk.hpp.

post_process_effect_start_times

std::vector<std::chrono::steady_clock::time_point> mxvk::VK_Window::post_process_effect_start_times {}

protectedinherited

Definition at line 681 of file mxvk.hpp.

post_process_effect_time_enabled

std::vector<bool> mxvk::VK_Window::post_process_effect_time_enabled {}

protectedinherited

Definition at line 680 of file mxvk.hpp.

post_process_enabled

bool mxvk::VK_Window::post_process_enabled = true

protectedinherited

Definition at line 669 of file mxvk.hpp.

post_process_images

std::vector<std::vector<VkImage> > mxvk::VK_Window::post_process_images {}

protectedinherited

Definition at line 682 of file mxvk.hpp.

post_process_initialized

std::vector<std::vector<bool> > mxvk::VK_Window::post_process_initialized {}

protectedinherited

Definition at line 685 of file mxvk.hpp.

post_process_memories

std::vector<std::vector<VkDeviceMemory> > mxvk::VK_Window::post_process_memories {}

protectedinherited

Definition at line 683 of file mxvk.hpp.

post_process_params

std::array<float, 4> mxvk::VK_Window::post_process_params {}

protectedinherited

Definition at line 672 of file mxvk.hpp.

post_process_present_sprite

VK_Sprite* mxvk::VK_Window::post_process_present_sprite = nullptr

protectedinherited

Definition at line 676 of file mxvk.hpp.

post_process_sprite

VK_Sprite* mxvk::VK_Window::post_process_sprite = nullptr

protectedinherited

Definition at line 667 of file mxvk.hpp.

post_process_sprites

std::vector<VK_Sprite *> mxvk::VK_Window::post_process_sprites {}

protectedinherited

Definition at line 674 of file mxvk.hpp.

post_process_start_time

std::chrono::steady_clock::time_point mxvk::VK_Window::post_process_start_time = std::chrono::steady_clock::now()

protectedinherited

Definition at line 673 of file mxvk.hpp.

post_process_texture_consumer_enabled

bool mxvk::VK_Window::post_process_texture_consumer_enabled = false

protectedinherited

Definition at line 670 of file mxvk.hpp.

post_process_time_enabled

bool mxvk::VK_Window::post_process_time_enabled = false

protectedinherited

Definition at line 671 of file mxvk.hpp.

post_process_views

std::vector<std::vector<VkImageView> > mxvk::VK_Window::post_process_views {}

protectedinherited

Definition at line 684 of file mxvk.hpp.

present_mode_preference

PresentModePreference mxvk::VK_Window::present_mode_preference = PresentModePreference::LowLatency

protectedinherited

Definition at line 653 of file mxvk.hpp.

present_queue

VkQueue mxvk::VK_Window::present_queue = VK_NULL_HANDLE

protectedinherited

Definition at line 600 of file mxvk.hpp.

present_queue_family

uint32_t mxvk::VK_Window::present_queue_family = invalid_queue_index

protectedinherited

Definition at line 598 of file mxvk.hpp.

preview_text_queued

bool mxvk::VK_Window::preview_text_queued = false

protectedinherited

Definition at line 695 of file mxvk.hpp.

preview_text_renderer

std::unique_ptr<VK_Text> mxvk::VK_Window::preview_text_renderer {}

protectedinherited

Definition at line 690 of file mxvk.hpp.

render_extent_override

VkExtent2D mxvk::VK_Window::render_extent_override {}

protectedinherited

Definition at line 607 of file mxvk.hpp.

render_finished

std::vector<VkSemaphore> mxvk::VK_Window::render_finished {}

protectedinherited

Definition at line 620 of file mxvk.hpp.

resize_settle_delay_ms

uint64_t mxvk::VK_Window::resize_settle_delay_ms = 150

staticconstexprprotectedinherited

Definition at line 657 of file mxvk.hpp.

retired_swapchains

std::vector<VkSwapchainKHR> mxvk::VK_Window::retired_swapchains

protectedinherited

Definition at line 706 of file mxvk.hpp.

screenshot_enabled

bool mxvk::VK_Window::screenshot_enabled = defaultEnableScreenshot()

protectedinherited

Definition at line 630 of file mxvk.hpp.

screenshot_index

uint32_t mxvk::VK_Window::screenshot_index = 0

protectedinherited

Definition at line 632 of file mxvk.hpp.

screenshot_prefix

std::string mxvk::VK_Window::screenshot_prefix = defaultExecutableName()

protectedinherited

Definition at line 631 of file mxvk.hpp.

screenshot_queue_cv

std::condition_variable mxvk::VK_Window::screenshot_queue_cv

protectedinherited

Definition at line 640 of file mxvk.hpp.

screenshot_queue_mutex

std::mutex mxvk::VK_Window::screenshot_queue_mutex

protectedinherited

Definition at line 639 of file mxvk.hpp.

screenshot_save_queue

std::deque<ScreenshotSaveTask> mxvk::VK_Window::screenshot_save_queue

protectedinherited

Definition at line 641 of file mxvk.hpp.

screenshot_worker

std::thread mxvk::VK_Window::screenshot_worker

protectedinherited

Definition at line 642 of file mxvk.hpp.

screenshot_worker_stop

bool mxvk::VK_Window::screenshot_worker_stop = false

protectedinherited

Definition at line 643 of file mxvk.hpp.

sdl_initialized

bool mxvk::VK_Window::sdl_initialized = false

protectedinherited

Definition at line 627 of file mxvk.hpp.

sprite_descriptor_set_layout

VkDescriptorSetLayout mxvk::VK_Window::sprite_descriptor_set_layout = VK_NULL_HANDLE

protectedinherited

Definition at line 663 of file mxvk.hpp.

sprite_pipeline

VkPipeline mxvk::VK_Window::sprite_pipeline = VK_NULL_HANDLE

protectedinherited

Definition at line 665 of file mxvk.hpp.

sprite_pipeline_layout

VkPipelineLayout mxvk::VK_Window::sprite_pipeline_layout = VK_NULL_HANDLE

protectedinherited

Definition at line 664 of file mxvk.hpp.

sprite_state_dirty

bool mxvk::VK_Window::sprite_state_dirty = false

protectedinherited

Definition at line 666 of file mxvk.hpp.

sprites

std::vector<std::unique_ptr<VK_Sprite> > mxvk::VK_Window::sprites {}

protectedinherited

Definition at line 661 of file mxvk.hpp.

sprites3d

std::vector<std::unique_ptr<VK_Sprite3D> > mxvk::VK_Window::sprites3d {}

protectedinherited

Definition at line 662 of file mxvk.hpp.

surface

VkSurfaceKHR mxvk::VK_Window::surface = VK_NULL_HANDLE

protectedinherited

Definition at line 594 of file mxvk.hpp.

swapchain

VkSwapchainKHR mxvk::VK_Window::swapchain = VK_NULL_HANDLE

protectedinherited

Definition at line 603 of file mxvk.hpp.

swapchain_extent

VkExtent2D mxvk::VK_Window::swapchain_extent {}

protectedinherited

Definition at line 606 of file mxvk.hpp.

swapchain_format

VkFormat mxvk::VK_Window::swapchain_format = VK_FORMAT_UNDEFINED

protectedinherited

Definition at line 604 of file mxvk.hpp.

swapchain_image_initialized

std::vector<bool> mxvk::VK_Window::swapchain_image_initialized {}

protectedinherited

Definition at line 610 of file mxvk.hpp.

swapchain_image_views

std::vector<VkImageView> mxvk::VK_Window::swapchain_image_views {}

protectedinherited

Definition at line 609 of file mxvk.hpp.

swapchain_images

std::vector<VkImage> mxvk::VK_Window::swapchain_images {}

protectedinherited

Definition at line 608 of file mxvk.hpp.

swapchain_supports_transfer_src

bool mxvk::VK_Window::swapchain_supports_transfer_src = false

protectedinherited

Definition at line 625 of file mxvk.hpp.

text_descriptor_set_layout

VkDescriptorSetLayout mxvk::VK_Window::text_descriptor_set_layout = VK_NULL_HANDLE

protectedinherited

Definition at line 691 of file mxvk.hpp.

text_pipeline

VkPipeline mxvk::VK_Window::text_pipeline = VK_NULL_HANDLE

protectedinherited

Definition at line 693 of file mxvk.hpp.

text_pipeline_layout

VkPipelineLayout mxvk::VK_Window::text_pipeline_layout = VK_NULL_HANDLE

protectedinherited

Definition at line 692 of file mxvk.hpp.

text_renderer

std::unique_ptr<VK_Text> mxvk::VK_Window::text_renderer {}

protectedinherited

Definition at line 689 of file mxvk.hpp.

text_state_dirty

bool mxvk::VK_Window::text_state_dirty = false

protectedinherited

Definition at line 694 of file mxvk.hpp.

validation_enabled

bool mxvk::VK_Window::validation_enabled = false

protectedinherited

Definition at line 652 of file mxvk.hpp.

vulkan_library_loaded

bool mxvk::VK_Window::vulkan_library_loaded = false

protectedinherited

Definition at line 628 of file mxvk.hpp.

window

std::unique_ptr<SDL_Window, SDLWindowDeleter> mxvk::VK_Window::window {}

protectedinherited

Definition at line 591 of file mxvk.hpp.

---

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

• examples/3dmath_masterpiece/main.cpp
• examples/masterpiece/main.cpp