Prerequisites

Argo for iOS makes it easy to use volumetric content, but here are some aspects of iOS development you should be familiar with.

  • Xcode for developing apps. We currently require Xcode 9.1.
  • UIKit for managing UI
  • Carthage for dependency management
  • a basic knowledge of SceneKit will be useful for the manipulation of 3D assets

If you get stuck you can download the finished project from Argo-iOSExample.zip. The HVRS file and audio file that are used in this tutorial can be found in this project too.

Installation

Setup

Create a new Xcode project using the Single View App template.

We distribute Argo using Carthage, a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

In the same folder as your .xcodeproj file, create a text file called Cartfile. Add this line to the file then save:

binary "https://d7cvc31wlmbhf.cloudfront.net/8i+Website/Dev+Portal/Downloads/Argo-iOS-CarthageBinary.json" ~> 0.1

Usage

Configure your Xcode project

  1. Build your Carthage dependencies. Open Terminal and cd to the directory containing your Cartfile. Run this command:
$ carthage update --platform iOS
  1. Select your app target in Xcode. Select the General tab. From Finder, drag the ArgoKit.framework from Carthage/Build/iOS/ into the Embedded Binaries section. Do not select 'Copy items if needed'.
  2. There is also a framework within the ArgoKit framework that also needs to be added: HVRPlayerInterface.framework. Drag that into the Embedded Binaries section as well.
  3. Select your app target, and go to Build Phases.
  4. Add a 'New Run Script Phase'. Rename it 'Carthage'.
  5. Add $(SRCROOT)/Carthage/Build/iOS/ArgoKit.framework to Input Files
  6. Add $(SRCROOT)/Carthage/Build/iOS/ArgoKit.framework/HVRPlayerInterface.framework to Input Files
  7. Add $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ArgoKit.framework to Output Files
  8. Add $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/HVRPlayerInterface.framework to Output Files
  9. Finally, in Build Settings set Enable Bitcode to No.

Make sure everything builds. Find the app in the Products folder in the Xcode project navigator. Right-click, select Show in Finder. Right-click the app in Finder and select Show Package Contents. Open the Frameworks folder and ensure that the ArgoKit and HVRPlayerInterface frameworks are there.

Set up SceneKit

Now you're ready to start adding ArgoKit to your code.

import UIKit
import SceneKit // 3
import ArgoKit // 3

class ViewController: UIViewController {

    @IBOutlet weak var sceneView: SCNView! // 4
    var rendererDelegate: ArgoSceneRendererDelegate = ArgoSceneRendererDelegate() // 5
    
    override func viewDidLoad() {
        super.viewDidLoad()

        sceneView.delegate = rendererDelegate // 6
        sceneView.eaglContext = EAGLContext(api: .openGLES3) // 7
        sceneView.isPlaying = true // 8
    }
}
  1. In your Storyboard's view controller add a SceneKit SCNView.
  2. In the Attributes Inspector select the OpenGL ES Rendering API.
  3. Import SceneKit and ArgoKit into the view controller.
  4. In your view controller create a SCNView property and connect this to the SCNView in Interface Builder.
  5. SCNView uses a rendering delegate to perform custom rendering options. Argo for iOS provides a convenience class, ArgoSceneRendererDelegate, for you to use. Add a property to the ViewController for the ArgoSceneRendererDelegate.
  6. In viewDidLoad, set the SCNView's delegate to use this convenience class.
  7. Specify SCNView's context to use .openGLES3.
  8. To make sure things work later, make sure that the sceneView isPlaying property is true.
This version of Argo for iOS uses OpenGL ES 3 for rendering.

Setup the scene

Add the assets you'll be using for the HVRS and audio playback.

  1. Drag the Wrestler.hvrs file from Finder into your project. Make sure to select 'Copy files if needed'.
  2. Drag the Wrestler.wav file from Finder into your project. Make sure to select 'Copy files if needed'.
  3. In the Build Phases of your app's Target, add both files to the 'Copy Bundle Resources' section so that they are copied to your app during building.

Next, the HVRS file and the audio file will be used to create a node that can be added to the scene. Add a new property to your scene to hold our hologram.

lazy var hologramNode: SCNNode = { // 1

    let hvrFilePath = Bundle.main.path(forResource: "Wrestler", ofType: "hvrs")! // 2
    let wavFilePath = Bundle.main.path(forResource: "Wrestler", ofType: "wav")! // 3

    let argonaut = Argonaut(name: "myAsset", hvrPath: hvrFilePath, audioPath: wavFilePath) // 4
    let node = Argo.argoNode(argonaut: argonaut)! // 5

    return node
}()
  1. Create a lazy property to return an ArgoKit scene node.
  2. Get the path of the HVRS file in the bundle.
  3. Get the path of the audio file in the bundle.
  4. Create the Argonaut used to create a node and manipulate the playback state of the actor.
  5. Create the ArgoNode.

SceneKit needs a few more things before you can see the hologram. First up, an SCNCamera.

lazy var cameraNode: SCNNode = {

    let node = SCNNode()
    var camera = SCNCamera()
    camera.fieldOfView = 40
    node.camera = camera
    node.position = SCNVector3(0, 1.2, 2)

    return node
}()

Now, a scene can be composed with these components in viewDidLoad.

let scene = SCNScene() // 1
scene.rootNode.addChildNode(cameraNode) // 2
scene.rootNode.addChildNode(hologramNode) // 3

cameraNode.look(at: SCNVector3(0.0, 1.2, 0.0)) // 4

sceneView.scene = scene // 5
  1. Create a scene
  2. Add the camera node
  3. Add the actor node
  4. Ensure the camera is looking at the actor node
  5. Set the SCNView's scene

Run the app and you should see the actor in front of the camera. But the actor is not moving and there's no audio. That will be fixed next.

Playback

ArgoNode overrides the isPaused property of a SCNNode to enable basic playback.

In the hologramNode lazy property set hologramNode.isPaused = false.

Run the app. The actor should be performing with the audio file playing in the background.

By default, isPaused will loop HVR and audio playback continuously. It is possible to stop at the end of the video.