mxvk_abstract_model.cpp

Go to the documentation of this file.

#include "mxvk/mxvk_abstract_model.hpp"
#include "mxvk/mxvk_opencv_compat.hpp"
 
#include <cstring>
 
#include "mxvk/mxvk_exception.hpp"
#include "mxvk/mxvk_png.hpp"
#include "mxvk/mxvk_shader_module.hpp"
 
#include <algorithm>
#include <array>
#include <filesystem>
#include <fstream>
#include <iostream>
#include <sstream>
#ifdef MXVK_CUDA
#include <unistd.h>
#endif
 
namespace mxvk {
 
    namespace {
        struct ModelPushConstants {
            glm::mat4 model{1.0f};
            glm::vec4 fx{0.0f};
        };
 
        void logVKAbstractModelStep(const std::string &message, bool important = false) {
            if (important) {
                std::cout << "mxvk_abstract_model: " << message << '\n';
            }
        }
 
        [[nodiscard]] std::string parseMTLTexturePath(std::istream &stream) {
            std::string texturePath{};
            std::string token{};
            while (stream >> token) {
                if (!token.empty() && token[0] == '-') {
                    if (token == "-blendu" || token == "-blendv" || token == "-cc" ||
                        token == "-clamp" || token == "-imfchan" || token == "-type") {
                        stream >> token;
                    } else if (token == "-mm") {
                        stream >> token;
                        stream >> token;
                    } else if (token == "-o" || token == "-s" || token == "-t") {
                        stream >> token;
                        stream >> token;
                        stream >> token;
                    } else if (token == "-bm" || token == "-boost" || token == "-texres") {
                        stream >> token;
                    }
                    continue;
                }
 
                if (!texturePath.empty()) {
                    texturePath += ' ';
                }
                texturePath += token;
            }
            return texturePath;
        }
 
        [[nodiscard]] std::string resolveTexturePath(const std::string &textureBasePath, const std::string &texturePath) {
            if (texturePath.empty()) {
                return {};
            }
 
            std::filesystem::path resolvedPath(texturePath);
            if (resolvedPath.is_absolute()) {
                resolvedPath = resolvedPath.filename();
            }
 
            if (textureBasePath.empty()) {
                return resolvedPath.string();
            }
 
            return (std::filesystem::path(textureBasePath) / resolvedPath).string();
        }
    } // namespace
 
    void VKAbstractModel::load(VK_Window *targetWindow,
                               const std::string &modelPath,
                               const std::string &textureManifestPath,
                               const std::string &textureBasePath,
                               float scale) {
        if (targetWindow == nullptr) {
            throw mxvk::Exception("VKAbstractModel::load requires a valid window");
        }
        if (modelPath.empty()) {
            throw mxvk::Exception("VKAbstractModel::load modelPath is empty");
        }
 
        logVKAbstractModelStep("creation begin: " + modelPath, true);
 
        windowPtr = targetWindow;
        if (!windowPtr->ensureRenderResources()) {
            throw mxvk::Exception("VKAbstractModel::load failed because render resources are not ready");
        }
 
        obj.load(modelPath, scale);
        obj.upload(windowPtr->getDevice(), windowPtr->getPhysicalDevice(), windowPtr->getCommandPool(), windowPtr->getGraphicsQueue());
        computeBoundsAndScale();
        logVKAbstractModelStep("mesh upload complete", true);
 
        textures.clear();
        if (!textureManifestPath.empty()) {
            loadTextures(textureManifestPath, textureBasePath);
        } else {
            loadTexturesFromMTL(textureBasePath.empty() ? std::filesystem::path(modelPath).parent_path().string() : textureBasePath);
        }
        if (textures.empty()) {
            createFallbackTexture();
            logVKAbstractModelStep("using fallback texture", true);
        }
        logVKAbstractModelStep("textures ready: " + std::to_string(textures.size()), true);
 
        createTextureSampler();
        createDescriptorSetLayout();
        createUniformBuffers();
        createDescriptorPool();
        createDescriptorSets();
        createPipelines();
        logVKAbstractModelStep("creation complete", true);
    }
 
    void VKAbstractModel::load(VK_Window *targetWindow,
                               MXModel &&model,
                               const std::string &textureManifestPath,
                               const std::string &textureBasePath,
                               [[maybe_unused]] float scale) {
        if (targetWindow == nullptr) {
            throw mxvk::Exception("VKAbstractModel::load requires a valid window");
        }
 
        windowPtr = targetWindow;
        if (!windowPtr->ensureRenderResources()) {
            throw mxvk::Exception("VKAbstractModel::load failed because render resources are not ready");
        }
 
        obj = std::move(model);
        obj.upload(windowPtr->getDevice(), windowPtr->getPhysicalDevice(), windowPtr->getCommandPool(), windowPtr->getGraphicsQueue());
        computeBoundsAndScale();
        logVKAbstractModelStep("mesh upload complete (prepared)", true);
 
        textures.clear();
        if (!textureManifestPath.empty()) {
            loadTextures(textureManifestPath, textureBasePath);
        } else if (!obj.mtlLibPath().empty()) {
            loadTexturesFromMTL(textureBasePath.empty() ? std::filesystem::path(obj.mtlLibPath()).parent_path().string() : textureBasePath);
        } else {
            createFallbackTexture();
            logVKAbstractModelStep("using fallback texture", true);
        }
        if (textures.empty()) {
            createFallbackTexture();
            logVKAbstractModelStep("using fallback texture", true);
        }
        logVKAbstractModelStep("textures ready: " + std::to_string(textures.size()), true);
 
        createTextureSampler();
        createDescriptorSetLayout();
        createUniformBuffers();
        createDescriptorPool();
        createDescriptorSets();
        createPipelines();
        logVKAbstractModelStep("creation complete", true);
    }
 
    void VKAbstractModel::setShaders(VK_Window *targetWindow, const std::string &vertSpv, const std::string &fragSpv) {
        if (targetWindow == nullptr) {
            throw mxvk::Exception("VKAbstractModel::setShaders requires a valid window");
        }
 
        windowPtr = targetWindow;
        vertexShaderPath = vertSpv;
        fragmentShaderPath = fragSpv;
        logVKAbstractModelStep("setShaders", true);
        createPipelines();
    }
 
    void VKAbstractModel::setBackfaceCulling(bool enabled) {
        if (backfaceCullingEnabled == enabled) {
            return;
        }
 
        backfaceCullingEnabled = enabled;
        if (windowPtr != nullptr) {
            createPipelines();
        }
    }
 
    void VKAbstractModel::setAlphaBlending(bool enabled) {
        if (alphaBlendingEnabled == enabled) {
            return;
        }
 
        alphaBlendingEnabled = enabled;
        if (windowPtr != nullptr) {
            createPipelines();
        }
    }
 
    void VKAbstractModel::updateUBO(uint32_t imageIndex, const UniformBufferObject &ubo) {
        if (imageIndex >= uniformBuffersMapped.size()) {
            return;
        }
        if (uniformBuffersMapped[imageIndex] == nullptr) {
            return;
        }
 
        std::memcpy(uniformBuffersMapped[imageIndex], &ubo, sizeof(UniformBufferObject));
    }
 
    void VKAbstractModel::enableExtendedFragmentUniforms() {
        if (windowPtr != nullptr) {
            throw mxvk::Exception("VKAbstractModel::enableExtendedFragmentUniforms must be called before load");
        }
        extendedFragmentUniformsEnabled = true;
    }
 
    void VKAbstractModel::updateFragmentUBO(uint32_t imageIndex, const ModelFragmentUniforms &uniforms) {
        if (imageIndex >= fragmentUniformBuffersMapped.size() || fragmentUniformBuffersMapped[imageIndex] == nullptr) {
            return;
        }
        std::memcpy(fragmentUniformBuffersMapped[imageIndex], &uniforms, sizeof(ModelFragmentUniforms));
    }
 
    void VKAbstractModel::setFragmentPushConstants(const ModelFragmentPushConstants &constants) {
        fragmentPushConstants = constants;
    }
 
    bool VKAbstractModel::updatePrimaryTexture(const void *pixels, int width, int height, int pitch) {
        if (windowPtr == nullptr || windowPtr->getDevice() == VK_NULL_HANDLE) {
            return false;
        }
        if (pixels == nullptr || width <= 0 || height <= 0) {
            return false;
        }
 
        const uint32_t uploadWidth = static_cast<uint32_t>(width);
        const uint32_t uploadHeight = static_cast<uint32_t>(height);
        const uint32_t srcRowBytes = static_cast<uint32_t>(pitch > 0 ? pitch : width * 4);
        const uint32_t tightRowBytes = uploadWidth * 4U;
        if (srcRowBytes < tightRowBytes) {
            return false;
        }
 
        if (textures.empty()) {
            createFallbackTexture();
            createDescriptorSets();
        }
 
        TextureEntry &texture = textures[0];
        if (texture.image == VK_NULL_HANDLE || texture.memory == VK_NULL_HANDLE || texture.view == VK_NULL_HANDLE) {
            return false;
        }
 
        bool recreatedTexture = false;
        if (texture.width != uploadWidth || texture.height != uploadHeight) {
            vkDeviceWaitIdle(windowPtr->getDevice());
 
#ifdef MXVK_CUDA
            destroyTextureCudaInterop(texture);
#endif
            if (texture.view != VK_NULL_HANDLE) {
                vkDestroyImageView(windowPtr->getDevice(), texture.view, nullptr);
            }
            if (texture.image != VK_NULL_HANDLE) {
                vkDestroyImage(windowPtr->getDevice(), texture.image, nullptr);
            }
            if (texture.memory != VK_NULL_HANDLE) {
                vkFreeMemory(windowPtr->getDevice(), texture.memory, nullptr);
            }
 
            texture.view = VK_NULL_HANDLE;
            texture.image = VK_NULL_HANDLE;
            texture.memory = VK_NULL_HANDLE;
 
            createTextureImage(uploadWidth, uploadHeight, texture);
 
            texture.view = createImageView(texture.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
            texture.width = uploadWidth;
            texture.height = uploadHeight;
            recreatedTexture = true;
 
            createDescriptorSets();
        }
 
#ifdef MXVK_CUDA
        if (updatePrimaryTextureCudaHost(texture, pixels, uploadWidth, uploadHeight, srcRowBytes)) {
            return true;
        }
#endif
 
        const VkDeviceSize stagingSize = static_cast<VkDeviceSize>(tightRowBytes) * uploadHeight;
        VkBuffer stagingBuffer = VK_NULL_HANDLE;
        VkDeviceMemory stagingMemory = VK_NULL_HANDLE;
        createBuffer(stagingSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT,
                     VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                     stagingBuffer, stagingMemory);
 
        void *mapped = nullptr;
        const VkResult mapResult = vkMapMemory(windowPtr->getDevice(), stagingMemory, 0, stagingSize, 0, &mapped);
        if (mapResult != VK_SUCCESS || mapped == nullptr) {
            vkDestroyBuffer(windowPtr->getDevice(), stagingBuffer, nullptr);
            vkFreeMemory(windowPtr->getDevice(), stagingMemory, nullptr);
            return false;
        }
 
        if (srcRowBytes == tightRowBytes) {
            std::memcpy(mapped, pixels, static_cast<size_t>(stagingSize));
        } else {
            const auto *src = static_cast<const uint8_t *>(pixels);
            auto *dst = static_cast<uint8_t *>(mapped);
            for (uint32_t y = 0; y < uploadHeight; ++y) {
                const size_t srcOffset = static_cast<size_t>(y) * srcRowBytes;
                const size_t dstOffset = static_cast<size_t>(y) * tightRowBytes;
                std::memcpy(dst + dstOffset, src + srcOffset, tightRowBytes);
            }
        }
        vkUnmapMemory(windowPtr->getDevice(), stagingMemory);
 
        if (recreatedTexture) {
            transitionImageLayout(texture.image, VK_FORMAT_R8G8B8A8_UNORM,
                                  VK_IMAGE_LAYOUT_UNDEFINED,
                                  VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);
        } else {
            transitionImageLayout(texture.image, VK_FORMAT_R8G8B8A8_UNORM,
                                  VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL,
                                  VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);
        }
        copyBufferToImage(stagingBuffer, texture.image, uploadWidth, uploadHeight);
        transitionImageLayout(texture.image, VK_FORMAT_R8G8B8A8_UNORM,
                              VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
                              VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
#ifdef MXVK_CUDA
        texture.cudaImageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
#endif
 
        vkDestroyBuffer(windowPtr->getDevice(), stagingBuffer, nullptr);
        vkFreeMemory(windowPtr->getDevice(), stagingMemory, nullptr);
        return true;
    }
 
    void VKAbstractModel::render(VkCommandBuffer cmd, uint32_t imageIndex, bool wireframe) const {
        if (cmd == VK_NULL_HANDLE || imageIndex >= uniformBuffers.size() || descriptorSets.empty()) {
            return;
        }
 
        const VkPipeline pipeline = (wireframe && pipelineWireframe != VK_NULL_HANDLE) ? pipelineWireframe : pipelineFill;
        if (pipeline == VK_NULL_HANDLE || pipelineLayout == VK_NULL_HANDLE) {
            return;
        }
 
        vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline);
        if (extendedFragmentUniformsEnabled) {
            vkCmdPushConstants(cmd,
                               pipelineLayout,
                               VK_SHADER_STAGE_FRAGMENT_BIT,
                               0,
                               sizeof(ModelFragmentPushConstants),
                               &fragmentPushConstants);
        }
 
        const size_t textureCount = std::max<size_t>(1, textures.size());
        for (size_t i = 0; i < obj.subMeshCount(); ++i) {
            const SubMesh &submesh = obj.subMesh(i);
            const size_t textureIndex = std::min<size_t>(submesh.textureIndex, textureCount - 1U);
            const size_t setIndex = static_cast<size_t>(imageIndex) * textureCount + textureIndex;
            if (setIndex >= descriptorSets.size()) {
                continue;
            }
 
            vkCmdBindDescriptorSets(cmd,
                                    VK_PIPELINE_BIND_POINT_GRAPHICS,
                                    pipelineLayout,
                                    0,
                                    1,
                                    &descriptorSets[setIndex],
                                    0,
                                    nullptr);
 
            obj.drawSubMesh(cmd, i);
        }
    }
 
    void VKAbstractModel::renderWithPushConstants(VkCommandBuffer cmd,
                                                  uint32_t imageIndex,
                                                  size_t textureIndex,
                                                  const UniformBufferObject &ubo,
                                                  bool wireframe) {
        if (cmd == VK_NULL_HANDLE || imageIndex >= uniformBuffers.size() || descriptorSets.empty()) {
            return;
        }
 
        const VkPipeline pipeline = (wireframe && pipelineWireframe != VK_NULL_HANDLE) ? pipelineWireframe : pipelineFill;
        if (pipeline == VK_NULL_HANDLE || pipelineLayout == VK_NULL_HANDLE) {
            return;
        }
 
        const size_t textureCount = std::max<size_t>(1, textures.size());
        textureIndex = std::min(textureIndex, textureCount - 1U);
        const size_t setIndex = static_cast<size_t>(imageIndex) * textureCount + textureIndex;
        if (setIndex >= descriptorSets.size()) {
            return;
        }
 
        vkCmdBindPipeline(cmd, VK_PIPELINE_BIND_POINT_GRAPHICS, pipeline);
        updateUBO(imageIndex, ubo);
        const ModelPushConstants pushConstants{
            .model = ubo.model,
            .fx = ubo.fx,
        };
        vkCmdPushConstants(cmd,
                           pipelineLayout,
                           VK_SHADER_STAGE_VERTEX_BIT,
                           0,
                           sizeof(ModelPushConstants),
                           &pushConstants);
        if (extendedFragmentUniformsEnabled) {
            vkCmdPushConstants(cmd,
                               pipelineLayout,
                               VK_SHADER_STAGE_FRAGMENT_BIT,
                               0,
                               sizeof(ModelFragmentPushConstants),
                               &fragmentPushConstants);
        }
        vkCmdBindDescriptorSets(cmd,
                                VK_PIPELINE_BIND_POINT_GRAPHICS,
                                pipelineLayout,
                                0,
                                1,
                                &descriptorSets[setIndex],
                                0,
                                nullptr);
 
        obj.draw(cmd);
    }
 
    void VKAbstractModel::resize(VK_Window *targetWindow) {
        if (targetWindow == nullptr || targetWindow->getDevice() == VK_NULL_HANDLE) {
            return;
        }
        if (!isLoaded()) {
            return;
        }
 
        logVKAbstractModelStep("resize begin", true);
        windowPtr = targetWindow;
        destroyPipelines();
        destroyDescriptors();
 
        createDescriptorSetLayout();
        createUniformBuffers();
        createDescriptorPool();
        createDescriptorSets();
        createPipelines();
        logVKAbstractModelStep("resize complete", true);
    }
 
    void VKAbstractModel::cleanup(VK_Window *targetWindow) {
        if (targetWindow == nullptr || targetWindow->getDevice() == VK_NULL_HANDLE) {
            return;
        }
 
        logVKAbstractModelStep("teardown begin", true);
        windowPtr = targetWindow;
        destroyPipelines();
        destroyDescriptors();
        destroyTextures();
        obj.cleanup(windowPtr->getDevice());
        windowPtr = nullptr;
        logVKAbstractModelStep("teardown complete", true);
    }
 
    void VKAbstractModel::computeBoundsAndScale() {
        const auto &vertices = obj.vertices();
        if (vertices.empty()) {
            modelCenterOffsetValue = glm::vec3(0.0f);
            modelRenderScaleValue = 1.0f;
            modelAxisExtentValue = glm::vec3(1.0f);
            return;
        }
 
        float minX = vertices.front().pos[0];
        float maxX = minX;
        float minY = vertices.front().pos[1];
        float maxY = minY;
        float minZ = vertices.front().pos[2];
        float maxZ = minZ;
 
        for (const VKVertex &v : vertices) {
            minX = std::min(minX, v.pos[0]);
            maxX = std::max(maxX, v.pos[0]);
            minY = std::min(minY, v.pos[1]);
            maxY = std::max(maxY, v.pos[1]);
            minZ = std::min(minZ, v.pos[2]);
            maxZ = std::max(maxZ, v.pos[2]);
        }
 
        modelCenterOffsetValue = glm::vec3(
            -0.5f * (minX + maxX),
            -0.5f * (minY + maxY),
            -0.5f * (minZ + maxZ));
 
        modelAxisExtentValue = glm::vec3(maxX - minX, maxY - minY, maxZ - minZ);
        const float maxExtent = std::max(modelAxisExtentValue.x, std::max(modelAxisExtentValue.y, modelAxisExtentValue.z));
        modelRenderScaleValue = (maxExtent > 1e-6f) ? (2.5f / maxExtent) : 1.0f;
    }
 
    void VKAbstractModel::loadTextures(const std::string &textureManifestPath, const std::string &textureBasePath) {
        std::ifstream file(textureManifestPath);
        if (!file.is_open()) {
            throw mxvk::Exception("Failed to open texture manifest: " + textureManifestPath);
        }
 
        std::vector<std::string> lines{};
        std::string line;
        while (std::getline(file, line)) {
            const size_t begin = line.find_first_not_of(" \t\r\n");
            if (begin == std::string::npos) {
                continue;
            }
            const size_t end = line.find_last_not_of(" \t\r\n");
            line = line.substr(begin, end - begin + 1);
            if (line.empty() || line[0] == '#') {
                continue;
            }
            lines.push_back(line);
        }
 
        bool isStructured = false;
        bool isMtlLike = false;
        for (const std::string &ln : lines) {
            std::istringstream stream(ln);
            std::string keyword;
            stream >> keyword;
            if (keyword == "submesh" || keyword == "texture_dir" || keyword == "material_lib" || keyword == "model") {
                isStructured = true;
                break;
            }
            if (keyword == "newmtl") {
                isMtlLike = true;
                break;
            }
        }
 
        std::vector<std::string> imagePaths{};
        const std::string prefix = textureBasePath;
 
        if (isMtlLike) {
            int currentMaterialTexture = -1;
            for (const std::string &ln : lines) {
                std::istringstream stream(ln);
                std::string keyword;
                stream >> keyword;
                if (keyword == "newmtl") {
                    imagePaths.emplace_back();
                    currentMaterialTexture = static_cast<int>(imagePaths.size()) - 1;
                } else if (keyword == "map_Kd") {
                    const std::string image = parseMTLTexturePath(stream);
                    if (!image.empty() && currentMaterialTexture >= 0) {
                        imagePaths[static_cast<size_t>(currentMaterialTexture)] = resolveTexturePath(prefix, image);
                    }
                }
            }
        } else if (isStructured) {
            for (const std::string &ln : lines) {
                std::istringstream stream(ln);
                std::string keyword;
                stream >> keyword;
                if (keyword == "texture") {
                    std::string image;
                    if (stream >> image) {
                        imagePaths.push_back(resolveTexturePath(prefix, image));
                    }
                }
            }
        } else {
            for (const std::string &ln : lines) {
                imagePaths.push_back(resolveTexturePath(prefix, ln));
            }
        }
 
        if (imagePaths.empty()) {
            logVKAbstractModelStep("no texture candidates found in manifest [" + textureManifestPath + "]");
        }
 
        for (const std::string &path : imagePaths) {
            if (path.empty()) {
                logVKAbstractModelStep("material has no texture map; using fallback texture slot");
                createFallbackTexture();
                continue;
            }
 
            logVKAbstractModelStep("trying texture [" + path + "]");
            SDL_Surface *surface = mxvk::LoadPNG(path.c_str());
            if (surface == nullptr) {
                logVKAbstractModelStep("texture not found [" + path + "]");
                createFallbackTexture();
                continue;
            }
 
            const uint32_t width = static_cast<uint32_t>(surface->w);
            const uint32_t height = static_cast<uint32_t>(surface->h);
 
            TextureEntry tex{};
            tex.width = width;
            tex.height = height;
            createTextureImage(width, height, tex);
 
#ifdef MXVK_CUDA
            if (updatePrimaryTextureCudaHost(tex, surface->pixels, width, height, static_cast<uint32_t>(surface->pitch))) {
                tex.view = createImageView(tex.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
                textures.push_back(tex);
                SDL_DestroySurface(surface);
                continue;
            }
#endif
 
            const VkDeviceSize imageSize = static_cast<VkDeviceSize>(width) * static_cast<VkDeviceSize>(height) * 4U;
            VkBuffer stagingBuffer = VK_NULL_HANDLE;
            VkDeviceMemory stagingMemory = VK_NULL_HANDLE;
            createBuffer(imageSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT,
                         VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                         stagingBuffer, stagingMemory);
 
            void *mapped = nullptr;
            vkMapMemory(windowPtr->getDevice(), stagingMemory, 0, imageSize, 0, &mapped);
            std::memcpy(mapped, surface->pixels, static_cast<size_t>(imageSize));
            vkUnmapMemory(windowPtr->getDevice(), stagingMemory);
 
#ifdef MXVK_CUDA
            const VkImageLayout uploadOldLayout = (tex.cudaImageLayout == VK_IMAGE_LAYOUT_GENERAL)
                                                      ? VK_IMAGE_LAYOUT_GENERAL
                                                      : VK_IMAGE_LAYOUT_UNDEFINED;
#else
            const VkImageLayout uploadOldLayout = VK_IMAGE_LAYOUT_UNDEFINED;
#endif
            transitionImageLayout(tex.image, VK_FORMAT_R8G8B8A8_UNORM,
                                  uploadOldLayout,
                                  VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);
            copyBufferToImage(stagingBuffer, tex.image, width, height);
            transitionImageLayout(tex.image, VK_FORMAT_R8G8B8A8_UNORM,
                                  VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
                                  VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
#ifdef MXVK_CUDA
            tex.cudaImageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
#endif
 
            tex.view = createImageView(tex.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
            textures.push_back(tex);
 
            vkDestroyBuffer(windowPtr->getDevice(), stagingBuffer, nullptr);
            vkFreeMemory(windowPtr->getDevice(), stagingMemory, nullptr);
            SDL_DestroySurface(surface);
        }
    }
 
    void VKAbstractModel::loadTexturesFromMTL(const std::string &textureBasePath) {
        bool foundTextureReference = false;
        for (const MXMaterial &material : obj.materials()) {
            if (material.map_kd.empty()) {
                createFallbackTexture();
                continue;
            }
 
            foundTextureReference = true;
            const std::string path = resolveTexturePath(textureBasePath, material.map_kd);
            logVKAbstractModelStep("trying texture [" + path + "]");
            SDL_Surface *surface = mxvk::LoadPNG(path.c_str());
            if (surface == nullptr) {
                logVKAbstractModelStep("texture not found [" + path + "]");
                createFallbackTexture();
                continue;
            }
 
            const uint32_t width = static_cast<uint32_t>(surface->w);
            const uint32_t height = static_cast<uint32_t>(surface->h);
 
            TextureEntry tex{};
            tex.width = width;
            tex.height = height;
            createTextureImage(width, height, tex);
 
#ifdef MXVK_CUDA
            if (updatePrimaryTextureCudaHost(tex, surface->pixels, width, height, static_cast<uint32_t>(surface->pitch))) {
                tex.view = createImageView(tex.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
                textures.push_back(tex);
                SDL_DestroySurface(surface);
                continue;
            }
#endif
 
            const VkDeviceSize imageSize = static_cast<VkDeviceSize>(width) * static_cast<VkDeviceSize>(height) * 4U;
            VkBuffer stagingBuffer = VK_NULL_HANDLE;
            VkDeviceMemory stagingMemory = VK_NULL_HANDLE;
            createBuffer(imageSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT,
                         VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                         stagingBuffer, stagingMemory);
 
            void *mapped = nullptr;
            vkMapMemory(windowPtr->getDevice(), stagingMemory, 0, imageSize, 0, &mapped);
            std::memcpy(mapped, surface->pixels, static_cast<size_t>(imageSize));
            vkUnmapMemory(windowPtr->getDevice(), stagingMemory);
 
#ifdef MXVK_CUDA
            const VkImageLayout uploadOldLayout = (tex.cudaImageLayout == VK_IMAGE_LAYOUT_GENERAL)
                                                      ? VK_IMAGE_LAYOUT_GENERAL
                                                      : VK_IMAGE_LAYOUT_UNDEFINED;
#else
            const VkImageLayout uploadOldLayout = VK_IMAGE_LAYOUT_UNDEFINED;
#endif
            transitionImageLayout(tex.image, VK_FORMAT_R8G8B8A8_UNORM,
                                  uploadOldLayout,
                                  VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);
            copyBufferToImage(stagingBuffer, tex.image, width, height);
            transitionImageLayout(tex.image, VK_FORMAT_R8G8B8A8_UNORM,
                                  VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
                                  VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
#ifdef MXVK_CUDA
            tex.cudaImageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
#endif
 
            tex.view = createImageView(tex.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
            textures.push_back(tex);
 
            vkDestroyBuffer(windowPtr->getDevice(), stagingBuffer, nullptr);
            vkFreeMemory(windowPtr->getDevice(), stagingMemory, nullptr);
            SDL_DestroySurface(surface);
        }
 
        if (!foundTextureReference) {
            logVKAbstractModelStep("no texture candidates found in MTL materials");
        }
    }
 
    void VKAbstractModel::createFallbackTexture() {
        SDL_Surface *surface = SDL_CreateSurface(1, 1, SDL_PIXELFORMAT_RGBA32);
        if (surface == nullptr) {
            throw mxvk::Exception("VKAbstractModel failed to allocate fallback texture surface");
        }
 
        auto *pixel = static_cast<uint32_t *>(surface->pixels);
        *pixel = 0xFFFFFFFFu;
 
        TextureEntry tex{};
        tex.width = 1;
        tex.height = 1;
        createTextureImage(1, 1, tex);
 
#ifdef MXVK_CUDA
        if (updatePrimaryTextureCudaHost(tex, surface->pixels, 1, 1, static_cast<uint32_t>(surface->pitch))) {
            tex.view = createImageView(tex.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
            textures.push_back(tex);
            SDL_DestroySurface(surface);
            return;
        }
#endif
 
        const VkDeviceSize imageSize = 4;
        VkBuffer stagingBuffer = VK_NULL_HANDLE;
        VkDeviceMemory stagingMemory = VK_NULL_HANDLE;
        createBuffer(imageSize, VK_BUFFER_USAGE_TRANSFER_SRC_BIT,
                     VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                     stagingBuffer, stagingMemory);
 
        void *mapped = nullptr;
        vkMapMemory(windowPtr->getDevice(), stagingMemory, 0, imageSize, 0, &mapped);
        std::memcpy(mapped, surface->pixels, static_cast<size_t>(imageSize));
        vkUnmapMemory(windowPtr->getDevice(), stagingMemory);
 
#ifdef MXVK_CUDA
        const VkImageLayout uploadOldLayout = (tex.cudaImageLayout == VK_IMAGE_LAYOUT_GENERAL)
                                                  ? VK_IMAGE_LAYOUT_GENERAL
                                                  : VK_IMAGE_LAYOUT_UNDEFINED;
#else
        const VkImageLayout uploadOldLayout = VK_IMAGE_LAYOUT_UNDEFINED;
#endif
        transitionImageLayout(tex.image, VK_FORMAT_R8G8B8A8_UNORM,
                              uploadOldLayout,
                              VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);
        copyBufferToImage(stagingBuffer, tex.image, 1, 1);
        transitionImageLayout(tex.image, VK_FORMAT_R8G8B8A8_UNORM,
                              VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
                              VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
#ifdef MXVK_CUDA
        tex.cudaImageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
#endif
        tex.view = createImageView(tex.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
        textures.push_back(tex);
 
        vkDestroyBuffer(windowPtr->getDevice(), stagingBuffer, nullptr);
        vkFreeMemory(windowPtr->getDevice(), stagingMemory, nullptr);
        SDL_DestroySurface(surface);
    }
 
    void VKAbstractModel::createBuffer(VkDeviceSize size, VkBufferUsageFlags usage,
                                       VkMemoryPropertyFlags properties, VkBuffer &buffer,
                                       VkDeviceMemory &bufferMemory) const {
        VkBufferCreateInfo bufferInfo{};
        bufferInfo.sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO;
        bufferInfo.size = size;
        bufferInfo.usage = usage;
        bufferInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
 
        if (vkCreateBuffer(windowPtr->getDevice(), &bufferInfo, nullptr, &buffer) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to create buffer");
        }
 
        VkMemoryRequirements requirements{};
        vkGetBufferMemoryRequirements(windowPtr->getDevice(), buffer, &requirements);
 
        VkMemoryAllocateInfo allocInfo{};
        allocInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
        allocInfo.allocationSize = requirements.size;
 
        try {
            allocInfo.memoryTypeIndex = findMemoryType(requirements.memoryTypeBits, properties);
            if (vkAllocateMemory(windowPtr->getDevice(), &allocInfo, nullptr, &bufferMemory) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to allocate buffer memory");
            }
 
            if (vkBindBufferMemory(windowPtr->getDevice(), buffer, bufferMemory, 0) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to bind buffer memory");
            }
        } catch (...) {
            if (bufferMemory != VK_NULL_HANDLE) {
                vkFreeMemory(windowPtr->getDevice(), bufferMemory, nullptr);
                bufferMemory = VK_NULL_HANDLE;
            }
            if (buffer != VK_NULL_HANDLE) {
                vkDestroyBuffer(windowPtr->getDevice(), buffer, nullptr);
                buffer = VK_NULL_HANDLE;
            }
            throw;
        }
    }
 
    uint32_t VKAbstractModel::findMemoryType(uint32_t typeFilter, VkMemoryPropertyFlags properties) const {
        VkPhysicalDeviceMemoryProperties memProperties{};
        vkGetPhysicalDeviceMemoryProperties(windowPtr->getPhysicalDevice(), &memProperties);
 
        for (uint32_t i = 0; i < memProperties.memoryTypeCount; ++i) {
            const bool typeSupported = (typeFilter & (1u << i)) != 0u;
            const bool propsSupported =
                (memProperties.memoryTypes[i].propertyFlags & properties) == properties;
            if (typeSupported && propsSupported) {
                return i;
            }
        }
 
        throw mxvk::Exception("VKAbstractModel failed to find suitable memory type");
    }
 
    VkCommandBuffer VKAbstractModel::beginSingleTimeCommands() const {
        VkCommandBufferAllocateInfo allocInfo{};
        allocInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO;
        allocInfo.level = VK_COMMAND_BUFFER_LEVEL_PRIMARY;
        allocInfo.commandPool = windowPtr->getCommandPool();
        allocInfo.commandBufferCount = 1;
 
        VkCommandBuffer commandBuffer = VK_NULL_HANDLE;
        if (vkAllocateCommandBuffers(windowPtr->getDevice(), &allocInfo, &commandBuffer) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to allocate command buffer");
        }
 
        VkCommandBufferBeginInfo beginInfo{};
        beginInfo.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
        beginInfo.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
        if (vkBeginCommandBuffer(commandBuffer, &beginInfo) != VK_SUCCESS) {
            vkFreeCommandBuffers(windowPtr->getDevice(), windowPtr->getCommandPool(), 1, &commandBuffer);
            throw mxvk::Exception("VKAbstractModel failed to begin command buffer");
        }
 
        return commandBuffer;
    }
 
    void VKAbstractModel::endSingleTimeCommands(VkCommandBuffer commandBuffer) const {
        if (vkEndCommandBuffer(commandBuffer) != VK_SUCCESS) {
            vkFreeCommandBuffers(windowPtr->getDevice(), windowPtr->getCommandPool(), 1, &commandBuffer);
            throw mxvk::Exception("VKAbstractModel failed to end command buffer");
        }
 
        VkSubmitInfo submitInfo{};
        submitInfo.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO;
        submitInfo.commandBufferCount = 1;
        submitInfo.pCommandBuffers = &commandBuffer;
 
        if (vkQueueSubmit(windowPtr->getGraphicsQueue(), 1, &submitInfo, VK_NULL_HANDLE) != VK_SUCCESS) {
            vkFreeCommandBuffers(windowPtr->getDevice(), windowPtr->getCommandPool(), 1, &commandBuffer);
            throw mxvk::Exception("VKAbstractModel failed to submit command buffer");
        }
        if (vkQueueWaitIdle(windowPtr->getGraphicsQueue()) != VK_SUCCESS) {
            vkFreeCommandBuffers(windowPtr->getDevice(), windowPtr->getCommandPool(), 1, &commandBuffer);
            throw mxvk::Exception("VKAbstractModel failed to wait for queue idle");
        }
 
        vkFreeCommandBuffers(windowPtr->getDevice(), windowPtr->getCommandPool(), 1, &commandBuffer);
    }
 
    void VKAbstractModel::createImage(uint32_t width, uint32_t height, VkFormat format,
                                      VkImageTiling tiling, VkImageUsageFlags usage,
                                      VkMemoryPropertyFlags properties, VkImage &image,
                                      VkDeviceMemory &memory) const {
        VkImageCreateInfo imageInfo{};
        imageInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
        imageInfo.imageType = VK_IMAGE_TYPE_2D;
        imageInfo.extent.width = width;
        imageInfo.extent.height = height;
        imageInfo.extent.depth = 1;
        imageInfo.mipLevels = 1;
        imageInfo.arrayLayers = 1;
        imageInfo.format = format;
        imageInfo.tiling = tiling;
        imageInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
        imageInfo.usage = usage;
        imageInfo.samples = VK_SAMPLE_COUNT_1_BIT;
        imageInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
 
        if (vkCreateImage(windowPtr->getDevice(), &imageInfo, nullptr, &image) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to create image");
        }
 
        VkMemoryRequirements requirements{};
        vkGetImageMemoryRequirements(windowPtr->getDevice(), image, &requirements);
 
        VkMemoryAllocateInfo allocInfo{};
        allocInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
        allocInfo.allocationSize = requirements.size;
 
        try {
            allocInfo.memoryTypeIndex = findMemoryType(requirements.memoryTypeBits, properties);
            if (vkAllocateMemory(windowPtr->getDevice(), &allocInfo, nullptr, &memory) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to allocate image memory");
            }
 
            if (vkBindImageMemory(windowPtr->getDevice(), image, memory, 0) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to bind image memory");
            }
        } catch (...) {
            if (memory != VK_NULL_HANDLE) {
                vkFreeMemory(windowPtr->getDevice(), memory, nullptr);
                memory = VK_NULL_HANDLE;
            }
            if (image != VK_NULL_HANDLE) {
                vkDestroyImage(windowPtr->getDevice(), image, nullptr);
                image = VK_NULL_HANDLE;
            }
            throw;
        }
    }
 
    void VKAbstractModel::createTextureImage(uint32_t width, uint32_t height, TextureEntry &texture) const {
#ifdef MXVK_CUDA
        try {
            createCudaExportableImage(width, height, texture);
            return;
        } catch (const std::exception &ex) {
            logVKAbstractModelStep(std::format(
                "CUDA exportable model texture unavailable: {}; using standard Vulkan texture",
                ex.what()));
            texture.cudaExportMemorySize = 0;
            texture.cudaInteropEnabled = false;
            texture.cudaInteropUnavailableLogged = true;
        }
#endif
 
        createImage(width, height, VK_FORMAT_R8G8B8A8_UNORM,
                    VK_IMAGE_TILING_OPTIMAL,
                    VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_SAMPLED_BIT,
                    VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT,
                    texture.image, texture.memory);
        texture.width = width;
        texture.height = height;
#ifdef MXVK_CUDA
        texture.cudaImageLayout = VK_IMAGE_LAYOUT_UNDEFINED;
#endif
    }
 
#ifdef MXVK_CUDA
    void VKAbstractModel::destroyTextureCudaInterop(TextureEntry &texture) const {
        if (texture.cudaInteropEnabled || texture.cudaExternalMemory != nullptr || texture.cudaMipmappedArray != nullptr) {
            logVKAbstractModelStep("CUDA interop: destroying imported model texture resources");
        }
        if (texture.cudaMipmappedArray != nullptr) {
            cudaFreeMipmappedArray(texture.cudaMipmappedArray);
            texture.cudaMipmappedArray = nullptr;
            texture.cudaArray = nullptr;
        }
        if (texture.cudaExternalMemory != nullptr) {
            cudaDestroyExternalMemory(texture.cudaExternalMemory);
            texture.cudaExternalMemory = nullptr;
        }
        texture.cudaInteropEnabled = false;
        texture.cudaExportMemorySize = 0;
        texture.cudaUploadLogged = false;
        texture.cudaWriteTransitionLogged = false;
        texture.cudaShaderTransitionLogged = false;
        texture.cudaImageLayout = VK_IMAGE_LAYOUT_UNDEFINED;
    }
 
    void VKAbstractModel::createCudaExportableImage(uint32_t width, uint32_t height, TextureEntry &texture) const {
        logVKAbstractModelStep(std::format(
            "CUDA interop init: requesting exportable model texture {}x{} RGBA8 optimal-tiled OPAQUE_FD",
            width, height));
 
        VkExternalMemoryImageCreateInfo externalImageInfo{};
        externalImageInfo.sType = VK_STRUCTURE_TYPE_EXTERNAL_MEMORY_IMAGE_CREATE_INFO;
        externalImageInfo.handleTypes = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT;
 
        VkImageCreateInfo imageInfo{};
        imageInfo.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
        imageInfo.pNext = &externalImageInfo;
        imageInfo.imageType = VK_IMAGE_TYPE_2D;
        imageInfo.extent.width = width;
        imageInfo.extent.height = height;
        imageInfo.extent.depth = 1;
        imageInfo.mipLevels = 1;
        imageInfo.arrayLayers = 1;
        imageInfo.format = VK_FORMAT_R8G8B8A8_UNORM;
        imageInfo.tiling = VK_IMAGE_TILING_OPTIMAL;
        imageInfo.initialLayout = VK_IMAGE_LAYOUT_UNDEFINED;
        imageInfo.usage = VK_IMAGE_USAGE_TRANSFER_DST_BIT | VK_IMAGE_USAGE_SAMPLED_BIT;
        imageInfo.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
        imageInfo.samples = VK_SAMPLE_COUNT_1_BIT;
 
        if (vkCreateImage(windowPtr->getDevice(), &imageInfo, nullptr, &texture.image) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to create CUDA exportable texture image");
        }
 
        VkMemoryRequirements requirements{};
        vkGetImageMemoryRequirements(windowPtr->getDevice(), texture.image, &requirements);
 
        VkExportMemoryAllocateInfo exportMemoryInfo{};
        exportMemoryInfo.sType = VK_STRUCTURE_TYPE_EXPORT_MEMORY_ALLOCATE_INFO;
        exportMemoryInfo.handleTypes = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT;
 
        VkMemoryAllocateInfo allocInfo{};
        allocInfo.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO;
        allocInfo.pNext = &exportMemoryInfo;
        allocInfo.allocationSize = requirements.size;
 
        try {
            allocInfo.memoryTypeIndex = findMemoryType(requirements.memoryTypeBits, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
            if (vkAllocateMemory(windowPtr->getDevice(), &allocInfo, nullptr, &texture.memory) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to allocate CUDA exportable texture memory");
            }
            if (vkBindImageMemory(windowPtr->getDevice(), texture.image, texture.memory, 0) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to bind CUDA exportable texture memory");
            }
        } catch (...) {
            if (texture.memory != VK_NULL_HANDLE) {
                vkFreeMemory(windowPtr->getDevice(), texture.memory, nullptr);
                texture.memory = VK_NULL_HANDLE;
            }
            if (texture.image != VK_NULL_HANDLE) {
                vkDestroyImage(windowPtr->getDevice(), texture.image, nullptr);
                texture.image = VK_NULL_HANDLE;
            }
            texture.cudaExportMemorySize = 0;
            throw;
        }
 
        texture.width = width;
        texture.height = height;
        texture.cudaExportMemorySize = requirements.size;
        texture.cudaInteropUnavailableLogged = false;
        texture.cudaImageLayout = VK_IMAGE_LAYOUT_UNDEFINED;
        logVKAbstractModelStep(std::format(
            "CUDA interop init: exportable model texture allocated (memorySize={} bytes, memoryType={}); optimal image memory is imported as cudaArray, not wrapped as pitched GpuMat",
            static_cast<unsigned long long>(requirements.size), allocInfo.memoryTypeIndex));
    }
 
    bool VKAbstractModel::ensureTextureCudaInterop(TextureEntry &texture) const {
        if (texture.cudaInteropEnabled) {
            return true;
        }
        if (windowPtr == nullptr || texture.memory == VK_NULL_HANDLE || texture.cudaExportMemorySize == 0) {
            if (!texture.cudaInteropUnavailableLogged) {
                logVKAbstractModelStep("CUDA interop init: model texture is not exportable; CPU staging fallback remains active");
                texture.cudaInteropUnavailableLogged = true;
            }
            return false;
        }
        if (vkGetMemoryFdKHR == nullptr) {
            if (!texture.cudaInteropUnavailableLogged) {
                logVKAbstractModelStep("CUDA interop init: vkGetMemoryFdKHR was not loaded for model texture");
                texture.cudaInteropUnavailableLogged = true;
            }
            return false;
        }
 
        VkMemoryGetFdInfoKHR fdInfo{};
        fdInfo.sType = VK_STRUCTURE_TYPE_MEMORY_GET_FD_INFO_KHR;
        fdInfo.memory = texture.memory;
        fdInfo.handleType = VK_EXTERNAL_MEMORY_HANDLE_TYPE_OPAQUE_FD_BIT;
 
        int memoryFd = -1;
        const VkResult fdResult = vkGetMemoryFdKHR(windowPtr->getDevice(), &fdInfo, &memoryFd);
        if (fdResult != VK_SUCCESS) {
            if (!texture.cudaInteropUnavailableLogged) {
                logVKAbstractModelStep(std::format("CUDA interop init: vkGetMemoryFdKHR failed for model texture ({})", static_cast<int>(fdResult)));
                texture.cudaInteropUnavailableLogged = true;
            }
            return false;
        }
        logVKAbstractModelStep(std::format("CUDA interop init: exported model texture memory fd={}", memoryFd));
 
        cudaExternalMemoryHandleDesc externalMemoryDesc{};
        externalMemoryDesc.type = cudaExternalMemoryHandleTypeOpaqueFd;
        externalMemoryDesc.handle.fd = memoryFd;
        externalMemoryDesc.size = texture.cudaExportMemorySize;
 
        cudaError_t cudaResult = cudaImportExternalMemory(&texture.cudaExternalMemory, &externalMemoryDesc);
        if (cudaResult != cudaSuccess) {
            close(memoryFd);
            if (!texture.cudaInteropUnavailableLogged) {
                logVKAbstractModelStep(std::format("CUDA interop init: cudaImportExternalMemory failed for model texture: {}",
                                                   cudaGetErrorString(cudaResult)));
                texture.cudaInteropUnavailableLogged = true;
            }
            texture.cudaExternalMemory = nullptr;
            return false;
        }
        logVKAbstractModelStep(std::format("CUDA interop init: imported model texture external memory into CUDA ({} bytes)",
                                           static_cast<unsigned long long>(texture.cudaExportMemorySize)));
 
        cudaExternalMemoryMipmappedArrayDesc arrayDesc{};
        arrayDesc.offset = 0;
        arrayDesc.formatDesc = cudaCreateChannelDesc<uchar4>();
        arrayDesc.extent = make_cudaExtent(static_cast<size_t>(texture.width), static_cast<size_t>(texture.height), 0);
        arrayDesc.flags = cudaArrayColorAttachment;
        arrayDesc.numLevels = 1;
 
        cudaResult = cudaExternalMemoryGetMappedMipmappedArray(&texture.cudaMipmappedArray, texture.cudaExternalMemory, &arrayDesc);
        if (cudaResult != cudaSuccess) {
            if (!texture.cudaInteropUnavailableLogged) {
                logVKAbstractModelStep(std::format("CUDA interop init: cudaExternalMemoryGetMappedMipmappedArray failed for model texture: {}",
                                                   cudaGetErrorString(cudaResult)));
                texture.cudaInteropUnavailableLogged = true;
            }
            destroyTextureCudaInterop(texture);
            return false;
        }
        logVKAbstractModelStep(std::format("CUDA interop init: mapped model texture CUDA mipmapped array {}x{} uchar4",
                                           texture.width, texture.height));
 
        cudaResult = cudaGetMipmappedArrayLevel(&texture.cudaArray, texture.cudaMipmappedArray, 0);
        if (cudaResult != cudaSuccess) {
            if (!texture.cudaInteropUnavailableLogged) {
                logVKAbstractModelStep(std::format("CUDA interop init: cudaGetMipmappedArrayLevel failed for model texture: {}",
                                                   cudaGetErrorString(cudaResult)));
                texture.cudaInteropUnavailableLogged = true;
            }
            destroyTextureCudaInterop(texture);
            return false;
        }
 
        texture.cudaInteropEnabled = true;
        logVKAbstractModelStep("CUDA interop init: direct CUDA-to-model-texture upload is ready");
        return true;
    }
 
    bool VKAbstractModel::transitionTextureForCudaWrite(TextureEntry &texture) const {
        if (texture.cudaImageLayout == VK_IMAGE_LAYOUT_GENERAL) {
            return true;
        }
 
        const VkImageLayout oldLayout = (texture.cudaImageLayout == VK_IMAGE_LAYOUT_UNDEFINED)
                                            ? VK_IMAGE_LAYOUT_UNDEFINED
                                            : texture.cudaImageLayout;
        VkCommandBuffer commandBuffer = beginSingleTimeCommands();
 
        VkImageMemoryBarrier barrier{};
        barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
        barrier.oldLayout = oldLayout;
        barrier.newLayout = VK_IMAGE_LAYOUT_GENERAL;
        barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.image = texture.image;
        barrier.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        barrier.subresourceRange.baseMipLevel = 0;
        barrier.subresourceRange.levelCount = 1;
        barrier.subresourceRange.baseArrayLayer = 0;
        barrier.subresourceRange.layerCount = 1;
        barrier.srcAccessMask = (oldLayout == VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL) ? VK_ACCESS_SHADER_READ_BIT : 0;
        barrier.dstAccessMask = VK_ACCESS_MEMORY_WRITE_BIT;
 
        const VkPipelineStageFlags srcStage = (oldLayout == VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL)
                                                  ? VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT
                                                  : VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT;
        vkCmdPipelineBarrier(commandBuffer, srcStage, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT,
                             0, 0, nullptr, 0, nullptr, 1, &barrier);
        endSingleTimeCommands(commandBuffer);
 
        texture.cudaImageLayout = VK_IMAGE_LAYOUT_GENERAL;
        if (!texture.cudaWriteTransitionLogged) {
            logVKAbstractModelStep("CUDA interop sync: model texture transitions to GENERAL before CUDA writes");
            texture.cudaWriteTransitionLogged = true;
        }
        return true;
    }
 
    bool VKAbstractModel::transitionTextureForShaderRead(TextureEntry &texture) const {
        if (texture.cudaImageLayout == VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL) {
            return true;
        }
 
        VkCommandBuffer commandBuffer = beginSingleTimeCommands();
        VkImageMemoryBarrier barrier{};
        barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
        barrier.oldLayout = texture.cudaImageLayout;
        barrier.newLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
        barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.image = texture.image;
        barrier.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        barrier.subresourceRange.baseMipLevel = 0;
        barrier.subresourceRange.levelCount = 1;
        barrier.subresourceRange.baseArrayLayer = 0;
        barrier.subresourceRange.layerCount = 1;
        barrier.srcAccessMask = VK_ACCESS_MEMORY_WRITE_BIT;
        barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT;
 
        vkCmdPipelineBarrier(commandBuffer, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT,
                             0, 0, nullptr, 0, nullptr, 1, &barrier);
        endSingleTimeCommands(commandBuffer);
 
        texture.cudaImageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
        if (!texture.cudaShaderTransitionLogged) {
            logVKAbstractModelStep("CUDA interop sync: model texture transitions GENERAL -> SHADER_READ_ONLY before sampling");
            texture.cudaShaderTransitionLogged = true;
        }
        return true;
    }
 
    void VKAbstractModel::recreatePrimaryTextureForCuda(TextureEntry &texture, uint32_t width, uint32_t height) {
        vkDeviceWaitIdle(windowPtr->getDevice());
        destroyTextureCudaInterop(texture);
        if (texture.view != VK_NULL_HANDLE) {
            vkDestroyImageView(windowPtr->getDevice(), texture.view, nullptr);
            texture.view = VK_NULL_HANDLE;
        }
        if (texture.image != VK_NULL_HANDLE) {
            vkDestroyImage(windowPtr->getDevice(), texture.image, nullptr);
            texture.image = VK_NULL_HANDLE;
        }
        if (texture.memory != VK_NULL_HANDLE) {
            vkFreeMemory(windowPtr->getDevice(), texture.memory, nullptr);
            texture.memory = VK_NULL_HANDLE;
        }
 
        createCudaExportableImage(width, height, texture);
        texture.view = createImageView(texture.image, VK_FORMAT_R8G8B8A8_UNORM, VK_IMAGE_ASPECT_COLOR_BIT);
 
        createDescriptorSets();
    }
 
    bool VKAbstractModel::updatePrimaryTextureCudaHost(TextureEntry &texture, const void *pixels,
                                                       uint32_t width, uint32_t height, uint32_t pitch) const {
        if (pixels == nullptr || width == 0 || height == 0) {
            return false;
        }
        const uint32_t rowBytes = width * 4U;
        if (pitch < rowBytes || texture.width != width || texture.height != height) {
            return false;
        }
        if (!ensureTextureCudaInterop(texture) || !transitionTextureForCudaWrite(texture)) {
            return false;
        }
 
        if (!texture.cudaUploadLogged) {
            logVKAbstractModelStep(std::format(
                "CUDA interop upload: copying {}x{} host RGBA pixels to optimal-tiled Vulkan model texture via cudaArray (source pitch={} bytes)",
                width, height, pitch));
            texture.cudaUploadLogged = true;
        }
 
        const cudaError_t cudaResult = cudaMemcpy2DToArray(
            texture.cudaArray, 0, 0, pixels, pitch,
            static_cast<size_t>(rowBytes), static_cast<size_t>(height),
            cudaMemcpyHostToDevice);
        if (cudaResult != cudaSuccess) {
            logVKAbstractModelStep(std::format("CUDA interop model host texture copy failed: {}", cudaGetErrorString(cudaResult)));
            return false;
        }
 
        return transitionTextureForShaderRead(texture);
    }
 
    bool VKAbstractModel::updatePrimaryTextureCuda(const cv::cuda::GpuMat &rgba, cv::cuda::Stream &stream) {
        if (windowPtr == nullptr || windowPtr->getDevice() == VK_NULL_HANDLE) {
            return false;
        }
        if (rgba.empty() || rgba.type() != CV_8UC4 || rgba.cols <= 0 || rgba.rows <= 0) {
            return false;
        }
 
        if (textures.empty()) {
            textures.push_back(TextureEntry{});
        }
 
        TextureEntry &texture = textures[0];
        const uint32_t uploadWidth = static_cast<uint32_t>(rgba.cols);
        const uint32_t uploadHeight = static_cast<uint32_t>(rgba.rows);
        if (texture.image == VK_NULL_HANDLE || texture.memory == VK_NULL_HANDLE ||
            texture.view == VK_NULL_HANDLE || texture.width != uploadWidth ||
            texture.height != uploadHeight || texture.cudaExportMemorySize == 0) {
            try {
                recreatePrimaryTextureForCuda(texture, uploadWidth, uploadHeight);
            } catch (const std::exception &ex) {
                if (!texture.cudaInteropUnavailableLogged) {
                    logVKAbstractModelStep(std::format("CUDA exportable model texture unavailable: {}; CPU staging fallback remains active", ex.what()));
                    texture.cudaInteropUnavailableLogged = true;
                }
                return false;
            }
        }
 
        if (!ensureTextureCudaInterop(texture) || !transitionTextureForCudaWrite(texture)) {
            return false;
        }
 
        cudaStream_t cudaStream = cuda_stream_handle(stream);
        if (!texture.cudaUploadLogged) {
            logVKAbstractModelStep(std::format(
                "CUDA interop upload: copying {}x{} RGBA GpuMat to optimal-tiled Vulkan model texture via cudaArray (source pitch={} bytes, copy row bytes={})",
                rgba.cols, rgba.rows,
                static_cast<unsigned long long>(rgba.step),
                static_cast<unsigned long long>(static_cast<size_t>(rgba.cols) * 4U)));
            texture.cudaUploadLogged = true;
        }
 
        cudaError_t cudaResult = cudaMemcpy2DToArrayAsync(
            texture.cudaArray, 0, 0, rgba.ptr(), rgba.step,
            static_cast<size_t>(rgba.cols) * 4U, static_cast<size_t>(rgba.rows),
            cudaMemcpyDeviceToDevice, cudaStream);
        if (cudaResult != cudaSuccess) {
            logVKAbstractModelStep(std::format("CUDA interop model texture copy failed: {}", cudaGetErrorString(cudaResult)));
            return false;
        }
 
        cudaResult = cudaStreamSynchronize(cudaStream);
        if (cudaResult != cudaSuccess) {
            logVKAbstractModelStep(std::format("CUDA interop model texture sync failed: {}", cudaGetErrorString(cudaResult)));
            return false;
        }
 
        return transitionTextureForShaderRead(texture);
    }
#endif
 
    VkImageView VKAbstractModel::createImageView(VkImage image, VkFormat format, VkImageAspectFlags aspectFlags) const {
        VkImageViewCreateInfo viewInfo{};
        viewInfo.sType = VK_STRUCTURE_TYPE_IMAGE_VIEW_CREATE_INFO;
        viewInfo.image = image;
        viewInfo.viewType = VK_IMAGE_VIEW_TYPE_2D;
        viewInfo.format = format;
        viewInfo.subresourceRange.aspectMask = aspectFlags;
        viewInfo.subresourceRange.baseMipLevel = 0;
        viewInfo.subresourceRange.levelCount = 1;
        viewInfo.subresourceRange.baseArrayLayer = 0;
        viewInfo.subresourceRange.layerCount = 1;
 
        VkImageView imageView = VK_NULL_HANDLE;
        if (vkCreateImageView(windowPtr->getDevice(), &viewInfo, nullptr, &imageView) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to create image view");
        }
        return imageView;
    }
 
    void VKAbstractModel::transitionImageLayout(VkImage image, VkFormat, VkImageLayout oldLayout, VkImageLayout newLayout) const {
        VkCommandBuffer cmd = beginSingleTimeCommands();
 
        VkImageMemoryBarrier barrier{};
        barrier.sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER;
        barrier.oldLayout = oldLayout;
        barrier.newLayout = newLayout;
        barrier.srcQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.dstQueueFamilyIndex = VK_QUEUE_FAMILY_IGNORED;
        barrier.image = image;
        barrier.subresourceRange.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        barrier.subresourceRange.baseMipLevel = 0;
        barrier.subresourceRange.levelCount = 1;
        barrier.subresourceRange.baseArrayLayer = 0;
        barrier.subresourceRange.layerCount = 1;
 
        VkPipelineStageFlags sourceStage = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT;
        VkPipelineStageFlags destinationStage = VK_PIPELINE_STAGE_TRANSFER_BIT;
 
        if (oldLayout == VK_IMAGE_LAYOUT_UNDEFINED && newLayout == VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL) {
            barrier.srcAccessMask = 0;
            barrier.dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
            sourceStage = VK_PIPELINE_STAGE_TOP_OF_PIPE_BIT;
            destinationStage = VK_PIPELINE_STAGE_TRANSFER_BIT;
        } else if (oldLayout == VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL && newLayout == VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL) {
            barrier.srcAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
            barrier.dstAccessMask = VK_ACCESS_SHADER_READ_BIT;
            sourceStage = VK_PIPELINE_STAGE_TRANSFER_BIT;
            destinationStage = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
        } else if (oldLayout == VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL && newLayout == VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL) {
            barrier.srcAccessMask = VK_ACCESS_SHADER_READ_BIT;
            barrier.dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
            sourceStage = VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT;
            destinationStage = VK_PIPELINE_STAGE_TRANSFER_BIT;
        } else if (oldLayout == VK_IMAGE_LAYOUT_GENERAL && newLayout == VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL) {
            barrier.srcAccessMask = VK_ACCESS_MEMORY_WRITE_BIT;
            barrier.dstAccessMask = VK_ACCESS_TRANSFER_WRITE_BIT;
            sourceStage = VK_PIPELINE_STAGE_ALL_COMMANDS_BIT;
            destinationStage = VK_PIPELINE_STAGE_TRANSFER_BIT;
        }
 
        vkCmdPipelineBarrier(cmd,
                             sourceStage,
                             destinationStage,
                             0,
                             0, nullptr,
                             0, nullptr,
                             1, &barrier);
 
        endSingleTimeCommands(cmd);
    }
 
    void VKAbstractModel::copyBufferToImage(VkBuffer buffer, VkImage image, uint32_t width, uint32_t height) const {
        VkCommandBuffer cmd = beginSingleTimeCommands();
 
        VkBufferImageCopy region{};
        region.bufferOffset = 0;
        region.bufferRowLength = 0;
        region.bufferImageHeight = 0;
        region.imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
        region.imageSubresource.mipLevel = 0;
        region.imageSubresource.baseArrayLayer = 0;
        region.imageSubresource.layerCount = 1;
        region.imageOffset = {0, 0, 0};
        region.imageExtent = {width, height, 1};
 
        vkCmdCopyBufferToImage(cmd, buffer, image, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &region);
        endSingleTimeCommands(cmd);
    }
 
    void VKAbstractModel::createTextureSampler() {
        if (textureSampler != VK_NULL_HANDLE) {
            return;
        }
 
        VkPhysicalDeviceFeatures deviceFeatures{};
        vkGetPhysicalDeviceFeatures(windowPtr->getPhysicalDevice(), &deviceFeatures);
        VkPhysicalDeviceProperties deviceProperties{};
        vkGetPhysicalDeviceProperties(windowPtr->getPhysicalDevice(), &deviceProperties);
        const bool anisotropySupported = deviceFeatures.samplerAnisotropy == VK_TRUE;
        const float anisotropyLevel = anisotropySupported
                                          ? std::min(8.0f, deviceProperties.limits.maxSamplerAnisotropy)
                                          : 1.0f;
 
        VkSamplerCreateInfo samplerInfo{};
        samplerInfo.sType = VK_STRUCTURE_TYPE_SAMPLER_CREATE_INFO;
        samplerInfo.magFilter = VK_FILTER_LINEAR;
        samplerInfo.minFilter = VK_FILTER_LINEAR;
        samplerInfo.addressModeU = VK_SAMPLER_ADDRESS_MODE_REPEAT;
        samplerInfo.addressModeV = VK_SAMPLER_ADDRESS_MODE_REPEAT;
        samplerInfo.addressModeW = VK_SAMPLER_ADDRESS_MODE_REPEAT;
        samplerInfo.anisotropyEnable = anisotropySupported ? VK_TRUE : VK_FALSE;
        samplerInfo.maxAnisotropy = anisotropyLevel;
        samplerInfo.borderColor = VK_BORDER_COLOR_INT_OPAQUE_BLACK;
        samplerInfo.unnormalizedCoordinates = VK_FALSE;
        samplerInfo.compareEnable = VK_FALSE;
        samplerInfo.compareOp = VK_COMPARE_OP_ALWAYS;
        samplerInfo.mipmapMode = VK_SAMPLER_MIPMAP_MODE_LINEAR;
 
        if (vkCreateSampler(windowPtr->getDevice(), &samplerInfo, nullptr, &textureSampler) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to create texture sampler");
        }
    }
 
    void VKAbstractModel::createDescriptorSetLayout() {
        if (descriptorSetLayout != VK_NULL_HANDLE) {
            return;
        }
 
        VkDescriptorSetLayoutBinding samplerBinding{};
        samplerBinding.binding = 0;
        samplerBinding.descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
        samplerBinding.descriptorCount = 1;
        samplerBinding.stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT;
 
        VkDescriptorSetLayoutBinding fragmentBinding{};
        fragmentBinding.binding = 1;
        fragmentBinding.descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER;
        fragmentBinding.descriptorCount = 1;
        fragmentBinding.stageFlags = extendedFragmentUniformsEnabled ? VK_SHADER_STAGE_FRAGMENT_BIT : VK_SHADER_STAGE_VERTEX_BIT | VK_SHADER_STAGE_FRAGMENT_BIT;
 
        VkDescriptorSetLayoutBinding modelBinding{};
        modelBinding.binding = 2;
        modelBinding.descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER;
        modelBinding.descriptorCount = 1;
        modelBinding.stageFlags = VK_SHADER_STAGE_VERTEX_BIT;
 
        const std::array<VkDescriptorSetLayoutBinding, 3> bindings = {samplerBinding, fragmentBinding, modelBinding};
 
        VkDescriptorSetLayoutCreateInfo layoutInfo{};
        layoutInfo.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO;
        layoutInfo.bindingCount = extendedFragmentUniformsEnabled ? static_cast<uint32_t>(bindings.size()) : 2U;
        layoutInfo.pBindings = bindings.data();
 
        if (vkCreateDescriptorSetLayout(windowPtr->getDevice(), &layoutInfo, nullptr, &descriptorSetLayout) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to create descriptor set layout");
        }
    }
 
    void VKAbstractModel::createUniformBuffers() {
        destroyUniformBuffers();
 
        const size_t frameCount = windowPtr->getSwapchainImageCount();
        if (frameCount == 0) {
            return;
        }
 
        uniformBuffers.resize(frameCount, VK_NULL_HANDLE);
        uniformBufferMemory.resize(frameCount, VK_NULL_HANDLE);
        uniformBuffersMapped.resize(frameCount, nullptr);
        if (extendedFragmentUniformsEnabled) {
            fragmentUniformBuffers.resize(frameCount, VK_NULL_HANDLE);
            fragmentUniformBufferMemory.resize(frameCount, VK_NULL_HANDLE);
            fragmentUniformBuffersMapped.resize(frameCount, nullptr);
        }
 
        for (size_t i = 0; i < frameCount; ++i) {
            createBuffer(sizeof(UniformBufferObject),
                         VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT,
                         VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                         uniformBuffers[i], uniformBufferMemory[i]);
            vkMapMemory(windowPtr->getDevice(), uniformBufferMemory[i], 0, sizeof(UniformBufferObject), 0, &uniformBuffersMapped[i]);
            if (extendedFragmentUniformsEnabled) {
                createBuffer(sizeof(ModelFragmentUniforms),
                             VK_BUFFER_USAGE_UNIFORM_BUFFER_BIT,
                             VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                             fragmentUniformBuffers[i], fragmentUniformBufferMemory[i]);
                vkMapMemory(windowPtr->getDevice(), fragmentUniformBufferMemory[i], 0, sizeof(ModelFragmentUniforms), 0, &fragmentUniformBuffersMapped[i]);
            }
        }
    }
 
    void VKAbstractModel::destroyUniformBuffers() {
        if (windowPtr == nullptr || windowPtr->getDevice() == VK_NULL_HANDLE) {
            uniformBuffers.clear();
            uniformBufferMemory.clear();
            uniformBuffersMapped.clear();
            fragmentUniformBuffers.clear();
            fragmentUniformBufferMemory.clear();
            fragmentUniformBuffersMapped.clear();
            return;
        }
 
        for (size_t i = 0; i < uniformBuffers.size(); ++i) {
            if (uniformBuffersMapped[i] != nullptr) {
                vkUnmapMemory(windowPtr->getDevice(), uniformBufferMemory[i]);
                uniformBuffersMapped[i] = nullptr;
            }
            if (uniformBuffers[i] != VK_NULL_HANDLE) {
                vkDestroyBuffer(windowPtr->getDevice(), uniformBuffers[i], nullptr);
            }
            if (uniformBufferMemory[i] != VK_NULL_HANDLE) {
                vkFreeMemory(windowPtr->getDevice(), uniformBufferMemory[i], nullptr);
            }
        }
 
        uniformBuffers.clear();
        uniformBufferMemory.clear();
        uniformBuffersMapped.clear();
 
        for (size_t i = 0; i < fragmentUniformBuffers.size(); ++i) {
            if (fragmentUniformBuffersMapped[i] != nullptr) {
                vkUnmapMemory(windowPtr->getDevice(), fragmentUniformBufferMemory[i]);
            }
            if (fragmentUniformBuffers[i] != VK_NULL_HANDLE) {
                vkDestroyBuffer(windowPtr->getDevice(), fragmentUniformBuffers[i], nullptr);
            }
            if (fragmentUniformBufferMemory[i] != VK_NULL_HANDLE) {
                vkFreeMemory(windowPtr->getDevice(), fragmentUniformBufferMemory[i], nullptr);
            }
        }
        fragmentUniformBuffers.clear();
        fragmentUniformBufferMemory.clear();
        fragmentUniformBuffersMapped.clear();
    }
 
    void VKAbstractModel::createDescriptorPool() {
        const uint32_t textureCount = std::max<uint32_t>(1U, static_cast<uint32_t>(textures.size()));
        const uint32_t frameCount = static_cast<uint32_t>(windowPtr->getSwapchainImageCount());
        const uint32_t requiredSetCount = textureCount * frameCount;
        const uint32_t setCount = std::max(requiredSetCount, descriptorPoolSetCapacity);
 
        std::array<VkDescriptorPoolSize, 2> poolSizes{};
        poolSizes[0].type = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
        poolSizes[0].descriptorCount = setCount;
        poolSizes[1].type = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER;
        poolSizes[1].descriptorCount = extendedFragmentUniformsEnabled ? setCount * 2U : setCount;
 
        VkDescriptorPoolCreateInfo poolInfo{};
        poolInfo.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO;
        poolInfo.poolSizeCount = static_cast<uint32_t>(poolSizes.size());
        poolInfo.pPoolSizes = poolSizes.data();
        poolInfo.maxSets = setCount;
        poolInfo.flags = VK_DESCRIPTOR_POOL_CREATE_FREE_DESCRIPTOR_SET_BIT;
 
        if (vkCreateDescriptorPool(windowPtr->getDevice(), &poolInfo, nullptr, &descriptorPool) != VK_SUCCESS) {
            throw mxvk::Exception("VKAbstractModel failed to create descriptor pool");
        }
        descriptorPoolSetCapacity = setCount;
    }
 
    void VKAbstractModel::createDescriptorSets() {
        const size_t textureCount = std::max<size_t>(1, textures.size());
        const size_t frameCount = windowPtr->getSwapchainImageCount();
        const size_t setCount = textureCount * frameCount;
 
        if (descriptorSetLayout == VK_NULL_HANDLE || frameCount == 0 || uniformBuffers.size() < frameCount || textures.empty() ||
            (extendedFragmentUniformsEnabled && fragmentUniformBuffers.size() < frameCount)) {
            return;
        }
 
        if (descriptorPool == VK_NULL_HANDLE || descriptorPoolSetCapacity < setCount) {
            descriptorSets.clear();
            if (descriptorPool != VK_NULL_HANDLE) {
                vkDestroyDescriptorPool(windowPtr->getDevice(), descriptorPool, nullptr);
                descriptorPool = VK_NULL_HANDLE;
                descriptorPoolSetCapacity = 0;
            }
            createDescriptorPool();
        }
 
        const bool needsAllocation = descriptorSets.size() != setCount ||
                                     std::any_of(descriptorSets.begin(), descriptorSets.end(), [](VkDescriptorSet set) {
                                         return set == VK_NULL_HANDLE;
                                     });
 
        if (needsAllocation) {
            std::vector<VkDescriptorSetLayout> layouts(setCount, descriptorSetLayout);
 
            VkDescriptorSetAllocateInfo allocInfo{};
            allocInfo.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO;
            allocInfo.descriptorPool = descriptorPool;
            allocInfo.descriptorSetCount = static_cast<uint32_t>(setCount);
            allocInfo.pSetLayouts = layouts.data();
 
            descriptorSets.assign(setCount, VK_NULL_HANDLE);
            const VkResult allocateResult = vkAllocateDescriptorSets(windowPtr->getDevice(), &allocInfo, descriptorSets.data());
            if (allocateResult == VK_ERROR_OUT_OF_POOL_MEMORY || allocateResult == VK_ERROR_FRAGMENTED_POOL) {
                vkDestroyDescriptorPool(windowPtr->getDevice(), descriptorPool, nullptr);
                descriptorPool = VK_NULL_HANDLE;
                descriptorPoolSetCapacity = static_cast<uint32_t>(std::max<size_t>(setCount * 2U, 1U));
                descriptorSets.clear();
                createDescriptorPool();
                allocInfo.descriptorPool = descriptorPool;
                descriptorSets.assign(setCount, VK_NULL_HANDLE);
                if (vkAllocateDescriptorSets(windowPtr->getDevice(), &allocInfo, descriptorSets.data()) != VK_SUCCESS) {
                    throw mxvk::Exception("VKAbstractModel failed to allocate descriptor sets");
                }
            } else if (allocateResult != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to allocate descriptor sets");
            }
        }
 
        for (size_t frame = 0; frame < frameCount; ++frame) {
            VkDescriptorBufferInfo bufferInfo{};
            bufferInfo.buffer = uniformBuffers[frame];
            bufferInfo.offset = 0;
            bufferInfo.range = sizeof(UniformBufferObject);
            VkDescriptorBufferInfo fragmentBufferInfo{};
            if (extendedFragmentUniformsEnabled) {
                fragmentBufferInfo.buffer = fragmentUniformBuffers[frame];
                fragmentBufferInfo.offset = 0;
                fragmentBufferInfo.range = sizeof(ModelFragmentUniforms);
            }
 
            for (size_t tex = 0; tex < textureCount; ++tex) {
                const size_t setIndex = frame * textureCount + tex;
                const TextureEntry &entry = textures[tex];
 
                VkDescriptorImageInfo imageInfo{};
                imageInfo.imageLayout = VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL;
                imageInfo.imageView = entry.view;
                imageInfo.sampler = textureSampler;
 
                std::array<VkWriteDescriptorSet, 3> writes{};
                writes[0].sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET;
                writes[0].dstSet = descriptorSets[setIndex];
                writes[0].dstBinding = 0;
                writes[0].descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
                writes[0].descriptorCount = 1;
                writes[0].pImageInfo = &imageInfo;
 
                writes[1].sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET;
                writes[1].dstSet = descriptorSets[setIndex];
                writes[1].dstBinding = 1;
                writes[1].descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER;
                writes[1].descriptorCount = 1;
                writes[1].pBufferInfo = extendedFragmentUniformsEnabled ? &fragmentBufferInfo : &bufferInfo;
 
                if (extendedFragmentUniformsEnabled) {
                    writes[2].sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET;
                    writes[2].dstSet = descriptorSets[setIndex];
                    writes[2].dstBinding = 2;
                    writes[2].descriptorType = VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER;
                    writes[2].descriptorCount = 1;
                    writes[2].pBufferInfo = &bufferInfo;
                }
 
                const uint32_t writeCount = extendedFragmentUniformsEnabled ? static_cast<uint32_t>(writes.size()) : 2U;
                vkUpdateDescriptorSets(windowPtr->getDevice(), writeCount, writes.data(), 0, nullptr);
            }
        }
    }
 
    void VKAbstractModel::createPipelines() {
        destroyPipelines();
 
        if (windowPtr == nullptr || windowPtr->getDevice() == VK_NULL_HANDLE) {
            return;
        }
        if (descriptorSetLayout == VK_NULL_HANDLE) {
            return;
        }
        if (vertexShaderPath.empty() || fragmentShaderPath.empty()) {
            return;
        }
        if (windowPtr->getSwapchainFormat() == VK_FORMAT_UNDEFINED) {
            return;
        }
 
        const std::vector<char> vertBytes = mxvk::load_spv(vertexShaderPath);
        const std::vector<char> fragBytes = mxvk::load_spv(fragmentShaderPath);
 
        const VkShaderModule vertModule = mxvk::create_shader_module(windowPtr->getDevice(), vertBytes);
        VkShaderModule fragModule = VK_NULL_HANDLE;
 
        try {
            fragModule = mxvk::create_shader_module(windowPtr->getDevice(), fragBytes);
 
            VkPipelineShaderStageCreateInfo vertStage{};
            vertStage.sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
            vertStage.stage = VK_SHADER_STAGE_VERTEX_BIT;
            vertStage.module = vertModule;
            vertStage.pName = "main";
 
            VkPipelineShaderStageCreateInfo fragStage{};
            fragStage.sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
            fragStage.stage = VK_SHADER_STAGE_FRAGMENT_BIT;
            fragStage.module = fragModule;
            fragStage.pName = "main";
 
            const std::array<VkPipelineShaderStageCreateInfo, 2> stages = {vertStage, fragStage};
 
            VkVertexInputBindingDescription binding{};
            binding.binding = 0;
            binding.stride = sizeof(VKVertex);
            binding.inputRate = VK_VERTEX_INPUT_RATE_VERTEX;
 
            std::array<VkVertexInputAttributeDescription, 3> attrs{};
            attrs[0].binding = 0;
            attrs[0].location = 0;
            attrs[0].format = VK_FORMAT_R32G32B32_SFLOAT;
            attrs[0].offset = offsetof(VKVertex, pos);
            attrs[1].binding = 0;
            attrs[1].location = 1;
            attrs[1].format = VK_FORMAT_R32G32_SFLOAT;
            attrs[1].offset = offsetof(VKVertex, texCoord);
            attrs[2].binding = 0;
            attrs[2].location = 2;
            attrs[2].format = VK_FORMAT_R32G32B32_SFLOAT;
            attrs[2].offset = offsetof(VKVertex, normal);
 
            VkPipelineVertexInputStateCreateInfo vertexInput{};
            vertexInput.sType = VK_STRUCTURE_TYPE_PIPELINE_VERTEX_INPUT_STATE_CREATE_INFO;
            vertexInput.vertexBindingDescriptionCount = 1;
            vertexInput.pVertexBindingDescriptions = &binding;
            vertexInput.vertexAttributeDescriptionCount = static_cast<uint32_t>(attrs.size());
            vertexInput.pVertexAttributeDescriptions = attrs.data();
 
            VkPipelineInputAssemblyStateCreateInfo inputAssembly{};
            inputAssembly.sType = VK_STRUCTURE_TYPE_PIPELINE_INPUT_ASSEMBLY_STATE_CREATE_INFO;
            inputAssembly.topology = VK_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST;
            inputAssembly.primitiveRestartEnable = VK_FALSE;
 
            const std::array<VkDynamicState, 2> dynamicStates = {
                VK_DYNAMIC_STATE_VIEWPORT,
                VK_DYNAMIC_STATE_SCISSOR,
            };
            VkPipelineDynamicStateCreateInfo dynamicInfo{};
            dynamicInfo.sType = VK_STRUCTURE_TYPE_PIPELINE_DYNAMIC_STATE_CREATE_INFO;
            dynamicInfo.dynamicStateCount = static_cast<uint32_t>(dynamicStates.size());
            dynamicInfo.pDynamicStates = dynamicStates.data();
 
            VkPipelineViewportStateCreateInfo viewportState{};
            viewportState.sType = VK_STRUCTURE_TYPE_PIPELINE_VIEWPORT_STATE_CREATE_INFO;
            viewportState.viewportCount = 1;
            viewportState.scissorCount = 1;
 
            VkPipelineRasterizationStateCreateInfo rasterizer{};
            rasterizer.sType = VK_STRUCTURE_TYPE_PIPELINE_RASTERIZATION_STATE_CREATE_INFO;
            rasterizer.depthClampEnable = VK_FALSE;
            rasterizer.rasterizerDiscardEnable = VK_FALSE;
            rasterizer.polygonMode = VK_POLYGON_MODE_FILL;
            rasterizer.cullMode = backfaceCullingEnabled ? VK_CULL_MODE_BACK_BIT : VK_CULL_MODE_NONE;
            rasterizer.frontFace = VK_FRONT_FACE_CLOCKWISE;
            rasterizer.depthBiasEnable = VK_FALSE;
            rasterizer.lineWidth = 1.0f;
 
            VkPipelineMultisampleStateCreateInfo multisample{};
            multisample.sType = VK_STRUCTURE_TYPE_PIPELINE_MULTISAMPLE_STATE_CREATE_INFO;
            multisample.rasterizationSamples = VK_SAMPLE_COUNT_1_BIT;
            multisample.sampleShadingEnable = VK_FALSE;
 
            VkPipelineDepthStencilStateCreateInfo depthStencil{};
            depthStencil.sType = VK_STRUCTURE_TYPE_PIPELINE_DEPTH_STENCIL_STATE_CREATE_INFO;
            depthStencil.depthTestEnable = VK_TRUE;
            depthStencil.depthWriteEnable = alphaBlendingEnabled ? VK_FALSE : VK_TRUE;
            depthStencil.depthCompareOp = VK_COMPARE_OP_LESS;
 
            VkPipelineColorBlendAttachmentState blendAttachment{};
            blendAttachment.colorWriteMask =
                VK_COLOR_COMPONENT_R_BIT |
                VK_COLOR_COMPONENT_G_BIT |
                VK_COLOR_COMPONENT_B_BIT |
                VK_COLOR_COMPONENT_A_BIT;
            blendAttachment.blendEnable = alphaBlendingEnabled ? VK_TRUE : VK_FALSE;
            blendAttachment.srcColorBlendFactor = VK_BLEND_FACTOR_SRC_ALPHA;
            blendAttachment.dstColorBlendFactor = VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA;
            blendAttachment.colorBlendOp = VK_BLEND_OP_ADD;
            blendAttachment.srcAlphaBlendFactor = VK_BLEND_FACTOR_ONE;
            blendAttachment.dstAlphaBlendFactor = VK_BLEND_FACTOR_ONE_MINUS_SRC_ALPHA;
            blendAttachment.alphaBlendOp = VK_BLEND_OP_ADD;
 
            VkPipelineColorBlendStateCreateInfo colorBlend{};
            colorBlend.sType = VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO;
            colorBlend.logicOpEnable = VK_FALSE;
            colorBlend.attachmentCount = 1;
            colorBlend.pAttachments = &blendAttachment;
 
            VkPipelineLayoutCreateInfo layoutInfo{};
            layoutInfo.sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO;
            layoutInfo.setLayoutCount = 1;
            layoutInfo.pSetLayouts = &descriptorSetLayout;
            const std::array<VkPushConstantRange, 2> pushConstantRanges = {
                VkPushConstantRange{
                    .stageFlags = VK_SHADER_STAGE_VERTEX_BIT,
                    .offset = 0,
                    .size = sizeof(ModelPushConstants),
                },
                VkPushConstantRange{
                    .stageFlags = VK_SHADER_STAGE_FRAGMENT_BIT,
                    .offset = 0,
                    .size = sizeof(ModelFragmentPushConstants),
                },
            };
            layoutInfo.pushConstantRangeCount = extendedFragmentUniformsEnabled ? static_cast<uint32_t>(pushConstantRanges.size()) : 1U;
            layoutInfo.pPushConstantRanges = pushConstantRanges.data();
 
            if (vkCreatePipelineLayout(windowPtr->getDevice(), &layoutInfo, nullptr, &pipelineLayout) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to create pipeline layout");
            }
 
            const VkFormat colorFormat = windowPtr->getSwapchainFormat();
            const VkFormat depthFormat = windowPtr->getDepthFormat();
            VkPipelineRenderingCreateInfo renderingInfo{};
            renderingInfo.sType = VK_STRUCTURE_TYPE_PIPELINE_RENDERING_CREATE_INFO;
            renderingInfo.colorAttachmentCount = 1;
            renderingInfo.pColorAttachmentFormats = &colorFormat;
            if (depthFormat != VK_FORMAT_UNDEFINED) {
                renderingInfo.depthAttachmentFormat = depthFormat;
            }
 
            VkGraphicsPipelineCreateInfo pipelineInfo{};
            pipelineInfo.sType = VK_STRUCTURE_TYPE_GRAPHICS_PIPELINE_CREATE_INFO;
            pipelineInfo.pNext = &renderingInfo;
            pipelineInfo.stageCount = static_cast<uint32_t>(stages.size());
            pipelineInfo.pStages = stages.data();
            pipelineInfo.pVertexInputState = &vertexInput;
            pipelineInfo.pInputAssemblyState = &inputAssembly;
            pipelineInfo.pViewportState = &viewportState;
            pipelineInfo.pRasterizationState = &rasterizer;
            pipelineInfo.pMultisampleState = &multisample;
            pipelineInfo.pDepthStencilState = &depthStencil;
            pipelineInfo.pColorBlendState = &colorBlend;
            pipelineInfo.pDynamicState = &dynamicInfo;
            pipelineInfo.layout = pipelineLayout;
            pipelineInfo.renderPass = VK_NULL_HANDLE;
            pipelineInfo.subpass = 0;
 
            if (vkCreateGraphicsPipelines(windowPtr->getDevice(), windowPtr->getPipelineCache(), 1, &pipelineInfo, nullptr, &pipelineFill) != VK_SUCCESS) {
                throw mxvk::Exception("VKAbstractModel failed to create fill pipeline");
            }
 
            // Keep wireframe pipeline disabled by default. The examples render with
            // filled geometry, and creating a line-mode pipeline requires matching
            // logical-device feature enablement (fillModeNonSolid).
            pipelineWireframe = VK_NULL_HANDLE;
        } catch (...) {
            if (fragModule != VK_NULL_HANDLE) {
                vkDestroyShaderModule(windowPtr->getDevice(), fragModule, nullptr);
            }
            vkDestroyShaderModule(windowPtr->getDevice(), vertModule, nullptr);
            throw;
        }
 
        vkDestroyShaderModule(windowPtr->getDevice(), fragModule, nullptr);
        vkDestroyShaderModule(windowPtr->getDevice(), vertModule, nullptr);
    }
 
    void VKAbstractModel::destroyPipelines() {
        if (windowPtr == nullptr || windowPtr->getDevice() == VK_NULL_HANDLE) {
            pipelineFill = VK_NULL_HANDLE;
            pipelineWireframe = VK_NULL_HANDLE;
            pipelineLayout = VK_NULL_HANDLE;
            return;
        }
 
        if (pipelineFill != VK_NULL_HANDLE) {
            logVKAbstractModelStep("destroying fill pipeline");
            vkDestroyPipeline(windowPtr->getDevice(), pipelineFill, nullptr);
            pipelineFill = VK_NULL_HANDLE;
        }
        if (pipelineWireframe != VK_NULL_HANDLE) {
            logVKAbstractModelStep("destroying wireframe pipeline");
            vkDestroyPipeline(windowPtr->getDevice(), pipelineWireframe, nullptr);
            pipelineWireframe = VK_NULL_HANDLE;
        }
        if (pipelineLayout != VK_NULL_HANDLE) {
            logVKAbstractModelStep("destroying pipeline layout");
            vkDestroyPipelineLayout(windowPtr->getDevice(), pipelineLayout, nullptr);
            pipelineLayout = VK_NULL_HANDLE;
        }
    }
 
    void VKAbstractModel::destroyDescriptors() {
        if (windowPtr == nullptr || windowPtr->getDevice() == VK_NULL_HANDLE) {
            descriptorSets.clear();
            descriptorPool = VK_NULL_HANDLE;
            descriptorSetLayout = VK_NULL_HANDLE;
            destroyUniformBuffers();
            return;
        }
 
        descriptorSets.clear();
        if (descriptorPool != VK_NULL_HANDLE) {
            logVKAbstractModelStep("destroying descriptor pool");
            vkDestroyDescriptorPool(windowPtr->getDevice(), descriptorPool, nullptr);
            descriptorPool = VK_NULL_HANDLE;
        }
        if (descriptorSetLayout != VK_NULL_HANDLE) {
            logVKAbstractModelStep("destroying descriptor set layout");
            vkDestroyDescriptorSetLayout(windowPtr->getDevice(), descriptorSetLayout, nullptr);
            descriptorSetLayout = VK_NULL_HANDLE;
        }
 
        destroyUniformBuffers();
    }
 
    void VKAbstractModel::destroyTextures() {
        if (windowPtr == nullptr || windowPtr->getDevice() == VK_NULL_HANDLE) {
            textures.clear();
            textureSampler = VK_NULL_HANDLE;
            return;
        }
 
        for (TextureEntry &tex : textures) {
#ifdef MXVK_CUDA
            destroyTextureCudaInterop(tex);
#endif
            if (tex.view != VK_NULL_HANDLE) {
                logVKAbstractModelStep("destroying texture image view");
                vkDestroyImageView(windowPtr->getDevice(), tex.view, nullptr);
            }
            if (tex.image != VK_NULL_HANDLE) {
                logVKAbstractModelStep("destroying texture image");
                vkDestroyImage(windowPtr->getDevice(), tex.image, nullptr);
            }
            if (tex.memory != VK_NULL_HANDLE) {
                logVKAbstractModelStep("freeing texture memory");
                vkFreeMemory(windowPtr->getDevice(), tex.memory, nullptr);
            }
        }
        textures.clear();
 
        if (textureSampler != VK_NULL_HANDLE) {
            logVKAbstractModelStep("destroying texture sampler");
            vkDestroySampler(windowPtr->getDevice(), textureSampler, nullptr);
            textureSampler = VK_NULL_HANDLE;
        }
    }
 
} // namespace mxvk