methanepowered / methaneasteroids

:ringed_planet: Asteroids sample demonstrating multi-threaded rendering of large number random-generated asteroids with Methane Kit framework using DirectX 12, Vulkan and Metal

Methane Asteroids Sample

Asteroids sample demonstrates multi-threaded rendering of large number of random-generated asteroids with Methane Kit library using one of modern graphics APIs (DirectX 12, Vulkan or Metal) and platform independent implementation. Thousands of unique asteroid instances (1000-50000) are drawn with individual draw-call parameters in parallel with a random combination of:

• random-generated mesh (from array of up to 1000 unique meshes),
• random generated perlin-noise array texture each with 3 projections (from array of up to 50 unique textures),
• random combination of coloring (from 72 color combinations).

Methane Asteroids sample was inspired by Intel Asteroids D3D12, but implemented from scratch in a cross-platform style using Methane Kit.

Platform	Graphics API	Screenshot
Windows	DirectX 12 Vulkan
Linux	Vulkan
MacOS	Vulkan Metal
iOS, tvOS	Metal

Build Instructions

• Prerequisites
• Fetch Sources
  • Notes
  • First time initialization
  • Update sources to latest revision
• Building from Sources
  • Windows Build with Visual Studio
  • Linux Build with Unix Makefiles
  • MacOS Build with XCode
  • iOS and tvOS Build with XCode
• CMake Generator
  • CMake Options
  • CMake Presets

Features

Default parameters of asteroids simulation are selected depending on CPU HW cores count and are displayed in right-bottom panel (switched with F3 key). Overall scene complexity can be reduced or increased by pressing [ / ] keys. Sample renders galaxy background using Methane::Graphics::SkyBox and planet using generated Methane::Graphics::SphereMesh with spherical texture coordinates. It also uses interactive Arc-Ball camera rotated with mouse LMB and light rotated with RMB with keyboard shortcuts also available (see in help by F1 key).

Rendering Optimizations

• Asteroid meshes use dynamically selected LODs depending on estimated screen size. This allows to greatly reduce GPU overhead. Use L key to enable LODs coloring and ' / ; keys to increase / reduce overall mesh level of details.
• Parallel rendering of asteroids array with individual draw-calls allows to be less CPU bound. Multi-threading can be switched off for comparing with single-threaded rendering by pressing P key.
• Parallel updating of asteroid transformation matrices in AsteroidsArray::Update and encoding asteroid meshes rendering in MeshBuffers::DrawParallel are implemented using Taskflow library which enables effective usage of the thread-pool via parallel_for primitive.
• All asteroid textures are bound to program uniform all at once as an array of textures to minimize number of program binding calls between draws. Particular texture is selected on each draw call using index parameter in constants buffer. Note that each asteroid texture is a texture 2d array itself with 3 mip-mapped textures used for triplane projection.
• Inverted depth buffer (with values from 1 in foreground to 0 in background and greater-or-equal compare function) is used to minimize frame buffer overdrawing by rendering in order from foreground to background: asteroids array with planet are drawn first and sky-box afterwards.

Controls

Keyboard actions

Keyboard Action	Shortcut	Controller
APPLICATION SETTINGS
Show controls help	F1	Platform::AppController
Show command-line help	F2	Platform::AppController
Show parameters	F3	Platform::AppController
Switch heads-up-display mode	F4	UserInterface::AppController
Switch full-screen	LCtrl + F	Platform::AppController
Close application	LCtrl/LCmd + Q	Platform::AppController
Switch animations on/off	LCtrl + P	Graphics::AppController
GRAPHICS CONTEXT SETTINGS
Switch vertical synchronization	LCtrl + V	Graphics::AppContextController
Switch device used for rendering	LCtrl + X	Graphics::AppContextController
Add frame buffer to swap-chain	LCtrl + +	Graphics::AppContextController
Remove frame buffer from swap-chain	LCtrl + -	Graphics::AppContextController
VIEW CAMERA
Move camera left	A	Graphics::AppCameraController
Move camera right	D	Graphics::AppCameraController
Move camera forward	W	Graphics::AppCameraController
Move camera backward	S	Graphics::AppCameraController
Move camera up	Page Up	Graphics::AppCameraController
Move camera down	Page Down	Graphics::AppCameraController
Yaw camera left	Left	Graphics::AppCameraController
Yaw camera right	Right	Graphics::AppCameraController
Pitch camera up	Up	Graphics::AppCameraController
Pitch camera down	Down	Graphics::AppCameraController
Roll camera left	<	Graphics::AppCameraController
Roll camera right	>	Graphics::AppCameraController
Zoom camera in	+	Graphics::AppCameraController
Zoom camera out	-	Graphics::AppCameraController
Change camera pivot	LAlt + P	Graphics::AppCameraController
Reset camera orientation	LAlt + R	Graphics::AppCameraController
LIGHT SOURCE
Reset light orientation	LCtrl + L	Graphics::AppCameraController
ASTEROIDS SETTINGS
Switch Parallel Rendering	P	Samples::AsteroidsAppController
Switch Mesh LODs Coloring	L	Samples::AsteroidsAppController
Increase Mesh LOD Complexity	'	Samples::AsteroidsAppController
Decrease Mesh LOD Complexity	;	Samples::AsteroidsAppController
Increase Scene Complexity	]	Samples::AsteroidsAppController
Decrease Scene Complexity	[	Samples::AsteroidsAppController
Set Scene Complexity 0 .. 9	0..9	Samples::AsteroidsAppController

Mouse actions

Mouse action	Mouse Button	Controller
VIEW CAMERA
Rotate camera	Left Button	Graphics::AppCameraController
Zoom camera	Ver. Scroll Wheel	Graphics::AppCameraController
Move camera	Middle Button	Graphics::AppCameraController
LIGHT SOURCE
Rotate Light	Right Button	Graphics::AppCameraController

Command line

Argument	Value (Default)	Description
APPLICATION SETTINGS
-h, --help	-	Print help message and exit
-w, --wnd-size	W H (0.8 0.8)	Window size in pixels or as ratio of desktop size
-f, --full-screen	0 / 1 (0)	Full-screen mode
-a, --animations	0 / 1 (1)	Enable animations
-d, --device	-1 / 0..N (0)	Render at adapter index, use -1 for software adapter
-v, --vsync	0 / 1	Vertical synchronization
-b, --frame-buffers	0..N (3)	Frame buffers count in swap-chain
-i, --hud	0..2 (2)	HUD display mode (0 - hidden, 1 - in window title, 2 - in UI)
ASTEROIDS SETTINGS
-c, --complexity	0..9	Asteroids simulation complexity
-s, --subdiv-count	1..N	Mesh subdivisions count
-t, --texture-array	0 / 1 (0)	Texture array enabled
-r, --parallel-render	0 / 1 (1)	Parallel rendering enabled

Instrumentation and Profiling

Integrated instrumentation of the Methane Kit library and Asteroids sample enables profiling with the following tools:

• Tracy Profiler
• Intel GPA Trace Analyzer
• Intel VTune Profiler

Tracy Frame Profiler	Intel Graphics Trace Analyzer

External Dependencies

• Libraries
• Build Tools
• Assets

License

Methane Asteroids sample along with Methane Kit are distributed under Apache 2.0 License: it is free to use and open for contributions!

Copyright 2019-2022 © Evgeny Gorodetskiy

methaneasteroids's Issues

Vulkan sample crashes on NVIDIA Optimus laptop

Describe the bug
Released Vulkan sample fails to start

Steps To Reproduce
Launch in IDA using an NVIDIA Optimus laptop

7FF8E767D230: The instruction at 0x7FF8E767D230 referenced memory at 0x1C2A3FFE050. The memory could not be read -> 000001C2A3FFE050 (exc.code c0000005, tid 18596)

RIP in IDA
nvoglv64.dll:00007FF8E767D230 loc_7FF8E767D230: ; CODE XREF: nvoglv64.dll:nvoglv64_vk_optimusGetInstanceProcAddr+205B3↓j

Expected behavior
Should work like the DX sample (which also is not Optimus aware and runs on iGPU, unless you force the dGPU in the Windows control panel)

Desktop (please complete the following information):

• OS: Windows 11
• Version: beta channel
• Build environment - released binary

Probably this helps?
"Trick to tell AMD and Nvidia drivers to use the most powerful GPU instead of a lower-performance (such as integrated) GPU"
https://gist.github.com/statico/6809850727c708f08458

Clean build fails on macOS

16-inch 2021 MacBook Pro, M1 Max
macOS Sonoma 14.5
cmake version 3.29.6

I'm building from console using the commands provided in the README.

OUTPUT_DIR=Build/Output/XCode/macOS
cmake -S . -B $OUTPUT_DIR/Build -G Xcode -DCMAKE_OSX_ARCHITECTURES="[arm64|x86_64]" -DCMAKE_OSX_ARCHITECTURES="[arm64|x86_64]" -DCMAKE_INSTALL_PREFIX="$(pwd)/$OUTPUT_DIR/Install"
cmake --build $OUTPUT_DIR/Build --config Release --target install

The build script fails because a folder hasn't yet been created:

WriteAuxiliaryFile /Users/marius/Documents/Gamedev/MethaneAsteroids/Build/Output/XCode/macOS/Build/build/MethaneAsteroids.build/Release/Script-032561A0B7652221BF209A44.sh (in target 'MethaneAsteroids' from project 'METHANE_ASTEROIDS')
    cd /Users/marius/Documents/Gamedev/MethaneAsteroids
    write-file /Users/marius/Documents/Gamedev/MethaneAsteroids/Build/Output/XCode/macOS/Build/build/MethaneAsteroids.build/Release/Script-032561A0B7652221BF209A44.sh

PhaseScriptExecution CMake\ PostBuild\ Rules /Users/marius/Documents/Gamedev/MethaneAsteroids/Build/Output/XCode/macOS/Build/build/MethaneAsteroids.build/Release/Script-032561A0B7652221BF209A44.sh (in target 'MethaneAsteroids' from project 'METHANE_ASTEROIDS')
    cd /Users/marius/Documents/Gamedev/MethaneAsteroids
    /bin/sh -c /Users/marius/Documents/Gamedev/MethaneAsteroids/Build/Output/XCode/macOS/Build/build/MethaneAsteroids.build/Release/Script-032561A0B7652221BF209A44.sh
Error: Target (for copy_if_different command) "/Users/marius/Documents/Gamedev/MethaneAsteroids/Build/Output/XCode/macOS/Build/App/Release/MethaneAsteroids.app/Contents/MacOS/../Resources" is not a directory.
Command PhaseScriptExecution failed with a nonzero exit code

Full log: build_log.txt

GitHub Actions build for Windows DirectX fails on DXC HLSL compilation when shaders validation is enabled

Describe the bug
Windows DirectX build fails on DXC HLSL shader compilation with Pipeline State validation error. Shader compilation passes when shader validation is manually disabled (as the result compiled shader is not usable). The same works fine in Azure Pipelines with shader validation enabled.

Steps To Reproduce
Steps to reproduce the behavior:

1. Go to .github/workflows/asteroids-build.yml:117 and change cmake option -DMETHANE_SHADERS_VALIDATION_ENABLED:BOOL=OFF to ON
2. Commit and push changes
3. Wait for GitHub Actions to run, see Windows DirectX builds failures:

CUSTOMBUILD : error : Container part 'Pipeline State Validation' does not match expected for module. Use /Zi for source location. [D:\a\MethaneAsteroids\MethaneAsteroids\Build\Output\VS2022-Win64-DX-Default\Build\Modules\Simulation\92cb9df0f32d066bd409e0fe32d11575.vcxproj]
  Validation failed.

Expected behavior
DXC shader compilation should work normally with validation enabled, as it works in Azure Pipelines.

A number of the links in the readme are broken

such as https://github.com/MethanePowered/MethaneKit/tree/master/Modules/Graphics/Extensions/Include/Methane/Graphics/SkyBox.h

Low frame rate in Asteroids build with Vulkan API

Describe the bug
"Asteroids" sample built for Vulkan API has significantly lower FPS than for DirectX API in multi-threaded rendering scenario.

Steps To Reproduce
Steps to reproduce the behavior:

1. Run "Asteroids" sample built for DirectX, set scene complexity to 8 (35000 asteroids) => get ~294 FPS
2. Run "Asteroids" sample built for Vulkan, set scene complexity to 8 (35000 asteroids) => get ~77 FPS

Expected behavior
Comparable FPS is expected for DirectX and Vulkan version for the same application with equal parameters.

Desktop (please complete the following information):

• OS: Windows 11
• Version 23H2
• HW: Intel Core i7-7820X, NVidia GeForce 2070 SUPER
• Build environment Visual Studio 2022

Rootcause
This issue is tracked and fixed in MethanePowered/MethaneKit#130