Vid Engine

Graphics engine written in Metal & Swift.

It's an endless work-in-progress that I use in my spare to test things. It should be usable to do basic stuff, but note that there are no plans for OpenGL ES support, and thus, both older devices and the simulators are not supported. You will need a Metal-compatible iOS device to build and run it.

Installation

Simply add this repository as a submodule in your repository,

git submodule add [email protected]:endavid/VidEngine.git VidEngine

Then,

• Create a Workspace in Xcode
• Add your project to the workspace
  • An easy way to start is to create a Single View App from the iOS templates (File → New → Project).
  • Under Target → Build Phases, add MetalKit.framework to Link binary with libraries section.
  • Open Main.storyboard, select the View, and select MTKView class in the Identity inspector.
• Add VidFramework project to the workspace: Add Files → select xcodeproj file.
  • If you want to check the shaders, also add VidMetalLib to your workspace. But note that at the moment, you need to build the shader libraries from the console (see Build section).
  • I would also add a sample app to your workspace. For instance, if you want to create an AR app, add SampleAR to your workspace.
• Select your project in Xcode, and in Target → General → Embedded Binaries, select VidFramework (it should appear if it's in your workspace). This should also add it to Linked Framework & Libraries. But if it doesn't, add it there as well. Also make sure it did add an entry in Build Phases → Embed Frameworks.

Build

Use the provided build.sh, because I can't figure out how to get the shaders in VidMetalLib to get linked to the correct location from Xcode... 😅

App Configuration

Info.plist

This engine is Metal-only, so that needs to be specified as a requirement in your Info.plist. If you are going to use AR, you will also need to include arkit to the list. Your Info.plist should have this section,

<key>UIRequiredDeviceCapabilities</key>
<array>
<string>armv7</string>
<string>metal</string>
<string>arkit</string>
</array>

Overview

3D rendering

Vid Engine uses a right-handed coordinate system, with Y being the vertical direction. The camera looks to -Z by default. That means that +Z points towards the screen, and +X towards the right side of the screen. Units are given in meters by default. Therefore, both coordinate system and units match ARKit, so working with AR scene should be straightforward.

Samples

Open the VidWorkspace and you should see several samples.

SampleAR

ARKit sample app using the VidEngine.

Details in these posts:

• Spherical Harmonics Lighting from ARKit Environment Probes
• How to combine Render Command Encoders that use a different shader in Metal

SampleColorPalette

Example of using display-P3 color space, and Self-Organizing Maps (a type of neural network).

Read these blog posts:

• Display P3 vs sRGB in Color Palettes
• Exploring the display-P3 color space

Also, this sample has been expanded into a full app: Palettist

SampleCornellBox

This is just the typical cornell box scene (WIP)

SampleRain

Very simple procedural 2D rain. All the updates happen in the GPU with a compute shader. You can read about it in this blog post: Metal: a Swift Introduction

If you need a more minimalistic example, find the rain-demo tag in git history.

SampleText

This demonstrates the support of font rendering in the 3D world using Signed-Distance Fields.

GPU Quaternions performance tests

You need to find these tags in the commit history:

instanced-spheres-quaternions
instanced-sphere-matrices
instanced-cubes-quaternions
instanced-cubes-matrices
cubes-demo-quaternions
cubes-demo-matrices

Just examples of instancing and GPU quaternions. Read about it in detail in this blog post: Performance of quaternions in the GPU

License

MIT License. Please let me know if you use this in any of your projects.