Copyright (c) 2014-2016 The Brenwill Workshop Ltd. All rights reserved.
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, 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.
VulkanSamples
LibraryTo 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
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.
A basic textured triangle, and varies the depth range over time, to provide a sweeping effect that slowly erases part of the triangle, and then replaces it.
To run this demo, run either the Triangle-iOS
or Triangle-macOS
Scheme from within Xcode.
A basic textured cube that spins in place.
To run this demo, run either the Cube-iOS
or Cube-macOS
Scheme from within Xcode.
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 theAPI-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.
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, 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.
Vulkan-Samples
LibraryTo 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
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 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.
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
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.