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
Ubuntu Linux	Vulkansoon

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.

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
• 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 partially initialized with help of shader reflection implement efficient binding of shader arguments to resources
  • Automatic resource state tracking used for resource transition barriers setup
  • Resources are automatically retained from destroying while they 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 via shared resource implicitly through the upload command list
  • Registry of named graphics objects used for reusing render states and graphics resources between UI items
• Graphics primitives and extensions for:
  • Graphics application base class with per-frame resource management, frame buffers resizing and other routine operations
  • Camera primitive and interactive arc-ball camera
  • Procedural mesh generation for quad, box, sphere, icosahedron and uber-mesh
  • Perlin Noise generation
  • Screen-quad and sky-box rendering extension classes
  • Texture image loader currently implemented with STB (planned for replacement with OpenImageIO, partially supported under the hood)
• User Interface libraries:
  • 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)
• Application infrastructure helpers:
  • Events mechanism connecting emitters and receivers via callback interfaces
  • Animations subsystem
  • Embedded resource providers
  • Range Set implementation
• Integrated API instrumentation for performance analysis with trace profiling tools
• Continuous integration with builds, unit-tests and 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. Other tutorials will be documented soon.

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.15 or later
• Windows
  • Windows 10 RS5 (build 1809) or later
  • Visual Studio 2019 with MSVC v142 or later
  • Windows 10 SDK
• MacOS
  • MacOS 10.13 "El Capitan" or later
  • XCode 9 or later with command-line tools
• Linux
  • Ubuntu 18.04 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_INSTALL_PREFIX="$(pwd)/../Install"
cmake --build . --config Release --target install

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 11
  • 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.

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-2020 © Evgeny Gorodetskiy