Methane Kit

Easy to use modern 3D graphics abstraction API in C++17 for cross-platform applications development:

• Builds on top of modern native 3D graphics APIs: DirectX 12 on Windows and Metal on MacOS, Vulkan on Linux will be enabled soon.
• Simplifies modern graphics programming with object-oriented higher-level graphics API inspired by simplicity of Apple's Metal and common shaders code in HLSL 6.
• Provides cross-platform application infrastructure from CMake-based toolchain to platform independent application and user input classes.

Click "Open in Gitpod" button above to explore Methane Kit codebase right away in a familiar VSCode-like IDE environment in your web-browser with navigation by symbols and cloud-build. Download release builds with built samples and tutorials to try them out. Also you can get Azure Pipelines build artifacts to test latest versions from develop branch. For manual build instruction see topic Building from Sources described below. Start learning Methane Graphics API with Hello Triangle tutorial documentation.

Platform	Graphics API	Master Build Status	Develop Build Status
Windows x64	DirectX 12
Windows x86	DirectX 12
MacOS	Metal
Linux	Vulkansoon

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
MacOS
Linux

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.

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.

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: DirectX 12 & Metal are supported, Vulkan is coming soon
  • 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:
  • 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 Azure Pipelines

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

Tutorials

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

Name / Link	Screenshot	Description
Hello Triangle		Colored triangle rendering in just 120 lines of code!
Textured Cube		Textured cube introduces buffers and textures usage along with program bindings.
Shadow Cube		Shadow cube introduces multi-pass rendering with render passes.
Typography		Typography demonstrates animated text rendering with dynamic font atlas updates using Methane UI.

Samples

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

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.

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.

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.

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 and Vulkan graphics API abstraction implementations are currently stubbed, so in spite of it builds fine, 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

CMake Build Options

Build options can be configured in cmake generator command line:

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

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
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

• Intel Graphics Frame Analyzer
• Apple XCode Metal Debugger
• RenderDoc
• Microsoft PIX
• NVidia Nsight Graphics

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