8i Unity Plugin Documentation¶

Parameters¶

Parameters¶

Limitations¶

• Directional Lights are only supported in Unity 2017.2 and greater
• Directional Lights shadow casting is not supported in the Unity Editor’s Scene View
• HvrLights under point light will have shadow artifacts prior to Unity 5.6
• Some mobile devices will have limited shadow casting support

Parameters¶

Parameters¶

Writing Shader Subroutines¶

Unlike Unity’s ShaderLab shaders, shader subroutines are not automatically converted to work for every BuildTarget. Shader subroutines must be written for each Graphics API that the effect needs to work on.

The current supported shader languages are GLSL, HLSL and Metal.

BEGIN_GLSL_VERTEX
    # Code
END_GLSL_VERTEX

BEGIN_GLSL_FRAGMENT
    # Code
END_GLSL_FRAGMENT

BEGIN_HLSL_VERTEX
    # Code
END_HLSL_VERTEX

BEGIN_METAL_VERTEX
    # Code
END_METAL_VERTEX

BEGIN_GLSL_VERTEX(CalcVertexColour, CalcVertexPosition, CalcVertexScale)

    // Control colour
    vec4 CalcVertexColour(vec4 colour : VERTEX_COLOUR, vec4 oPos : OPOS) : VERTEX_COLOUR
    {
        // Example: This makes the colour darker.
        // The 'oPos' parameter is not used in this example,
        // but could be included in the calculation, i.e. to modify
        // the colour based on the position.
        return vec4(0.5 * colour.rgb, colour.a);
    }

    // Control position
    vec4 CalcVertexPosition(vec4 oPos : OPOS) : OPOS
    {
        // Example: This moves the vertex vertically upwards.
        return vec4(oPos.x, oPos.y + 1.0, oPos.z, oPos.w);
    }

    // Control scale
    float CalcVertexScale(float scale : VOXEL_SCALE) : VOXEL_SCALE
    {
        // Example: This doubles the vertex size.
        return 2.0 * scale;
    }

END_GLSL_VERTEX

uniform float _<ID>CurrentTime;

cbuffer _<ID>ShaderParams
{
    float _<ID>CurrentTime;
}

struct _<ID>ShaderParams
{
    float _<ID>CurrentTime;
};

float4 CalcVertexColour(float4 colour : VERTEX_COLOUR, _<ID>ShaderParams uniforms : SHADER_UNIFORMS) : VERTEX_COLOUR
{
    return float4(colour.rgb * (sin(uniforms._<ID>CurrentTime) * 0.5 + 0.5), colour.a);
}

struct _<ID>ShaderTextures
{
    texture2d<float> _<ID>RGLookupTable;
};

float4 CalcVertexColour(float4 colour : VERTEX_COLOUR, _<ID>ShaderTextures textures : SHADER_TEXTURES) : VERTEX_COLOUR
{
    // Uses the R and G components of the original colour as texture coordinates.
    constexpr sampler textureSampler(mag_filter::linear, min_filter::linear);
    return textures._<ID>RGLookupTable.sample(textureSampler, colour.rg);
}

BEGIN_GLSL_VERTEX(VertexColor)

    uniform float _<ID>Saturation;

    float <ID>Luminance(vec3 c)
    {
        return dot(c, vec3(0.22, 0.707, 0.071));
    }

    vec4 CalcVertexColour(vec4 colour : VERTEX_COLOUR, vec4 oPos : OPOS) : VERTEX_COLOUR
    {
        float luminance = <ID>Luminance(colour.rgb);
        colour.r = lerp(colour.r, luminance, _<ID>Saturation);
        colour.g = lerp(colour.g, luminance, _<ID>Saturation);
        colour.b = lerp(colour.b, luminance, _<ID>Saturation);
        return colour;
    }

END_GLSL_VERTEX

Examples¶

Example 1

Set all voxels to be blue

BEGIN_GLSL_VERTEX(SetVertexColour)
    vec4 SetVertexColour(vec4 colour : VERTEX_COLOUR, vec4 oPos : OPOS) : VERTEX_COLOUR
    {
        colour.rgb = vec3(0, 0, 1);
        return colour;
    }
END_GLSL_VERTEX

BEGIN_HLSL_VERTEX(SetVertexColour)
    float4 SetVertexColour(float4 colour : VERTEX_COLOUR, float4 oPos : OPOS) : VERTEX_COLOUR
    {
        colour.rgb = float3(0, 0, 1);
        return colour;
    }
END_HLSL_VERTEX

BEGIN_METAL_VERTEX(SetVertexColour)
    float4 SetVertexColour(float4 colour : VERTEX_COLOUR) : VERTEX_COLOUR
    {
        colour.rgb = float3(0, 0, 1);
        return colour;
    }
END_METAL_VERTEX

Example 2

Offset the position of all vertices vertically

BEGIN_GLSL_VERTEX(SetVertexPosition)
    vec4 SetVertexPosition(vec4 oPos : OPOS) : OPOS
    {
        if (oPos.y > 100)
            oPos.y += 30;
        return oPos;
    }
END_GLSL_VERTEX

BEGIN_HLSL_VERTEX(SetVertexPosition)
    float4 SetVertexPosition(float4 oPos : OPOS) : OPOS
    {
        if (oPos.y > 100)
            oPos.y += 30;
        return oPos;
    }
END_HLSL_VERTEX

BEGIN_METAL_VERTEX(SetVertexPosition)
    float4 SetVertexPosition(float4 oPos : OPOS) : OPOS
    {
        if (oPos.y > 100)
            oPos.y += 30;
        return oPos;
    }
END_METAL_VERTEX

Example 3

The following sets the color of all voxels to be blue, and sets their scale to 0 if they are below 1m in the data’s object space.

BEGIN_GLSL_VERTEX(SetVertexColour, SetVertexScale)

    vec4 SetVertexScale(float scale : VOXEL_SCALE, vec4 oPos : OPOS) : VOXEL_SCALE
    {
        if (oPos.y < 100)
            return 0;
        return scale;
    }

    vec4 SetVertexColour(vec4 colour : VERTEX_COLOUR, vec4 oPos : OPOS) : VERTEX_COLOUR
    {
        colour.rgb = vec3(0, 0, 1);
        return colour;
    }
    END_GLSL_VERTEX

BEGIN_HLSL_VERTEX(SetVertexColour, SetVertexScale)

    float4 SetVertexScale(float scale : VOXEL_SCALE, float4 oPos : OPOS) : VOXEL_SCALE
    {
        if (oPos.y < 100)
            return 0;
        return scale;
    }

    float4 SetVertexColour(float4 colour : VERTEX_COLOUR, float4 oPos : OPOS) : VERTEX_COLOUR
    {
        colour.rgb = float3(0, 0, 1);
        return colour;
    }

END_HLSL_VERTEX

BEGIN_METAL_VERTEX(SetVertexColour, SetVertexScale)

    float4 SetVertexScale(float scale : VOXEL_SCALE, float4 oPos : OPOS) : VOXEL_SCALE
    {
        if (oPos.y < 100)
            return 0;
        return scale;
    }

    float4 SetVertexColour(float4 colour : VERTEX_COLOUR) : VERTEX_COLOUR
    {
        colour.rgb = float3(0, 0, 1);
        return colour;
    }

END_METAL_VERTEX

Parameters¶

Parameters¶

Parameters¶

HvrDataBuildInclude¶

The HvrDataBuildInclude is a component which a HvrDataReference can be assigned to.

To use this component, attach it to a GameObject within your scene and assign a HvrDataReference to the ‘Data Reference’ slot.

HvrDataReference¶

The HvrDataReference contains an list of references to files or folders from your project.

It can be created by either opening the ‘Assets’ menu at the top of the screen, or in the ‘Create’ context menu when right clicking in your Project window and navigating to ‘Create/8i/HvrDataReference’

To add a reference to the List

• Click the ‘Plus’ icon in the bottom right.
• Drag and Drop a file or folder from your project into the ‘Data’ slot OR click the circle icon to open a window to search your entire project.

Because the references are created using Unity’s project GUID system moving any referenced files and folders will not break the reference.

Parameters¶

• AsgardLiveShowUrl: The URL to monitor for live stream status changes
• CheckStatePeriod: How often to check the URL when the stream is inactive
• onStreamActiveChanged: Callback invoked when the stream status changes
• Active: Enable to allow the Manager to make network requests and begin playback as needed.

Properties¶

• bitrate: The maximum per-second bitrate of the sub-stream, meant to be used in PatAsset.SelectRepresentation
• id: string describing a given representation
• fps: framerate of the representation, when multiple framerates are present

Parameters¶

Parameters¶

• AsgardUrl: The URL to monitor for live stream status changes, which is passed in to PatLiveManager
• PatActorPrefab: Should be set to the provided PatActor.prefab

Prerequisites¶

• iOS devices that support ARKit and Metal and run iOS 11.3 or later, see here,
  • ARKit 2.0 requires a device with iOS 12 installed
• Mac installed latest macOS
• Unity 2017.1 or later
• Xcode 9.3 or later
  • Command line tools installed, see here.
  • ARKit 2.0 requires Xcode 10 or later
• Get a high level idea of how AR works on iOS from Apple’s documentation.

Getting Unity ARKit plugin¶

Go to https://bitbucket.org/Unity-Technologies/unity-arkit-plugin and download the official Unity ARKit plugin. You might need to install Mercurial or SourceTree to grab the source.

Switch to 1.5.1 tag if you want it to run on iOS 11 devices. Here’s how you do it in SourceTree but could be different if you use other Mercurial client:

Importing 8i Unity Plugin¶

Within the downloaded project, extract 8i Unity Plugin into the Asset folder, as stated in Quick Start section.

You should have the directory structure like this:

Configure the Unity Project¶

Open the project in Unity

If you are prompted to upgrade the Unity version, click yes.

Select File > Build Settings, a build dialogue should come up. In Platform choose iOS and click Switch Platform button.

Make sure the Platform is switched to iOS, and choose one of the scene as into the build. In this tutorial, we checked the simplest scene UnityARBallz.

Still in Build Settings dialogue, click Player Settings… button.

A PlayerSettings inspector should appear.

Make sure Metal is listed as the first in Graphics APIs and disable Metal Editor Support

Your First 8i Hologram¶

For this tutorial, we will edit the UnityARBallZ scene from Unity ARKit plugin’s example.

We will change the original AR object to 8i’s hologram, so that you can place a human hologram onto the augmented world.

To open the scene, find the scene in project and double click the scene.

You should be able to see something like this in Scene view:

This scene is a barebone template of an AR app and all it does is to automatically detect the environment and track the movement of the device and tie it to the virtual Camera object.

Select menu GameObject > 8i > HvrActor. This will create an GameObject with a HvrActor component attached to it.

Select the newly created HvrActor object.

There are a few options to note but for now we will just focus on the Asset/Data/Reference field.

This is the data source that 8i’s hologram engine will read from. As you can see, right now it’s empty. To specify a valid file reference, we can go to folder 8i/examples/assets/hvr, and find “president” folder:

Drag this “president” folder to Asset/Data/Reference field in Inspector panel. To make things even simpler, uncheck the Rendering/Lighting/Use Lighting checkbox:

You should be able to see the hologram has already been shown in the Scene view:

Making A Prefab¶

Because we want our user be able to drop the hologram whenever he touches the ground, we need to wrap this HvrActor object into a called “prefab” and let our ARKit code know to use it.

Making sure HvrActor is currently selected, drag the HvrActor object down to a folder in the Project window, Unity will automatically create a prefab for you, and you will see the name of HvrActor turns blue:

To change the ARKit code to spawn HvrActor*s instead of balls, find *BallMaker object in the scene and select it. Drag the newly created prefab HvrActor to BallMaker’s Inspector panel, replace BallPrefab with HvrActor:

Because we have stored the HvrActor in a prefab it is now safe to delete the HvrActor in the scene. Go to Hierarchy and right click on HvrActor, which should has its name in blue colour, and choose “Delete”.

Save the scene by pressing Cmd+S.

Camera Configuration¶

Next we need to configure the camera to let it render 8i’s hologram.

Find the camera object in Hierarchy > CameraParent > Main Camera and select it.

With Main Camera seleced, In menu choose Component > 8i > HvrRender, this should add a HvrRender component to the camera:

Save the scene by pressing Cmd+S.

Include HVR Data¶

Before we can build the project, there’s an extra step to do. Because we are using a prefab which means it will be dynamically loaded. We need to explicitly tell Unity to include the data before exporting.

First, right click on the Project window and create an asset of type HvrDataReference. You do it through Create > 8i > HvrDataReference.

After creation, select the asset. Drag the president folder to its data field.

Now we have created and configured the asset on disk. Now we need to include this asset in our scene. Right click in Hierarchy window and create an empty GameObject.

With the empty object selected, attach a component of type HvrDataBuildInclude. You can find it in Component > 8i > HvrDataBuildInclude.

Finally drag the configured HvrDataReference asset to Data Reference field.

Save the scene.

Export and Build¶

That’s it! It’s time to export Xcode project and deploy it to the device.

• Menu File > Build Settings, click Player Settings and make sure Metal is the first listed in the Inspector window.

• Click Build, select a folder to export the project. If everything went smooth, a Finder window should pop up and shows the exported Xcode project.

• Double click Unity-iPhone.xcodeproj and this should bring up Xcode.

• Configure Xcode project as follows. You need to pay attention to code signing if you are new to it.

• After configuration, hit run:

  

• Once the build is deployed and running, pick up your phone and walk around until a magenta ground is shown, which means you can put your holograms on.

• Tap the magenta ground to see how hologram works within AR world.

Where to go from now on¶

• Check out our documentation on all the Components and how they interact with each other.
• Take a look at Apple HIG on AR: https://developer.apple.com/design/human-interface-guidelines/ios/system-capabilities/augmented-reality/.
• Download 8i holograms from https://8i.com/developers/downloads/.

Prerequisites¶

• A walkthrough of Google ARCore Quickstart,
• An ARCore enabled Android device
• Unity 2017.4.9f1 or later with Android Build Support
  • Note Unity 2018.2 has an known bug with Android render target, so it’s not supported. See bug tracking here.
• Android SDK 7.0 (API Level 24) or later
• Accept all the licenses from Android SDK. For example, if you are on macOS:
  • $ cd ~/Library/Android/sdk/tools/bin
  • $ ./sdkmanager –licenses
  • Accept all the licenses.

Getting ARCore SDK for Unity¶

Download ARCore SDK for Unity 1.4.0 or later

Open Unity and create a new empty 3D project

Select Assets > Import Package > Custom Package, use the downloaded arcore-unity-sdk-v1.4.0.unitypackage from your disk.

In the import dialogue, make sure everything is selected and click Import.

Accept any API upgrades if prompted.

Importing 8i Unity Plugin¶

Within the newly created project, extract 8i Unity Plugin into the Asset folder, as stated in Quick Start section.

You should have the directory structure like this:

Fix any warning poped up in 8i Project Tips window, including Android Unpack Scene.

Configure the Unity Project¶

Open the project in Unity

If you are prompted to upgrade the Unity version, click yes.

Open scene HelloAR by double clicking Assets/GoogleARCore/Examples/HelloAR/Scenes/HelloAR

Select File > Build Settings, a build dialogue should come up. click Player Settings… button. A PlayerSettings inspector should appear. In the Inspector window, find Other Settings - Metal Editor Support and unchecked it. This is important for Unity previewing 8i’s hologram content.

Still in Build Settings dialogue, in Platform choose Android and click Switch Platform button.

Make sure the Platform is switched to Android, and make sure HelloAR scene is ticked on by using Add Open Scenes.

Still in Build Settings dialogue, click Player Settings… button. A PlayerSettings inspector should appear. In the Inspector window, a few fields need to be configured:

• Other Settings - Package Name: set to an reversed DNS like name, e.g. com.yourcompany.arsample

• Other Settings - Uncheck Auto Graphics API and explicitly set OpenGL ES 3 as the graphics API

• Other Settings - Multithreaded Rendering: uncheck

• Other Settings - Minimal API Level: set to Android 7.0 or higher. Note you need to have the right version of Android SDK installed and configured in Unity > Preference.

• Other Settings - Target API Level: set to Android 7.0 or higher. Note you need to have the right version of Android SDK installed and configured in Unity > Preference.

  

• XR Settings - ARCore Supported: tick on

  

Your First 8i Hologram¶

For this tutorial, we will edit the HelloAR scene from Google ARCore SDK for Unity’s example.

W will change the original AR object to 8i’s hologram, so that you can place a human hologram onto the augmented world.

To open the scene, find the scene in project and double click the scene.

Select menu GameObject > 8i > HvrActor. This will create an GameObject with a HvrActor component attached to it.

Select the newly created HvrActor object.

There are a few options to note but for now we will just focus on the Asset/Data/Reference field.

This is the data source that 8i’s hologram engine will read from. As you can see, right now it’s empty. To specify a valid file reference, we can go to folder 8i/examples/assets/hvr, and find “president” folder:

Drag this “president” folder to Asset/Data/Reference field in Inspector panel. To make things even simpler, uncheck the Rendering/Lighting/Use Lighting checkbox:

You should be able to see the hologram has already been shown in the Scene view:

Making A Prefab¶

Because we want our user be able to drop the hologram whenever he touches the ground, we need to wrap this HvrActor object into a called “prefab” and let our ARKit code know to use it.

Making sure HvrActor is currently selected, drag the HvrActor object down to a folder in the Project window, Unity will automatically create a prefab for you, and you will see the name of HvrActor turns blue:

To change the HelloAR scene to spawn HvrActor instead of Andy Android, find Example Controller object in the scene and select it. Drag the newly created prefab HvrActor to Example Controller’s Inspector panel, replace Andy Plane Prefab and Andy Point Prefab with HvrActor:

Because we have stored the HvrActor in a prefab it is now safe to delete the HvrActor in the scene. Go to Hierarchy and right click on HvrActor, which should has its name in blue colour, and choose “Delete”.

Save the scene by pressing Cmd+S.

Camera Configuration¶

Next we need to configure the camera to let it render 8i’s hologram.

Find the camera object in Hierarchy > CameraParent > Main Camera and select it.

With First Person Camera seleced, In menu choose Component > 8i > HvrRender, this should add a HvrRender component to the camera:

Save the scene by pressing Cmd+S.

Include HVR Data¶

Before we can build the project, there’s an extra step to do. Because we are using a prefab which means it will be dynamically loaded. We need to explicitly tell Unity to include the data before exporting.

First, right click on the Project window and create an asset of type HvrDataReference. You do it through Create > 8i > HvrDataReference.

After creation, select the asset. Drag the president folder to its data field.

Now we have created and configured the asset on disk. Now we need to include this asset in our scene. Right click in Hierarchy window and create an empty GameObject.

With the empty object selected, attach a component of type HvrDataBuildInclude. You can find it in Component > 8i > HvrDataBuildInclude.

Drag the configured HvrDataReference asset to Data Reference field.

Finally, choose from menu 8i > Android > Prepare Build and click OK if a dialogue prompts. This will prepare and bake the content ready to be submit to Android device. Note this is an Android specific process whenever you changed the dynamic loaded 8i content. You don’t have to do it if no 8i content changed between builds.

Save the scene.

Export and Build¶

That’s it! It’s time to build an APK and deploy it to the device.

• Connect your Android phone to your development machine

• Enable developer options and USB debugging on your Android phone. This should be done just once.

• Menu File > Build Settings, click Player Settings.

• Click Build And Run, select a folder to export the APK. If everything went smooth, you should be to see the APK get exported and automatically deployed to device.

  

• Once the build is up and running, pick up your phone and walk around until a magenta ground is shown, which means you can put your holograms on.

• Tap the white grid ground or blue dots to see how hologram works within AR world.

Where to go from now on¶

• Check out our documentation on all the Components and how they interact with each other.
• Take a look at Google Augmented Reality Design Guidelines.
• Download 8i holograms from https://8i.com/developers/downloads/.