mxvk::MXModel Class Reference

Loads OBJ/MXMOD meshes and uploads them to Vulkan buffers. More...

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

Public Member Functions
void	cleanup (VkDevice device)
	Release owned GPU buffers.
void	compressIndices ()
	Remove duplicate vertices and remap indices.
void	draw (VkCommandBuffer cmd) const
	Record one indexed draw for the full mesh.
void	drawSubMesh (VkCommandBuffer cmd, size_t index) const
	Record one indexed draw for a sub-mesh.
void	exportOBJ (const std::string &objPath, const std::string &mtlPath="") const
	Export the loaded model as Wavefront OBJ plus MTL.
VkBuffer	indexBuffer () const
uint32_t	indexCount () const
const std::vector< uint32_t > &	indices () const
void	load (const std::string &path, const std::string &textureManifestPath, const std::string &textureBasePath, float positionScale=1.0f)
	Parse model data and an optional texture manifest from disk.
void	load (const std::string &path, float positionScale=1.0f)
	Parse model data from disk into CPU-side arrays.
const std::vector< MXMaterial > &	materials () const
const std::string &	mtlLibPath () const
	MXModel ()=default
	MXModel (const MXModel &)=delete
	MXModel (MXModel &&other) noexcept
MXModel &	operator= (const MXModel &)=delete
MXModel &	operator= (MXModel &&other) noexcept
const SubMesh &	subMesh (size_t i) const
size_t	subMeshCount () const
const std::vector< SubMesh > &	subMeshes () const
void	upload (VkDevice device, VkPhysicalDevice physicalDevice, VkCommandPool commandPool, VkQueue graphicsQueue)
	Upload parsed geometry to device-local GPU buffers.
VkBuffer	vertexBuffer () const
const std::vector< VKVertex > &	vertices () const
	~MXModel ()=default

Static Public Member Functions
static void	exportOBJ (const std::string &modelPath, const std::string &textureManifestPath, const std::string &textureBasePath, const std::string &objPath, float positionScale=1.0f)
	Load a model/manifest pair and export it as Wavefront OBJ plus MTL.

Detailed Description

Loads OBJ/MXMOD meshes and uploads them to Vulkan buffers.

Definition at line 69 of file mxvk_model.hpp.

Constructor & Destructor Documentation

MXModel() [1/3]

mxvk::MXModel::MXModel ( )

default

~MXModel()

mxvk::MXModel::~MXModel ( )

default

MXModel() [2/3]

mxvk::MXModel::MXModel ( const MXModel & )

delete

MXModel() [3/3]

mxvk::MXModel::MXModel ( MXModel && other )

noexcept

Definition at line 18 of file mxvk_model.cpp.

        : verticesData(std::move(other.verticesData)),
          indicesData(std::move(other.indicesData)),
          subMeshList(std::move(other.subMeshList)),
          materialList(std::move(other.materialList)),
          mtlLibraryPath(std::move(other.mtlLibraryPath)),
          vertexBufferHandle(other.vertexBufferHandle),
          vertexBufferMemory(other.vertexBufferMemory),
          indexBufferHandle(other.indexBufferHandle),
          indexBufferMemory(other.indexBufferMemory) {
        other.vertexBufferHandle = VK_NULL_HANDLE;
        other.vertexBufferMemory = VK_NULL_HANDLE;
        other.indexBufferHandle = VK_NULL_HANDLE;
        other.indexBufferMemory = VK_NULL_HANDLE;
    }

Member Function Documentation

cleanup()

void mxvk::MXModel::cleanup

(

VkDevice

device

)

Release owned GPU buffers.

Parameters

device

Logical Vulkan device that owns these resources.

Definition at line 1211 of file mxvk_model.cpp.

                                         {
        if (device == VK_NULL_HANDLE) {
            return;
        }
 
        const bool hadBuffers = vertexBufferHandle != VK_NULL_HANDLE || indexBufferHandle != VK_NULL_HANDLE ||
                                vertexBufferMemory != VK_NULL_HANDLE || indexBufferMemory != VK_NULL_HANDLE;
        if (hadBuffers) {
            logMXModelStep("teardown begin", true);
        }
 
        if (vertexBufferHandle != VK_NULL_HANDLE) {
            vkDestroyBuffer(device, vertexBufferHandle, nullptr);
            vertexBufferHandle = VK_NULL_HANDLE;
        }
        if (vertexBufferMemory != VK_NULL_HANDLE) {
            vkFreeMemory(device, vertexBufferMemory, nullptr);
            vertexBufferMemory = VK_NULL_HANDLE;
        }
 
        if (indexBufferHandle != VK_NULL_HANDLE) {
            vkDestroyBuffer(device, indexBufferHandle, nullptr);
            indexBufferHandle = VK_NULL_HANDLE;
        }
        if (indexBufferMemory != VK_NULL_HANDLE) {
            vkFreeMemory(device, indexBufferMemory, nullptr);
            indexBufferMemory = VK_NULL_HANDLE;
        }
 
        if (hadBuffers) {
            logMXModelStep("teardown complete", true);
        }
    }

compressIndices()

void mxvk::MXModel::compressIndices

(

)

Remove duplicate vertices and remap indices.

Definition at line 685 of file mxvk_model.cpp.

                                  {
        if (verticesData.empty() || indicesData.empty()) {
            return;
        }
 
        std::vector<VKVertex> uniqueVertices{};
        uniqueVertices.reserve(verticesData.size());
 
        std::unordered_map<VKVertex, uint32_t, VKVertexHash> vertexMap{};
        std::vector<uint32_t> remap(verticesData.size(), 0);
 
        for (size_t i = 0; i < verticesData.size(); ++i) {
            const auto it = vertexMap.find(verticesData[i]);
            if (it != vertexMap.end()) {
                remap[i] = it->second;
                continue;
            }
 
            const uint32_t nextIndex = static_cast<uint32_t>(uniqueVertices.size());
            uniqueVertices.push_back(verticesData[i]);
            vertexMap.emplace(verticesData[i], nextIndex);
            remap[i] = nextIndex;
        }
 
        for (uint32_t &idx : indicesData) {
            if (idx < static_cast<uint32_t>(remap.size())) {
                idx = remap[idx];
            }
        }
 
        verticesData = std::move(uniqueVertices);
    }

draw()

void mxvk::MXModel::draw

(

VkCommandBuffer

cmd

)

const

Record one indexed draw for the full mesh.

Parameters

cmd	Active command buffer.

Definition at line 1245 of file mxvk_model.cpp.

                                                {
        if (cmd == VK_NULL_HANDLE || vertexBufferHandle == VK_NULL_HANDLE || indexBufferHandle == VK_NULL_HANDLE || indicesData.empty()) {
            return;
        }
 
        const VkBuffer buffers[] = {vertexBufferHandle};
        const VkDeviceSize offsets[] = {0};
        vkCmdBindVertexBuffers(cmd, 0, 1, buffers, offsets);
        vkCmdBindIndexBuffer(cmd, indexBufferHandle, 0, VK_INDEX_TYPE_UINT32);
        vkCmdDrawIndexed(cmd, indexCount(), 1, 0, 0, 0);
    }

drawSubMesh()

void mxvk::MXModel::drawSubMesh	(	VkCommandBuffer	cmd,
		size_t	index ) const

Record one indexed draw for a sub-mesh.

Parameters

cmd	Active command buffer.
index	Sub-mesh index.

Definition at line 1257 of file mxvk_model.cpp.

                                                                     {
        if (cmd == VK_NULL_HANDLE || index >= subMeshList.size() ||
            vertexBufferHandle == VK_NULL_HANDLE || indexBufferHandle == VK_NULL_HANDLE) {
            return;
        }
 
        const VkBuffer buffers[] = {vertexBufferHandle};
        const VkDeviceSize offsets[] = {0};
        vkCmdBindVertexBuffers(cmd, 0, 1, buffers, offsets);
        vkCmdBindIndexBuffer(cmd, indexBufferHandle, 0, VK_INDEX_TYPE_UINT32);
 
        const SubMesh &sm = subMeshList[index];
        if (sm.indexCount == 0) {
            return;
        }
 
        vkCmdDrawIndexed(cmd, sm.indexCount, 1, sm.firstIndex, 0, 0);
    }

exportOBJ() [1/2]

void mxvk::MXModel::exportOBJ ( const std::string & modelPath, const std::string & textureManifestPath, const std::string & textureBasePath, const std::string & objPath, float positionScale = 1.0f )

static

Load a model/manifest pair and export it as Wavefront OBJ plus MTL.

Definition at line 888 of file mxvk_model.cpp.

                                                 {
        MXModel model{};
        model.load(modelPath, textureManifestPath, textureBasePath, positionScale);
        model.exportOBJ(objPath);
    }

exportOBJ() [2/2]

void mxvk::MXModel::exportOBJ	(	const std::string &	objPath,
		const std::string &	mtlPath = "" ) const

Export the loaded model as Wavefront OBJ plus MTL.

Parameters

objPath	Output .obj path.
mtlPath	Optional output .mtl path. Defaults to objPath with .mtl extension.

Definition at line 765 of file mxvk_model.cpp.

                                                                                    {
        if (objPath.empty()) {
            throw mxvk::Exception("MXModel::exportOBJ objPath is empty");
        }
        if (verticesData.empty() || indicesData.empty()) {
            throw mxvk::Exception("MXModel::exportOBJ requires loaded geometry");
        }
 
        const std::filesystem::path objOutputPath(objPath);
        const std::filesystem::path mtlOutputPath = mtlPath.empty()
                                                        ? objOutputPath.parent_path() / objOutputPath.stem().concat(".mtl")
                                                        : std::filesystem::path(mtlPath);
 
        if (!objOutputPath.parent_path().empty()) {
            std::filesystem::create_directories(objOutputPath.parent_path());
        }
        if (!mtlOutputPath.parent_path().empty()) {
            std::filesystem::create_directories(mtlOutputPath.parent_path());
        }
 
        std::ofstream objFile(objOutputPath);
        if (!objFile.is_open()) {
            throw mxvk::Exception("MXModel::exportOBJ failed to open OBJ file: " + objOutputPath.string());
        }
 
        std::ofstream mtlFile(mtlOutputPath);
        if (!mtlFile.is_open()) {
            throw mxvk::Exception("MXModel::exportOBJ failed to open MTL file: " + mtlOutputPath.string());
        }
 
        objFile << "# Exported from MXVK MXModel\n";
        objFile << "mtllib " << mtlReferencePath(objOutputPath.string(), mtlOutputPath.string()) << "\n\n";
 
        for (const VKVertex &vertex : verticesData) {
            objFile << "v " << vertex.pos[0] << ' ' << vertex.pos[1] << ' ' << vertex.pos[2] << '\n';
        }
        objFile << '\n';
 
        for (const VKVertex &vertex : verticesData) {
            objFile << "vt " << vertex.texCoord[0] << ' ' << vertex.texCoord[1] << '\n';
        }
        objFile << '\n';
 
        for (const VKVertex &vertex : verticesData) {
            objFile << "vn " << vertex.normal[0] << ' ' << vertex.normal[1] << ' ' << vertex.normal[2] << '\n';
        }
        objFile << '\n';
 
        std::vector<MXMaterial> outputMaterials = materialList;
        for (size_t i = 0; i < outputMaterials.size(); ++i) {
            if (outputMaterials[i].name.empty()) {
                outputMaterials[i].name = "material_" + std::to_string(i);
            }
        }
 
        const auto hasOutputMaterial = [&outputMaterials](const std::string &name) {
            return std::any_of(outputMaterials.begin(), outputMaterials.end(), [&name](const MXMaterial &material) {
                return material.name == name;
            });
        };
 
        const auto ensureOutputMaterial = [&outputMaterials, &hasOutputMaterial](const std::string &name) {
            if (hasOutputMaterial(name)) {
                return;
            }
            MXMaterial material{};
            material.name = name;
            outputMaterials.push_back(material);
        };
 
        if (subMeshList.empty()) {
            ensureOutputMaterial("material_0");
        } else {
            for (const SubMesh &sm : subMeshList) {
                const std::string materialName = !sm.materialName.empty()
                                                     ? sm.materialName
                                                     : materialNameForTextureIndex(sm.textureIndex, outputMaterials);
                ensureOutputMaterial(materialName);
            }
        }
 
        for (const MXMaterial &material : outputMaterials) {
            MXMaterial outputMaterial = material;
            outputMaterial.map_kd = mtlTextureReferencePath(mtlOutputPath, outputMaterial.map_kd);
            writeMTLMaterial(mtlFile, outputMaterial);
        }
 
        const auto emitFaces = [&](uint32_t firstIndex, uint32_t indexCount, const std::string &materialName) {
            if (firstIndex > indicesData.size() || indexCount > indicesData.size() - firstIndex) {
                throw mxvk::Exception("MXModel::exportOBJ submesh index range is out of bounds");
            }
            if ((indexCount % 3U) != 0U) {
                throw mxvk::Exception("MXModel::exportOBJ only triangle index ranges can be exported");
            }
 
            objFile << "usemtl " << materialName << '\n';
            for (uint32_t i = 0; i < indexCount; i += 3U) {
                objFile << "f";
                for (uint32_t j = 0; j < 3U; ++j) {
                    const uint32_t vertexIndex = indicesData[firstIndex + i + j];
                    if (vertexIndex >= static_cast<uint32_t>(verticesData.size())) {
                        throw mxvk::Exception("MXModel::exportOBJ vertex index is out of bounds");
                    }
                    const uint32_t objIndex = vertexIndex + 1U;
                    objFile << ' ' << objIndex << '/' << objIndex << '/' << objIndex;
                }
                objFile << '\n';
            }
            objFile << '\n';
        };
 
        if (subMeshList.empty()) {
            emitFaces(0, static_cast<uint32_t>(indicesData.size()), "material_0");
        } else {
            for (const SubMesh &sm : subMeshList) {
                const std::string materialName = !sm.materialName.empty()
                                                     ? sm.materialName
                                                     : materialNameForTextureIndex(sm.textureIndex, materialList);
                emitFaces(sm.firstIndex, sm.indexCount, materialName);
            }
        }
    }

indexBuffer()

VkBuffer mxvk::MXModel::indexBuffer ( ) const

inlinenodiscard

Definition at line 151 of file mxvk_model.hpp.

{ return indexBufferHandle; }

indexCount()

uint32_t mxvk::MXModel::indexCount ( ) const

inlinenodiscard

Definition at line 148 of file mxvk_model.hpp.

{ return static_cast<uint32_t>(indicesData.size()); }

indices()

const std::vector< uint32_t > & mxvk::MXModel::indices ( ) const

inlinenodiscard

Definition at line 147 of file mxvk_model.hpp.

{ return indicesData; }

load() [1/2]

void mxvk::MXModel::load	(	const std::string &	path,
		const std::string &	textureManifestPath,
		const std::string &	textureBasePath,
		float	positionScale = 1.0f )

Parse model data and an optional texture manifest from disk.

Parameters

path	Path to .obj, .mxmod, or .mxmod.z model.
textureManifestPath	Optional .txt/.tex or MTL-like texture manifest.
textureBasePath	Base path used to resolve relative texture paths.
positionScale	Uniform scale applied to positions.

Definition at line 755 of file mxvk_model.cpp.

                                            {
        load(path, positionScale);
        if (!textureManifestPath.empty()) {
            loadTextureManifest(textureManifestPath, textureBasePath);
        }
    }

load() [2/2]

void mxvk::MXModel::load	(	const std::string &	path,
		float	positionScale = 1.0f )

Parse model data from disk into CPU-side arrays.

Parameters

path	Path to .obj, .mxmod, or .mxmod.z model.
positionScale	Uniform scale applied to positions.

Definition at line 718 of file mxvk_model.cpp.

                                                                 {
        if (path.empty()) {
            throw mxvk::Exception("MXModel::load path is empty");
        }
 
        logMXModelStep("load begin: " + path, true);
 
        if (path.ends_with(".obj")) {
            loadOBJ(path, positionScale);
            logMXModelStep("load complete (.obj): vertices=" + std::to_string(verticesData.size()) +
                               ", indices=" + std::to_string(indicesData.size()) +
                               ", submeshes=" + std::to_string(subMeshList.size()),
                           true);
            return;
        }
 
        if (path.ends_with(".mxmod")) {
            loadMXMOD(path, positionScale);
            logMXModelStep("load complete (.mxmod): vertices=" + std::to_string(verticesData.size()) +
                               ", indices=" + std::to_string(indicesData.size()) +
                               ", submeshes=" + std::to_string(subMeshList.size()),
                           true);
            return;
        }
 
        if (path.ends_with(".mxmod.z")) {
            loadMXMODZ(path, positionScale);
            logMXModelStep("load complete (.mxmod.z): vertices=" + std::to_string(verticesData.size()) +
                               ", indices=" + std::to_string(indicesData.size()) +
                               ", submeshes=" + std::to_string(subMeshList.size()),
                           true);
            return;
        }
 
        throw mxvk::Exception("MXModel::load unsupported file format: " + path);
    }

materials()

const std::vector< MXMaterial > & mxvk::MXModel::materials ( ) const

inlinenodiscard

Definition at line 157 of file mxvk_model.hpp.

{ return materialList; }

mtlLibPath()

const std::string & mxvk::MXModel::mtlLibPath ( ) const

inlinenodiscard

Definition at line 158 of file mxvk_model.hpp.

{ return mtlLibraryPath; }

operator=() [1/2]

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

delete

operator=() [2/2]

MXModel & mxvk::MXModel::operator= ( MXModel && other )

noexcept

Definition at line 34 of file mxvk_model.cpp.

                                                      {
        if (this == &other) {
            return *this;
        }
 
        verticesData = std::move(other.verticesData);
        indicesData = std::move(other.indicesData);
        subMeshList = std::move(other.subMeshList);
        materialList = std::move(other.materialList);
        mtlLibraryPath = std::move(other.mtlLibraryPath);
        vertexBufferHandle = other.vertexBufferHandle;
        vertexBufferMemory = other.vertexBufferMemory;
        indexBufferHandle = other.indexBufferHandle;
        indexBufferMemory = other.indexBufferMemory;
 
        other.vertexBufferHandle = VK_NULL_HANDLE;
        other.vertexBufferMemory = VK_NULL_HANDLE;
        other.indexBufferHandle = VK_NULL_HANDLE;
        other.indexBufferMemory = VK_NULL_HANDLE;
        return *this;
    }

subMesh()

const SubMesh & mxvk::MXModel::subMesh ( size_t i ) const

inlinenodiscard

Definition at line 154 of file mxvk_model.hpp.

{ return subMeshList[i]; }

subMeshCount()

size_t mxvk::MXModel::subMeshCount ( ) const

inlinenodiscard

Definition at line 153 of file mxvk_model.hpp.

{ return subMeshList.size(); }

subMeshes()

const std::vector< SubMesh > & mxvk::MXModel::subMeshes ( ) const

inlinenodiscard

Definition at line 155 of file mxvk_model.hpp.

{ return subMeshList; }

upload()

void mxvk::MXModel::upload	(	VkDevice	device,
		VkPhysicalDevice	physicalDevice,
		VkCommandPool	commandPool,
		VkQueue	graphicsQueue )

Upload parsed geometry to device-local GPU buffers.

Parameters

device	Logical Vulkan device.
physicalDevice	Physical Vulkan device.
commandPool	Command pool used for transfer command buffer allocation.
graphicsQueue	Queue used to submit transfer commands.

Definition at line 1149 of file mxvk_model.cpp.

                                                                           {
        if (device == VK_NULL_HANDLE || physicalDevice == VK_NULL_HANDLE ||
            commandPool == VK_NULL_HANDLE || graphicsQueue == VK_NULL_HANDLE) {
            throw mxvk::Exception("MXModel::upload requires valid Vulkan handles");
        }
        if (verticesData.empty() || indicesData.empty()) {
            throw mxvk::Exception("MXModel::upload requires loaded geometry");
        }
 
        logMXModelStep("upload begin", true);
 
        cleanup(device);
 
        const VkDeviceSize vertexBufferSize = sizeof(VKVertex) * verticesData.size();
        const VkDeviceSize indexBufferSize = sizeof(uint32_t) * indicesData.size();
 
        VkBuffer stagingVertexBuffer = VK_NULL_HANDLE;
        VkDeviceMemory stagingVertexMemory = VK_NULL_HANDLE;
        createBuffer(device, physicalDevice, vertexBufferSize,
                     VK_BUFFER_USAGE_TRANSFER_SRC_BIT,
                     VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                     stagingVertexBuffer, stagingVertexMemory);
 
        VkBuffer stagingIndexBuffer = VK_NULL_HANDLE;
        VkDeviceMemory stagingIndexMemory = VK_NULL_HANDLE;
        createBuffer(device, physicalDevice, indexBufferSize,
                     VK_BUFFER_USAGE_TRANSFER_SRC_BIT,
                     VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT,
                     stagingIndexBuffer, stagingIndexMemory);
 
        void *vertexData = nullptr;
        vkMapMemory(device, stagingVertexMemory, 0, vertexBufferSize, 0, &vertexData);
        std::memcpy(vertexData, verticesData.data(), static_cast<size_t>(vertexBufferSize));
        vkUnmapMemory(device, stagingVertexMemory);
 
        void *indexData = nullptr;
        vkMapMemory(device, stagingIndexMemory, 0, indexBufferSize, 0, &indexData);
        std::memcpy(indexData, indicesData.data(), static_cast<size_t>(indexBufferSize));
        vkUnmapMemory(device, stagingIndexMemory);
 
        createBuffer(device, physicalDevice, vertexBufferSize,
                     VK_BUFFER_USAGE_TRANSFER_DST_BIT | VK_BUFFER_USAGE_VERTEX_BUFFER_BIT,
                     VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT,
                     vertexBufferHandle, vertexBufferMemory);
 
        createBuffer(device, physicalDevice, indexBufferSize,
                     VK_BUFFER_USAGE_TRANSFER_DST_BIT | VK_BUFFER_USAGE_INDEX_BUFFER_BIT,
                     VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT,
                     indexBufferHandle, indexBufferMemory);
 
        copyBuffer(device, commandPool, graphicsQueue, stagingVertexBuffer, vertexBufferHandle, vertexBufferSize);
        copyBuffer(device, commandPool, graphicsQueue, stagingIndexBuffer, indexBufferHandle, indexBufferSize);
 
        vkDestroyBuffer(device, stagingVertexBuffer, nullptr);
        vkFreeMemory(device, stagingVertexMemory, nullptr);
        vkDestroyBuffer(device, stagingIndexBuffer, nullptr);
        vkFreeMemory(device, stagingIndexMemory, nullptr);
 
        logMXModelStep("upload complete", true);
    }

vertexBuffer()

VkBuffer mxvk::MXModel::vertexBuffer ( ) const

inlinenodiscard

Definition at line 150 of file mxvk_model.hpp.

{ return vertexBufferHandle; }

vertices()

const std::vector< VKVertex > & mxvk::MXModel::vertices ( ) const

inlinenodiscard

Definition at line 146 of file mxvk_model.hpp.

{ return verticesData; }

---

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

• mxvk/include/mxvk/mxvk_model.hpp
• mxvk/src/mxvk_model.cpp