Extensions¶
Extensions¶
Extensions are additional components that can be added to the HoloSuite player to extend its functionality. All of the following extensions are provided with the HoloSuite Player package. They can be found in the Add Components menu in the Inspector, under Arcturus. Extensions must be placed on the GameObject containing the HoloSuite Player component.
This page describes the available extensions, how to configure them, and their available events.
The HSP Look At Controller¶
The HSP Look At Controller extension can be used to orient a transform to track another transform at runtime. Typically this script is used for the head retargeting workflow. This enables a volumetric actor to track the scene camera, or another GameObject with their head.
Setup¶
See the Retargeting Setup guide for a step by step walkthrough showing how to set up head retargeting using the HSP Look At Controller.
Parameters¶
Weight: Control the strength of the look at retargeting motion. At 1.0, the look at retargeting motion will be applied completely. At lower values, it will be combined with existing animation through spherical linear interpolation according to the weight value.
Bones: Expand the ‘Bones’ drawer to configure the Bones array:
Size: Specify the number of bones to control
Element: Element fields will be displayed according to the number provided in size. Each Element supplies a transform that will be affected by the script.
Effector: Provide a transform to use as the source for the look-at calculation. This can be the same as your target bone, or any other object. Typically this is a child of your target bone, which can be slightly rotated or translated to provide an offset for eye position and angle.
Forward Vector: Modify the ‘forward’ vector if necessary depending on the orientation of your bones.
Target: Specify the target transform. This is the object the selected bones will look at.
Turn Speed Active: Specify the turn speed for tracking an object in degrees/sec.
Turn Speed Passive: Specify the turn speed used when returning to idle in degrees/sec.
Turn Accel: Rate at which the turn speed increases when locking on to an object.
Twist Axis: Specify the twist (left/right turn, for head retargeting) axis in your bone’s local space.
Swing Axis: Specify the swing (up down tilt, for head retargeting) axis in your bone’s local space.
Twist Max: Max Twist rotation in degrees. Will not rotate further.
Swing Max: Max swing rotation in degrees. Will not rotate further.
Swing Plus Tilt Max: Set a maximum degrees for tilt (ear to shoulder tilt, for head retargeting) when turning the head. Too low of values may produce strange rotations when used on the head.
Swing Max Bias: Bias max swing in one direction or another, in degrees. Negative values bias left, positive values bias right.
Out Of Range Timeout: Set a timer, in seconds, after which the target will return to its idle position when the target is outside of swing/twist range.
The HSP Playback Controller¶
The HSP Playback Controller extension lets you play, pause, and seek the timeline of an OMS file. This can be controlled programmatically, or using the provided Playback Controls Prefab. This is located under Packages > HoloSuite Player > Runtime > Extensions > HSPPlayBackController.
Note
The Seek function of HSP Playback Controller creates texture desyncs when used with the StreamingAsset SourceType. For this reason it is advised to use the Asset SourceType with the HSP Playback Controller.
Setup¶
To set up the HSP Playback Controller, first add the HSP Playback Controller component to your HoloSuite Player GameObject.
Add Extension Component: You can do this using the Add Component button at the bottom of the inspector. It is located under Arcturus > HSP Playback Controller.
Add UI Prefab: Next drag the Playback Controls prefab from Packages > HoloSuite Player > Runtime > Extensions > HSPPlaybackController into your Hierarchy panel. Once that is loaded into your Hierarchy panel you will need to set that as your UI for the HSP Playback controller. You can do this by dragging that prefab from your Hierarchy panel into the UI field of the HSP Playback Controller in the HoloSuite Player’s inspector panel.
Link UnityEvents: The last step is setting the UnityEvents of the UI to trigger the functions of the HSP Playback Controller. Set all of the events for the below GameObjects. Link an event by selecting a GameObject in the Object field, and a component’s function in the dropdown menu. In this case you will be selecting your HoloSuite Player, then selecting the HSP Playback Controllers function to be triggered. Be sure to select the dynamic version of these functions when specified. The dynamic versions, when available can be found at the top of the function list.
Play/Pause: Found at Playback Controls > Panel > Play/Pause. Set the following events
On Value Changed: Set to the HSPPlaybackController.PlayToggle (dynamic) function.
SeekSlider: Found at Playback Controls > Panel > SeekSlider Set the follow events.
On Value Changed: Set to the HSPPlaybackController.SeekTime (dynamic) function.
On Click End: Set to the HSPPlaybackController.SyncWithPlayButton function.
Now that you have the HSP Playback Controller configured, you can click play on your scene, and you will see the play head advancing in accordance with the playback of your clip.
Configure to control multiple HoloSuite Players¶
In order to control more then one HoloSuite Player with the same playback control UI, Each HoloSuite Player will need the HSP Playback Controller extension. When linking the Unity events as instructed above, set the events for all HoloSuite Players you would like to control. To add an additional function to a UnityEvent, just click the + symbol at the bottom right of that UnityEvent.
Parameters¶
UI: This field accepts a GameObject containing the UI Canvas for the playback UI. The default UI prefab is located at Packages > HoloSuite Player > Runtime > Extensions > HSPPlayBackController > Playback Controls. To create a custom prefab, right click on the Playback Controls prefab and select the Create > Prefab Variant option. This will create a copy of the initial prefab that can be customized to your liking.
Time Display Type: Sets the type of time display used to the right of the seek bar.
None: The time display will be removed.
Playtime: Shows the current playtime of the clip.
Remainder: Shows the time remaining in the clip.
Events¶
The HSP Playback Controller has three events you can use to trigger functions in your scene.
On Playback Start: This triggers when playback of the OMS starts for the first time. It will not trigger again on successive loops.
On Playback End: This triggers when the playback of the OMS ends.
On Clip Looped: This triggers when the clips playback loops.
Functions¶
The HSP Playback Controller makes it easy to programmatically tap into the HoloSuite Player to control playback. The following functions are available for this purpose.
Play(): Plays the clip.
Pause(): Pauses the clip.
PlayToggle(bool): Set the play/pause state with a bool. true = play, false = pause.
Stop(): Stops the playback of the clip.
Seek(float): Seeks to a fraction of the overall playtime. 0 = start, 1 = end.
SeekTime(float): Seeks to a particular time in the clip. Input the desired seek time in seconds.
SeekFrame(float): Seeks to a particular frame in the clip. Input the desired frame index.
SyncWithPlayButton(): Sets the playback state of the clip to match the PlayButton. This ensures the playback state matches the UI.
Note
When using any of the seek functions to seek the player, It is advised to call the SyncWithPlayButton() function when you are done seeking. This will restore the playstate that was active before seeking began.
HSP Timeline Controller¶
The HSP Timeline Controller extension lets you drive a timeline based off of the current play time of the HoloSuite Player. This extension will not let you drive the HoloSuite Players playback time from a timeline.
Setup¶
To set up the HSP Timeline Controller, first you will need to create a Timeline and animation.
Create Timeline: start by opening the Timeline panel under Window > Sequencing > Timeline. With that panel visible, select the GameObject you are looking to animate with the timeline. With that object selected, you should see a Create button in the center of the Timeline panel. Click create to generate a new playable file. Save this anywhere you like in your project. This will also generate Playable Director and Animator components on the target GameObject.
Create animation: you can create an animation by clicking the record button in the timeline, and adjusting a parameter of the target GameObject. This will create a start keyframe. Next move the play head in the Timeline to a new location, and adjust that parameter again, to create another keyframe. Repeat this until you have created your desired animation. When you are finished, click the record button again to save the animation. You should now be able to play the scene, and see your animation take place. Now that you have your Timeline set up, and an animation created, all that is left to do is to drive this Timeline from the HSP Timeline Controller.
Drive Timeline: Select your HoloSuite Player GameObject, and add the HSP Timeline Controller under Add Component > Arcturus. Once that is added to your HoloSuite Player, check its Drive Timeline box. Lastly either drag the GameObject you animated from your Hierarchy panel to the Timeline field on the HSP Timeline Controller, or click the target button on that field, and select that GameObject.
Now that the HSP Timeline Controller is configured to drive your Timeline. The animation you created will playback in step with your HoloSuite player.
Parameters¶
Drive Timeline: This checkbox enables or disables driving the timeline using the HoloSuite Player.
Timeline: Set this to the Playable Director associated with your Timeline. Dragging in the GameObject containing the Playable Director will also populate this field.