{"id":19248569,"url":"https://github.com/nvidiagameworks/heightmap_rtx","last_synced_at":"2025-04-21T11:34:27.456Z","repository":{"id":212546531,"uuid":"727978378","full_name":"NVIDIAGameWorks/heightmap_rtx","owner":"NVIDIAGameWorks","description":null,"archived":false,"fork":false,"pushed_at":"2024-05-13T23:47:26.000Z","size":250,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":15,"default_branch":"main","last_synced_at":"2024-05-14T00:51:55.459Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NVIDIAGameWorks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-06T01:05:08.000Z","updated_at":"2024-05-13T23:45:08.000Z","dependencies_parsed_at":null,"dependency_job_id":"658df0ec-ee12-4edf-9689-d4cd8d2835bd","html_url":"https://github.com/NVIDIAGameWorks/heightmap_rtx","commit_stats":null,"previous_names":["nvidiagameworks/heightmap_rtx"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2Fheightmap_rtx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2Fheightmap_rtx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2Fheightmap_rtx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVIDIAGameWorks%2Fheightmap_rtx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVIDIAGameWorks","download_url":"https://codeload.github.com/NVIDIAGameWorks/heightmap_rtx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223863922,"owners_count":17216234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T18:08:55.614Z","updated_at":"2025-04-21T11:34:27.415Z","avatar_url":"https://github.com/NVIDIAGameWorks.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e [!IMPORTANT]\n\u003e This project has been archived and is no longer maintained. The vulkan\n\u003e extension `VK_NV_displacement_micromap` is no longer available.\n\u003e\n\u003e We recommend exploring [**NVIDIA RTX Mega\n\u003e Geometry**](https://developer.nvidia.com/blog/nvidia-rtx-mega-geometry-now-available-with-new-vulkan-samples/),\n\u003e which can provide similar functionality with greater flexibility. See\n\u003e [vk_tessellated_clusters](https://github.com/nvpro-samples/vk_tessellated_clusters),\n\u003e which demonstrates raytracing displacement with Vulkan.\n\n# Heightmap RTX\n\n![raytraced displacement using heightmap_rtx](doc/preview.jpg \"Raytraced\ndisplacement in micromesh_toolbox using this library. Turtle Barbarian model by\nJesse Sandifer, courtesy of Autodesk.\")\n\u003cbr/\u003e\u003csub\u003e\u003csup\u003eRaytraced displacement in \u003ca\nhref=\"https://github.com/NVIDIAGameWorks/Displacement-MicroMap-Toolkit\"\u003emicromesh_toolbox\u003c/a\u003e\nusing this library. \"Turtle Barbarian\" model by Jesse Sandifer, courtesy of\nAutodesk.\u003c/sup\u003e\u003c/sub\u003e\n\nHeightmap RTX is a small Vulkan library to displace raytraced triangles with a\nheightmap. It uses [NVIDIA\nMicro-Mesh](https://developer.nvidia.com/rtx/ray-tracing/micro-mesh)\n([Toolkit](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-Toolkit))\ninternally. It can also be seen as a cheap runtime micromap baker.\n\n[VK_NV_displacement_micromap](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_NV_displacement_micromap.html)\nis required. See [device\nsupport](https://vulkan.gpuinfo.org/listdevicescoverage.php?extension=VK_NV_displacement_micromap\u0026platform=all).\n\n## API Guide\n\n1. Include [CMakeLists.txt](CMakeLists.txt) to provide the `heightmap_rtx` static library. The C interface is defined in [heightmap_rtx.h](include/heightmap_rtx/heightmap_rtx.h).\n2. Create a `HrtxMap` object from an image and the geometry that would normally be added to the acceleration structure build. This depends on a common `HrtxPipeline` object.\n3. Set the geometry's `pNext` to the micromap description returned by `hrtxMapDesc(HrtxMap)` before building the acceleration structure.\n4. Make sure the vulkan raytracing pipeline is created with `VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV`.\n\nFor a complete example, see the nvpro_core sample [vk_raytrace_displacement](https://github.com/nvpro-samples/vk_raytrace_displacement).\n\n```c++\n#include \u003cheightmap_rtx.h\u003e\n\n...\n\n// Library input data\ngeometry.vertexTexcoordBuffer.address = ...;\ngeometry.vertexNormalBufferHVec4.address = ...;\nVkAccelerationStructureGeometryTrianglesDataKHR triangles = {...};\nVkAccelerationStructureBuildRangeInfoKHR        buildRange = {...};\nVkImage                                         heightmapImage = ...;\nVkDescriptorImageInfo                           heightmapImageInfo = ...;\nfloat                                           heightmapBias = 0.0f;\nfloat                                           heightmapScale = 1.0f;\n\n// A callback must be provided for buffer allocation (this example uses nvpro_core's AllocVma).\nHrtxAllocatorCallbacks allocatorCallbacks{\n    [](const VkBufferCreateInfo bufferCreateInfo, const VkMemoryPropertyFlags memoryProperties, void* userPtr) {\n      auto alloc  = reinterpret_cast\u003cnvvkhl::AllocVma*\u003e(userPtr);\n      auto result = new nvvk::Buffer();\n      *result     = alloc-\u003ecreateBuffer(bufferCreateInfo, memoryProperties);\n      return \u0026result-\u003ebuffer;  // return pointer to member\n    },\n    [](VkBuffer* bufferPtr, void* userPtr) {\n      auto alloc = reinterpret_cast\u003cnvvkhl::AllocVma*\u003e(userPtr);\n      // reconstruct from pointer to member\n      auto nvvkBuffer = reinterpret_cast\u003cnvvk::Buffer*\u003e(reinterpret_cast\u003cchar*\u003e(bufferPtr) - offsetof(nvvk::Buffer, buffer));\n      alloc-\u003edestroy(*nvvkBuffer);\n      delete nvvkBuffer;\n    },\n    alloc,\n};\n\n// This example assumes these vulkan objects exist\nVkPhysicalDevice physicalDevice = ...;\nVkDevice         device = ...;\nVkCommandBuffer  cmd = ...;\n\n// Create a HrtxPipeline object. This holds the shader and resources for baking\nHrtxPipeline pipeline;\nHrtxPipelineCreate hrtxPipelineCreate{\n    physicalDevice, device, allocatorCallbacks, VK_NULL_HANDLE, nullptr, nullptr, VK_NULL_HANDLE,\n    [](VkResult result) {\n      ... handle error\n    }};\nif(hrtxCreatePipeline(cmd, \u0026hrtxPipelineCreate, \u0026pipeline) != VK_SUCCESS)\n{\n  ... handle error\n}\n\n// Create a HrtxMap object from an image to displace some geometry\n// This adds a call to 'cmd' to execute a compute shader to bake a micromap\n... use hrtxBarrierFlags() to synchronize inputs if needed\nHrtxMap        hrtxMap;\nconst uint32_t subdivLevel = 5;\nHrtxMapCreate  mapCreate{\n    \u0026triangles,\n    buildRange.primitiveCount,\n    geometry.vertexTexcoordBuffer.address,\n    VK_FORMAT_R32G32_SFLOAT,\n    sizeof(float) * 2,\n    geometry.vertexNormalBuffer.address,  // displacement directions\n    VK_FORMAT_R32G32B32_SFLOAT,\n    sizeof(float) * 3,\n    heightmapImageInfo,\n    heightmapBias,\n    heightmapScale,\n    subdivLevel,\n};\nif(hrtxCmdCreateMap(cmd, pipeline, \u0026mapCreate, \u0026hrtxMap) != VK_SUCCESS)\n{\n  ... handle error\n}\n\n// Library output is a micromap\nVkAccelerationStructureTrianglesDisplacementMicromapNV micromapDesc = hrtxMapDesc(hrtxMap);\ntriangles.pNext = \u0026micromapDesc;\n\n// Build the acceleration structure normally\n... vkCmdBuildAccelerationStructureNV()\n\n// Make sure the pipeline has micromaps enabled\nVkRayTracingPipelineCreateInfoKHR pipelineCreateInfo = {...};\npipelineCreateInfo.flags |= VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV;\n```\n\n## Rendering Differences\n\nMicro-Mesh was designed to be as seamless as possible. By setting the pipeline\nflag VK_PIPELINE_CREATE_RAY_TRACING_DISPLACEMENT_MICROMAP_BIT_NV and\nVkAccelerationStructureGeometryTrianglesDataKHR::pNext, rays will just start\nhitting displaced geometry. One caveat is when existing shaders interpolate the\noriginal triangle positions. An alternative is to use gl_WorldRayOriginEXT +\ngl_WorldRayDirectionEXT * gl_HitTEXT, which will produce a position on the\ndisplaced surface. gl_HitMicroTriangleVertexPositionsNV can also be used if it’s\nnecessary to specialize. Micromesh also produces a gl_HitKindEXT of\ngl_HitKindFrontFacingMicroTriangleNV and gl_HitKindBackFacingMicroTriangleNV\ninstead of gl_HitKindFrontFacingTriangleEXT and gl_HitKindBackFacingTriangleEXT.\n\n## Limitations\n\n- The baked micromap is not well compressed, using lossless unorm11 packed\n  encoding.\n- Displacement bounds are not generated, possibly resulting in poor raytracing\n  performance.\n- This library supports a maximum subdivision level of 5, so each triangle can\n  be subdivided into at most 1024 micro-triangles. This might be too\n  low-resolution for some heightmaps. Larger libraries like the Micro-Mesh\n  Toolkit can pre-tessellate the input mesh to avoid this limitation.\n- Micromesh direction vectors are not normalized after interpolation and this is\n  not compensated for during baking, resulting in flatter displacement in across\n  triangles of high curvature.\n- Discontinuities across UV seams are not stitched, which can produce small\n  cracks.\n- Hard edge normals can produce large cracks. It is up to the application to\n  provide smooth displacement direction vectors.\n\nThe intent of this library is to give quick easy access to\n[VK_NV_displacement_micromap](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_NV_displacement_micromap.html).\nUltimately, baking a micromap offline with displacement bounds fitting and\ncompression optimization will give better results, e.g. using `micromesh_tool`\nfrom the\n[Toolkit](https://github.com/NVIDIAGameWorks/Displacement-MicroMap-Toolkit).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvidiagameworks%2Fheightmap_rtx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvidiagameworks%2Fheightmap_rtx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvidiagameworks%2Fheightmap_rtx/lists"}