MoltenVK 0.16.0 Demo Projects

Introduction
LunarG Vulkan Samples
Khronos Vulkan Samples
- Installing the Khronos Vulkan-Samples Library
- AsynchronousTimeWarp
Cinder Vulkan Samples
- Installing the Cinder Library
- Fish Tornado

Introduction

The Xcode projects in this folder are a set of demo applications that demonstrate how to integrate Vulkan into an Xcode project, and demonstrate the features and capabilities of Vulkan when using using MoltenVK on the iOS and macOS platforms.

Although the demo projects are provided with this MoltenVK distribution, the source code and resources for the demo applications come from publicly-available open-source repositories. Follow the instructions for each section below to learn how to download the demo application source code and resources for each set of demo applications.

To review and run all of the available demo apps, open the Demos.xcworkspace Xcode workspace in Xcode.

LunarG Vulkan Samples

LunarG, who have been involved in Vulkan development from the beginning, and are one of the original developers of Vulkan tools and SDK's, provides a suite of demo apps, that demonstrate a wide range of basic Vulkan features.

These demo apps can be found in the LunarG-VulkanSamples folder of this Demos folder, and in the LunarG-VulkanSamples group in the Xcode Project Navigator in the Demos.xcworkspace Xcode workspace.

These MoltenVK demos use a modified version of the LunarG Vulkan Samples, that allows the demo apps to run under iOS and macOS. To download these modified LunarG Vulkan Samples, and link them to the demo Xcode projects in this Molten distribution, follow the instructions in the Installing the LunarG VulkanSamples Library section next.

Installing the LunarG `VulkanSamples` Library

To run the LunarG Vulkan Samples demo apps, MoltenVK uses a modified version of the LunarG VulkanSamples library. To install this modified LunarG VulkanSamples library, open a Terminal session and perform the following command-line steps:

In a folder outside this Molten distribution, clone the modified VulkanSamples repo:
```
git clone https://github.com/brenwill/VulkanSamples.git
```
In the LunarG-VulkanSamples folder, replace the VulkanSamples symlink as follows:
```
rm VulkanSamples
ln -s path-to-VulkanSamples-repo-folder VulkanSamples
```

Run the MoltenShaderConverter tool to convert the GLSL shaders in the VulkanSamples library to SPIR-V:

MoltenShaderConverter/Tools/MoltenShaderConverter -gi -so -xs "-" -d path-to-VulkanSamples-repo-folder/demos

LunarG Vulkan Samples: Demos

These demos are a pair of simple renderings, that originally were included in the Vulkan SDK.

These demos can be found in the LunarG-VulkanSamples/Demos folder, and in the LunarG-VulkanSamples/Demos group in the Xcode Project Navigator in the Demos.xcworkspace Xcode workspace.

Cube

A basic textured cube that spins in place.

To run this demo, run either the Cube-iOS or Cube-macOS Scheme from within Xcode.

The Cube-macOS demo is a simple example of installing MoltenVK as a dynamic library embedded within an application.

LunarG Vulkan Samples: API-Samples

This Xcode project actually contains a large number of modular demos, with each demo demonstrating a particular Vulkan feature, or suite of calls.

Note: For simplicity, the API-Samples demos are bare-bones. Each of the API-Samples demos renders a single frame during app startup, and then leaves the rendered image static. There is no display loop or motion in any of these demos, including the MoltenVK license watermark. This is normal for these demos, and the demo has not "hung" or "crashed" when this occurs.

This demo can be found in the LunarG-VulkanSamples/API-Samples folder, and in the LunarG-VulkanSamples/API-Samples group in the Xcode Project Navigator in the Demos.xcworkspace Xcode workspace.

To run this demo, run either the API-Samples-iOS or API-Samples-macOS Scheme from within Xcode.

To specify which of the many modular demos to run, open the Samples.h in the API-Samples project in the Xcode Project Navigator in the Demos.xcworkspace Xcode workspace, and follow the instructions in the comments within that file.

To see descriptions and screenshots of each of the demos, open this summary document, after you have installed the LunarG Vulkan Samples repository.

LunarG Vulkan Samples: Hologram

Note: In order to build the Hologram demo, you must have Python3 installed on your build computer.

This is a sophisticated particle demo that populates command buffers from multiple threads.

This demo can be found in the LunarG-VulkanSamples/Hologram folder, and in the LunarG-VulkanSamples/Hologram group in the Xcode Project Navigator in the Demos.xcworkspace Xcode workspace.

The Hologram demo currently only runs on macOS, as the iOS implementation of Metal is missing needed rendering functionality. To run this demo, run the Hologram-macOS Scheme from within Xcode. To see the effect of running this demo on iOS, complete with rendering errors, run the Hologram-iOS Scheme from within Xcode.

On macOS, once the demo is open, you can use the Up-arrow and Down-arrow keys on the keyboard to zoom the camera in and out of the scene. Zooming out will show more items on screen.

The demo allows some customization, by modifying the arguments passed to the demo at startup. To customize, modify the arguments created in the DemoViewController viewDidLoad method found in the iOS/DemoViewController.mm or macOS/DemoViewController.mm file.

Khronos Vulkan Samples

Khronos, the standards organization that developed Vulkan provides a suite of demo apps, that demonstrate a range of sophisticated Vulkan features.

These demo apps can be found in the Khronos-Vulkan-Samples folder of this Demos folder, and in the Khronos-Vulkan-Samples group in the Xcode Project Navigator in the Demos.xcworkspace Xcode workspace.

These MoltenVK demos use a modified version of the Khronos Vulkan Samples, that allows the demo apps to run under iOS and macOS. To download these modified Khronos Vulkan Samples, and link them to the demo Xcode projects in this Molten distribution, follow the instructions in the Installing the Khronos Vulkan-Samples Library section next.

Installing the Khronos `Vulkan-Samples` Library

To run the Khronos Vulkan Samples demo apps, MoltenVK uses a modified version of the Khronos Vulkan-Samples library. To install this modified Khronos Vulkan-Samples library, open a Terminal session and perform the following command-line steps:

In a folder outside this Molten distribution, clone the modified Vulkan-Samples repo:
```
git clone https://github.com/brenwill/Vulkan-Samples.git
```
In the Khronos-Vulkan-Samples folder, replace the Vulkan-Samples symlink as follows:
```
rm Vulkan-Samples
ln -s path-to-Vulkan-Samples-repo-folder Vulkan-Samples
```

Khronos Vulkan Samples: AsynchronousTimeWarp

This demo was contributed by Oculus VR, LLC, and demonstrates a variety of critical tests for evaluating accurate synchronization between the two scene images in a virtual reality headset.

This demo can be found in the Khronos-Vulkan-Samples/AsynchronousTimeWarp folder, and in the Khronos-Vulkan-Samples/AsynchronousTimeWarp group in the Xcode Project Navigator in the Demos.xcworkspace Xcode workspace.

You can make a large number of configuration changes to this demo, to increase or decrease the rendering and computational load of the scene. You can set these configuration values by passing command-line arguments to the demo at start-up. You pass these command-line arguments by setting them in the Arguments tab of the AsynchronousTimeWarp-VK-iOS or AsynchronousTimeWarp-VK-macOS Xcode schemes.

For example, the following command-line arguments can be used to set the scene complexity:

-q [0-3] : controls whether a minimal, small, medium, or large quantity of objects will be rendered.
-w [0-3] : controls whether each object will be rendered with a minimal, small, medium, or large quantity of triangles.
-e [0-3] : controls whether a minimal, small, medium, or large number of lights will be used to illuminate the scene.

On macOS, once the demo is open, you can also tap the Q, W, or E keys on the keyboard to cycle each of these same configuration parameters through their range of possible values.

For the full instructions for this demo, including a list and explanation of all of the configuration options, read the notes at the top of the atw/atw_vulkan.c file.

Cinder Vulkan Samples

Cinder is a cross-platform 3D graphics engine built in C++. Cinder supports Vulkan, and includes several Vulkan demos.

These demo apps are included as part of the Cinder code repository.

These MoltenVK demos use a modified version of Cinder, that allows Vulkan to run under iOS and macOS. To download the modified version of Cinder, and link it to MoltenVK, follow the instructions in the Installing the Cinder Library section next.

Installing the Cinder Library

To run the Cinder Vulkan Samples demo apps, MoltenVK uses a modified version of the Cinder library. To install this modified Cinder library, and link it to MoltenVK, open a Terminal session and perform the following command-line steps:

In a folder outside this Molten distribution, clone the modified Cinder repo, including required submodules:
```
git clone --recursive https://github.com/brenwill/Cinder.git
```
Build the core Cinder library from within the xcode folder in the Cinder repository:
```
cd xcode
./fullbuild.sh
```
In the samples/_vulkan_explicit folder of the Cinder repository, replace the MoltenVK symlink as follows:
```
rm MoltenVK
ln -s path-to-this-Molten-distribution/MoltenVK
```

Cinder Vulkan Samples: Fish Tornado

This is a sophisticated simulation of a Fish Tornado, a swirling school of thousands of fish.

This demo can be found in the samples/_vulkan_explicit/FishTornado folder of the Cinder repository. To build and run this demo for either iOS or macOS, open the xcode-ios/FishTornado.xcodeproj or xcode/FishTornado.xcodeproj Xcode project, respectively.