Need help with MethaneKit?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

egorodet
405 Stars 15 Forks Apache License 2.0 1.6K Commits 13 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

No Data

Methane Kit

Gitpod Ready-to-Code Build Status Quality Gate Status CodeQL

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, Metal on MacOS and Vulkan on Linux & Windows. - 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 from CMake-based build toolchain to platform independent application foundation classes.

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 Azure Pipelines CI and Sonar Cloud. See Building from Sources topic for manual build instructions and start learning Methane Graphics Core API with Hello Triangle and other tutorials documentation.

Open in Gitpod

| Platform | Graphics API | Master Build Status | Develop Build Status | | ---------------- | -------------| --------------------- | ---------------------- | | MacOS | Metal | MacOS Master Build Status | MacOS Develop Build Status | | Windows x64 | DirectX 12 | Windows x64 Master Build Status | Windows x64 Develop Build Status | | Windows x86 | DirectX 12 | Windows x86 Master Build Status | Windows x86 Develop Build Status | | Windows x64 | Vulkanwip | Windows x64 Master Build Status | Windows x64 Develop Build Status | | Windows x86 | Vulkanwip | Windows x86 Master Build Status | Windows x86 Develop Build Status | | Linuxsoon | Vulkanwip | Ubuntu Master Build Status | Ubuntu Develop Build Status |

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 | | ---------------- | ------------------ | -------------------- | --------------------- | | MacOS Metal | Quality Gate Status | MacOS Master Scan Status | MacOS Develop Scan Status | | Windows DirectX | Windows Quality Gate Status | Windows Master Scan Status | Windows Develop Scan Status | | Linux Vulkan | Quality Gate Status | Linux Master Scan Status | Linux Develop Scan Status |

Windows Maintainability Rating Windows Reliability Rating Windows Security Rating Windows Code Smells Windows Duplicated Lines (%) Windows Coverage Windows Lines of Code Total lines

Asteroids sample on Windows

Asteroids sample demonstrating multi-threaded rendering with Methane Graphics API

Getting Started

High-Level Architecture

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

Graphics Core Interfaces

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

Tutorials

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

|

Name / Link
|
Screenshot
|
Description                                         
| | ----------------------------- | ---------------------------- | ---------------------------------------------------------------------- | | 1. Hello Triangle | Hello Triangle on Windows | Colored triangle rendering in 100 lines of code. | | 2. Hello Cube | Hello Cube on Windows | Colored cube rendering in 200 lines of code with vertex and index buffers. | | 3. Textured Cube | Textured Cube on Windows | Textured cube introduces buffers, textures and samplers usage with Phong shading.
* Vulkan is not supported yet. | | 4. Shadow Cube | Shadow Cube on Windows | Shadow cube introduces multi-pass rendering with render passes.
* Vulkan is not supported yet. | | 5. Typography | Typography on Windows | Typography demonstrates animated text rendering with dynamic font atlas updates using Methane UI.
* Vulkan is not supported yet. |

Samples

Methane samples demonstrate advanced techniques and usage scenarios with more complex implementation than tutorials above.

|

Name / Link
|
Screenshot
|
Description                                         
| | ----------------------------- | ---------------------------- | ---------------------------------------------------------------------- | | Asteroids | Asteroids on Windows | Benchmark demonstrating parallel render commands encoding in a single render pass for the large number of heterogeneous asteroid objects processed in multiple threads.
* Vulkan is not supported yet. |

Features

  • Cross-platform application & input classes: Windows & MacOS are supported, Linux is coming soon
    • 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, Metal and Vulkan 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
    • Perlin Noise generator
    • 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
    • Events mechanism connecting emitters and receivers via callback interfaces
    • Animations subsystem
    • Embedded resource providers
    • Range Set implementation
  • Integrated debugging and profiling capabilities:
  • Continuous integration with automated multi-platform builds, unit-tests and Sonar Cloud static code analysis in Azure Pipelines

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

Building from Sources

Prerequisites

  • Common
    • Git (required to pull sub-modules)
    • CMake 3.16 or later
  • Windows
    • Windows 10 RS5 (build 1809) or later
    • Visual Studio 2019 with MSVC v142 or later
    • Windows 10 SDK latest
  • MacOS
    • MacOS 10.15 "Catalina" or later
    • XCode 11 or later with command-line tools
  • Linux
    • Ubuntu 20.04 or later
    • GCC 9 or later

Fetch Sources

IMPORTANT! - Do not download source code via Zip archive, since it does not include content of Externals submodules. Use

git clone
command as described below. - Consider using short path for repository location on Windows (for example
c:\Git
), which may be required to resolve problem with support of paths longer than 260 symbols in some Microsoft build tools.

First time initialization

git clone --recurse-submodules https://github.com/egorodet/MethaneKit.git
cd MethaneKit

Update sources to latest revision

cd MethaneKit
git pull && git submodule update --init --recursive

Build

Windows Build with Visual Studio 2019

Start Command Prompt, go to MethaneKit root directory (don't forget to pull dependent submodules as described above) and either start auxiliary build script Build/Windows/Build.bat or build with CMake command line:

mkdir Build\Output\VisualStudio\Build && cd Build\Output\VisualStudio\Build
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_INSTALL_PREFIX="%cd%\..\Install" "..\..\..\.."
cmake --build . --config Release --target install

Alternatively you can open root CMakeLists.txt directly in Visual Studio or any other IDE of choice with native CMake support and build it with Ninja using provided configurations in CMakeSettings.json.

Methane Graphics Core is built using DirectX 12 graphics API on Windows by default. Vulkan graphics API can be used instead by adding cmake generator option

-DMETHANE_GFX_VULKAN_ENABLED:BOOL=ON
or by running
Build/Windows/Build.bat --vulkan
.

Run built applications from the installation directory

Build\Output\VisualStudio\Install\Apps

MacOS Build with XCode

Start Terminal, go to MethaneKit root directory (don't forget to pull dependent submodules as described above) and either start auxiliary build script Build/Posix/Build.sh or build with CMake command line:

mkdir -p Build/Output/XCode/Build && cd Build/Output/XCode/Build
cmake -H../../../.. -B. -G Xcode -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64" -DCMAKE_INSTALL_PREFIX="$(pwd)/../Install"
cmake --build . --config Release --target install

Note that starting with XCode 12 and Clang 12 build architectures have to be specified explicitly using CMake generator command line option

-DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
to build the fat binary. This option can be omitted with earlier versions of Clang on macOS.

Alternatively you can open root CMakeLists.txt and build it from any IDE with native CMake support.

Methane Graphics Core is built using Metal graphics API on MacOS by default. Vulkan graphics API can be used instead by adding cmake generator option

-DMETHANE_GFX_VULKAN_ENABLED:BOOL=ON
or by running
Build/Posix/Build.sh --vulkan
, but it requires Vulkan SDK installation with MoltenVK driver implementation on top of Metal, which is not currently supporting all extensions required by Methane Kit.

Run built applications from the installation directory

Build/Output/XCode/Install/Apps

Linux Build with Unix Makefiles

Build on Linux is supported with "Unix Makefiles" generator. But Linux platform abstraction layer implementation is not ready yet and is currently stubbed, so in spite of it builds, do not expect anything to work on Linux now besides unit-tests.

mkdir -p Build/Output/Linux/Build && cd Build/Output/Linux/Build
cmake -H../../../.. -B. -G "Unix Makefiles" -DCMAKE_INSTALL_PREFIX="$(pwd)/../Install"
cmake --build . --config Release --target install

Methane Graphics Core is built using Vulkan graphics API on Linux.

CMake Build Options

Build options can be configured in cmake generator command line:

console
cmake -G [Generator] ... -D[BUILD_OPTION_NAME]:BOOL=ON

| Build Option Name | Default Value | Release Build | Profiling Build | Description | | ----------------------------------------------- | ----------------------- | ----------------------- | ----------------------- | ----------------------- | | METHANEGFXVULKANENABLED | OFF | OFF | OFF | Enable Vulkan graphics API instead of platform native API | | METHANEAPPSBUILDENABLED | ON | ON | ON | Enable applications build | | METHANETESTSBUILDENABLED | ON | ON | ON | Enable tests build | | METHANECHECKSENABLED | ON | ON | ON | Enable runtime checks of input arguments | | METHANERUNTESTSDURINGBUILD | ON | OFF | OFF | Enable test auto-run after module build | | METHANEUNITYBUILDENABLED | ON | ON | ON | Enable unity build speedup for some modules | | METHANECODECOVERAGEENABLED | OFF | OFF | OFF | Enable code coverage data collection with GCC and Clang | | METHANESHADERSCODEVIEWENABLED | OFF | ON | ON | Enable shaders code symbols viewing in debug tools | | METHANEOPENIMAGEIOENABLED | OFF | OFF | OFF | Enable using OpenImageIO library for images loading | | METHANECOMMANDDEBUGGROUPSENABLED | OFF | ON | ON | Enable command list debug groups with frame markup | | METHANELOGGINGENABLED | OFF | OFF | OFF | Enable debug logging | | METHANESCOPETIMERSENABLED | OFF | OFF | ON | Enable low-overhead profiling with scope-timers | | METHANEITTINSTRUMENTATIONENABLED | OFF | ON | ON | Enable ITT instrumentation for trace capture with Intel GPA or VTune | | METHANEITTMETADATAENABLED | OFF | OFF | ON | Enable ITT metadata for tasks and events like function source locations | | METHANEGPUINSTRUMENTATIONENABLED | OFF | OFF | ON | Enable GPU instrumentation to collect command list execution timings | | METHANETRACYPROFILINGENABLED | OFF | OFF | ON | Enable realtime profiling with Tracy | | METHANETRACYPROFILINGON_DEMAND | OFF | OFF | ON | Enable Tracy data collection on demand, after client connection |

Supported Development Tools

Development Environments

- Microsoft Visual Studio 2019 - Solutions and projects build (generate with Build.bat) - Ninja build with CMake native support (pre-configured with CMakeSettings.json) - Apple XCode - XCode workspace and projects (generate with Build.sh) - Microsoft VS Code and GitPod (pre-configured with .vscode/settings.json) - Jet Brains CLion (pre-configured with .idea) - Jet Brains ReSharper C++ (pre-configured with Folder.DotSettings) - 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 | Windows Master Scan Status | MacOS Master Scan Status | Linux Master Scan Status | | Quality Gate | Windows Quality Gate Status | MacOS Quality Gate Status | Linux Quality Gate Status | | Maintainability | Windows Maintainability Rating | MacOS Maintainability Rating | Linux Maintainability Rating | | Reliability | Windows Reliability Rating | MacOS Reliability Rating | Linux Reliability Rating | | Security | Windows Security Rating | MacOS Security Rating | Linux Security Rating | | Technical Debt | Windows Technical Debt | MacOS Technical Debt | Linux Technical Debt | Bugs | Windows Bugs | MacOS Bugs | Linux Bugs | | Vulnerabilities | Windows Vulnerabilities | MacOS Vulnerabilities | Linux Vulnerabilities | Code Smells | Windows Code Smells | MacOS Code Smells | Linux Code Smells | | Duplicated Lines | Windows Duplicated Lines (%) | MacOS Duplicated Lines (%) | Linux Duplicated Lines (%) | | Tests Coverage | Windows Coverage | MacOS Coverage | Linux Coverage | | Lines of Code | Windows Lines of Code | MacOS Lines of Code | Linux 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 | | -------------------- | ----------------------------- | | Asteroids Trace in Tracy | Asteroids Trace in GPA Trace Analyzer |

Frame Profiling and Debugging Tools

External Dependencies

All external dependencies of Methane Kit are listed in MethaneExternals repository. See MethaneExternals/README.md for more details.

License

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

Copyright 2019-2021 © Evgeny Gorodetskiy Follow

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.