methanepowered / methanekit Goto Github PK

🎲 Modern 3D graphics made simple with C++17 cross-platform framework and rendering abstraction API on top of DirectX 12, Metal & Vulkan

License: Apache License 2.0

CMake 4.27% C++ 85.10% HLSL 0.67% Shell 0.56% Batchfile 0.27% C 0.50% Objective-C++ 8.57% PowerShell 0.04% Dockerfile 0.02%

graphics d3d12 metal cross-platform gamedev vulkan hlsl graphics-engine graphics-programming graphics-library

methanekit's Introduction

Methane Kit

Easy to use modern 3D graphics rendering abstraction API and cross-platform application framework:

Builds on top of modern native 3D graphics APIs: DirectX 12 on Windows, Vulkan on Linux, Metal on MacOS, iOS & tvOS.
Simplifies modern graphics programming with object-oriented medium-level graphics API inspired by simplicity of Apple Metal. Common shaders code in HLSL 6 is used on all platforms.
Provides cross-platform application framework with CMake build toolchain, platform-independent application foundation classes and native-GUI layer for Windows, Linux and MacOS.

Download release builds with pre-built samples, tutorials and tests to try them out. Check latest build status, tests, code coverage and analysis results or get build artifacts from GitHub Actions CI and Sonar Cloud. See Build Instructions topic for manual build instructions and start learning Methane Graphics RHI API with Hello Triangle and other tutorials' documentation.

Platform	Graphics API	Master Build	Develop Build
Windows x64	DirectX 12
Windows x86	DirectX 12
Windows x64	Vulkan
Windows x86	Vulkan
Linux	Vulkan
MacOS	Vulkan
MacOS	Metal
iOS (Sim)	Metal
tvOS (Sim)	Metal

Static code analysis scans are performed as a part of automated CI build process on master and develop branches with up-to-date results published on Sonar Cloud.

Platform	Sonar Quality Gate	Master Scan Status	Develop Scan Status
Windows DirectX
Linux Vulkan
MacOS Metal

Asteroids sample demonstrating multi-threaded rendering with Methane Kit

Build Instructions

Getting Started

High-Level Architecture

Methane Kit architecture is clearly distributing library modules between 5 layers from low to high level of abstraction.

Rendering Hardware Interface (RHI)

Methane Graphics RHI module implements a set of public object-oriented interfaces, which make modern graphics programming easy and convenient in a platform and API independent way.

Tutorials

Start learning Methane Graphics API with Hello Triangle tutorial documentation and continue with others.

Name / Link	Screenshot	Description
1. Hello Triangle		Colored triangle rendering in 100 lines of code.
2. Hello Cube		Colored cube rendering in 200 lines of code with vertex and index buffers.
3. Textured Cube		Textured cube introduces buffers, textures and samplers usage with Phong shading.
4. Shadow Cube		Shadow cube introduces multi-pass rendering with render passes.
5. Typography		Typography demonstrates animated text rendering with dynamic font atlas updates using Methane UI.
6. Cube-Map Array		Cube-map array texturing along with sky-box rendering.
7. Parallel Rendering		Parallel rendering of the textured cube instances to the single render pass.
8. Console Compute		Conway's Game of Life implemented in Compute Shader and running in pure console application.

Samples

Methane samples demonstrate advanced techniques and usage scenarios with more complex implementation than tutorials above. Samples are distributes in form of separate repositories.

Name / Link	Screenshot	Description
Asteroids		Benchmark demonstrating parallel render commands encoding in a single render pass for the large number of heterogeneous asteroid objects processed in multiple threads.

Features

Cross-platform application & input classes: Windows, MacOS and Linux are supported
- CMake modules for convenient application build configuration, adding shaders and embedded resources
- HLSL-6 Shaders serving all graphics APIs converted to native shader language and compiled in build time with SPIRV-Cross & DirectXCompiler
- HLSL++ Math library with HLSL-like syntax in C++ and vector-instruction optimizations for different platforms
Modern Graphics API abstractions: based on DirectX 12, Vulkan and Metal APIs
- Render state and program configuration with compact initialization syntax
- Program binding objects implement efficient binding of shader arguments to resources
- Automatic resource state tracking used for automatic resource transition barriers setup
- Resources are automatically retained from destroying while in use on GPU with shared pointers in command list state
- Command list execution state tracking with optional GPU timestamps query on completion
- Parallel render command list for multi-threaded render commands encoding in single render pass
- Multiple command queues execution on GPU with synchronization using fences
- Private GPU resources asynchronously updated through the upload command list and shared resource
- Registry of named graphics objects enabling reuse of render states and graphics resources between renderer objects
Graphics primitives and extensions:
- Graphics application base class with per-frame resource management and frame buffers resizing enable effective triple buffering
- Camera primitive and interactive arc-ball camera
- Procedural mesh generation for quad, box, sphere, icosahedron and uber-mesh
- Screen-quad and sky-box rendering extension classes
- Texture loader (currently implemented with STB, planned for replacement with OpenImageIO)
User Interface:
- UI application base class with integrated HUD, logo badge and help/parameters text panels
- Typography library for fonts loading, dynamic atlas updating, text rendering & layout
- Widgets library (under development)
Platform Infrastructure:
- Base application with window management and input handling for Windows, MacOS and Linux
- Events mechanism connecting emitters and receivers via callback interfaces
- Animations subsystem
- Embedded resource providers
Integrated debugging and profiling capabilities:
- Library instrumentation for performance analysis with trace profiling tools
- Debug names for all GPU objects and debug regions for graphics API calls for use with frame profiling tools
Continuous integration with automated multi-platform builds, unit-tests and Sonar Cloud static code analysis in GitHub Actions

For detailed features description and development plans please refer to Modules documentation.

Supported Development Tools

Development Environments

Microsoft Visual Studio 2019
- Solutions and projects build (generate with Build/Windows/Build.bat)
- CMake native build support (pre-configured with CMakePresets.json)
Apple XCode
- XCode workspace and projects (generate with Build/Unix/Build.sh)
Microsoft VS Code and GitPod (pre-configured with CMakePresets.json and .vscode/settings.json)
Jet Brains CLion (pre-configured with .idea)
Qt Creator with CMake native support

Methane Kit is being developed with support of Jet Brains development tools. Open source project development license is provided free of charge to all key contributors of Methane Kit project.

Static Code Analysis

Methane Kit comes with continuous C++ static code and code coverage analysis performed as a part of automated CI "Scan" builds with up-to-date results published on Sonar Cloud separately for all supported platforms.

Master Scan Results	Windows	MacOS	Linux
Scan Build Status
Quality Gate
Maintainability
Reliability
Security
Technical Debt
Bugs
Vulnerabilities
Code Smells
Duplicated Lines
Tests Coverage
Lines of Code

Trace Profiling Tools

Methane Kit contains integrated instrumentation of all libraries for performance analysis with trace collection using following tools. Please refer to Methane Instrumentation document for more details on trace collection instructions and related build options.

Tracy Frame Profiler	Intel Graphics Trace Analyzer

Frame Profiling and Debugging Tools

External Dependencies

License

Methane Kit is distributed under Apache 2.0 License: it is free to use and open for contributions!

methanekit's People

Contributors

Stargazers

Watchers

methanekit's Issues

Application input controllers infrastructure

Cube-map textures support

Implement cube-map textures support in DirectX 12 and Metal.

Make color/depth/stencil clearing optional in graphics context and in application base

Color/depth/stencil frame buffers clearing should be optionally configurable via Context::Settings and in Graphics::App base class. Asteroids sample does not need frame buffer clearing because it already renders sky-box primitive to full-screen.

Keyboard shortcuts stop working after switching to full screen window on MacOS

Start application, check application shortcuts are working normally
Switch window to full-screen by pressing CTRL+F
Check application shortcuts => shortcuts are not working anymore, but switch full-screen OFF/ON

Document render pass and render state in TexturedCube and ShadowCube tutorial docs

Write documentation about using Render Pass and Render State based on code of Shadow Cube tutorial.

Sky-box rendering primitive

Add Sky-Box rendering primitive to the Extensions module, which should use its private shaders for rendering (from Extensions library resources) and support setting custom cube-texture images from user code.

Support common texture formats for DirectX and Metal

MacOS window appears in background after application startup

Start MacOS application
Application window appears in background under other applications windows.

Instead, newly started application should appear in foreground.

Reduce number of dynamic memory allocations during frames rendering

User interface library

Design and implement basic user interface library based on Graphics/Core module. UI library should include most common controls: Panel, Button, Label, etc.

Arc-ball camera controlled with mouse and keyboard

Render Context Heads Up Display (HUD)

Implement HeadsUpDisplay user interface component for rendering text on screen with common rendering statistics and information of RenderContext.

Vulkan backend implementation

Implement Vulkan API backend in Graphics Core module.

Use Direct3D 12 render pass feature

Parallel command lists

Support parallel command list calls.

Support shader and texture resources in library modules

Methane libraries should allow adding dedicated shader/texture resources and using them from the library code (same as done for applications now).

Document resource bindings in TexturedCube & ShadowCube tutorial docs

Write documentation about using Program Resource Bindings based on code of Textured Cube tutorial.

Tutorials do not start on MacOS because of command line parsing error

When macOS bundled application is launched from Finder, MacOS assigns it a unique process serial number (PSN) and passes it to application as a command line argument, for example "-psn_0_8423432" (see description on stack overflow). When cxxopts tries to parse command line with psn argument it throws OptionException "Argument ‘-psn_0_8423432’ starts with a - but has incorrect syntax". When application is started from Terminal by full path to executable inside bundle it works normally because there is no psn argument in command line options.

Related issue created on cxxopts project: jarro2783/cxxopts#171

Animations infrastructure

Use boost::nowide from official repository

Replace non-official fork of boost::nowide with official repository built in standalone mode: https://github.com/boostorg/nowide

Cows sample demonstrating mesh loading, instancing and DoF postprocessing

Develop "cows" sample demonstraing mesh loading, instancing and depth of field postprocessing with simple Poisson disk technique.

Add SRGB gamma correction in samples

Support Cmake modules dependency diagrams generation with GraphViz

[DX12] Triple buffering does not work as expected

Triple buffering should enable submitting up to 3 frames for rendering to GPU without stalls at present, but currently each frame is rendered strictly after previous frame was presented, which seems to be incorrect.

Multi-window applications

Support creating multiple windows for application with independent graphic contexts.

Badge with Methane logo in tutorials and samples

Application user input with mouse and keyboard

Implement user input with mouse and keyboard in Methane application infrastructure. Start with GLFW implementation and implement similar approach in object-oriented style extending module Platform/App.

Addressable resource bindings support

Support program uniforms binding to resources such as constant buffers with byte offset specification inside of it.

Platform layer instrumentation

Instrument Platform modules with ITT tasks.

Texture mip-map levels generation

Implement auto-generation of texture mip-map levels.

Add instrumentation for Tracy realtime profiler

Tracy realtime profiler: https://github.com/wolfpld/tracy
Manual: https://github.com/wolfpld/tracy/releases/download/v0.6.3/tracy.pdf

Command line to set app and context configuration

Add command line parameters to setup app and context configuration parameters on startup. Command line parser library should be chosen and added to Externals.

Create a fence for each frame in swap-chain

https://github.com/egorodet/MethaneKit/blob/b660063359bc2a9798052a0ef13228706e211619/Modules/Graphics/Core/Sources/Methane/Graphics/DirectX12/ContextDX.cpp#L157

See description here: https://www.braynzarsoft.net/viewtutorial/q16390-03-initializing-directx-12

Related issue #15

Continuous integration system setup

Setup continuous integration system integrated with GitHub project (Travis for example).

Asteroids sample

Create Asteroids sample demonstrating parallel rendering.

https://app.leanboard.io/board/c55368cd-cd1e-41a9-a4fc-17c69a34066b

Texture arrays support

Add support for texture arrays

Dynamic linking support

Implement dynamic library for Methane Kit.

Cross-platform text rendering

Implement cross-platform approach to building font atlas and using it for cross-platform text rendering. Font atlas generation could use Freetype library. Text renderer should be a part of module Graphics/Extensions.

Linux platform support

Add Linux platform support to Platform App and Platform Input modules.

[VS Build] Install target is broken

Attempt to run any CMake install target leads to the error described below:

CMake Error at Externals/Nowide/cmake_install.cmake:51 (file):
    file INSTALL cannot find
    "C:/Users/sys_avctests/Documents/MethaneKit/Build/Output/VisualStudio/x64-Release/Build/Externals/Nowide/RelWithDebInfo/nowide0.pdb".
  Call Stack (most recent call first):
    Externals/cmake_install.cmake:41 (include)
    cmake_install.cmake:37 (include)

Unhandled exception on minimizing the window

Minimize the window, as the result error message is displayed and application is closed.

[DX12] Resource transition barrier warnings

Fix DirectX 12 debug-runtime warnings related to incorrect setup of resource transition barriers in Shadow Cube tutorial.

Mesh models loader

Choose 3rd-party mesh models loader and implement loading in a tutorial.

Icosahedron and geosphere mesh generation

Implement procedural icosahedron mesh generation with subdivision and spherification support in order to generate geo-spheres with desired details.

Compute pipeline support

Support execution of compute shaders with Methane Kit. Add compute pipeline interfaces to Graphics Core module along with DX12 and Metal implementations:

ComputeCommandList
ComputeState
Shader::Type::Compute

Swich device between available system devices
Switch VSync ON/OFF
Switch to full screen and back
Add/Remove frame buffers in swap-chain

iOS Mobile platform support

Support iOS platform in Platform App module and enable graphics rendering with Metal backend.