XRSessionSubsystem.cs
22.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
using System;
using Unity.Collections;
#if UNITY_2020_2_OR_NEWER
using UnityEngine.SubsystemsImplementation;
#endif
namespace UnityEngine.XR.ARSubsystems
{
/// <summary>
/// This subsystem controls the lifecycle of an XR session. Some platforms,
/// particularly those that have non-XR modes, need to be able to turn the
/// session on and off to enter and exit XR mode(s) of operation.
/// </summary>
#if UNITY_2020_2_OR_NEWER
public class XRSessionSubsystem
: SubsystemWithProvider<XRSessionSubsystem, XRSessionSubsystemDescriptor, XRSessionSubsystem.Provider>
#else
public abstract class XRSessionSubsystem
: XRSubsystem<XRSessionSubsystemDescriptor>
#endif
{
/// <summary>
/// Returns an implementation-defined pointer associated with the session.
/// </summary>
public IntPtr nativePtr => provider.nativePtr;
/// <summary>
/// Returns a unique session identifier for this session.
/// </summary>
public Guid sessionId => provider.sessionId;
/// <summary>
/// Asynchronously retrieves the <see cref="SessionAvailability"/>. Used to determine whether
/// the current device supports XR and if the necessary software is installed.
/// </summary>
/// <remarks>
/// This platform-agnostic method is typically implemented by a platform-specific package.
/// </remarks>
/// <returns>A <see cref="Promise{SessionAvailability}"/> which can be used to determine when the
/// availability has been determined and retrieve the result.</returns>
public Promise<SessionAvailability> GetAvailabilityAsync() => provider.GetAvailabilityAsync();
/// <summary>
/// Asynchronously attempts to install XR software on the current device.
/// Throws if <see cref="XRSessionSubsystemDescriptor.supportsInstall"/> is <c>false</c>.
/// </summary>
/// <remarks>
/// This platform-agnostic method is typically implemented by a platform-specific package.
/// </remarks>
/// <returns>A <see cref="Promise{SessionInstallationStatus}"/> which can be used to determine when the
/// installation completes and retrieve the result.</returns>
public Promise<SessionInstallationStatus> InstallAsync()
{
if (!subsystemDescriptor.supportsInstall)
throw new NotSupportedException("InstallAsync is not supported on this platform.");
return provider.InstallAsync();
}
/// <summary>
/// Do not call this directly. Call create on a valid <see cref="XRSessionSubsystemDescriptor"/> instead.
/// </summary>
public XRSessionSubsystem()
{
#if !UNITY_2020_2_OR_NEWER
provider = CreateProvider();
#endif
m_ConfigurationChooser = m_DefaultConfigurationChooser;
}
#if !UNITY_2020_2_OR_NEWER
/// <summary>
/// Starts or resumes the session.
/// </summary>
protected sealed override void OnStart() => provider.Resume();
#endif
/// <summary>
/// Restarts a session. <see cref="OnStop"/> and <see cref="OnStart"/> pause and resume
/// a session, respectively. <c>Restart</c> resets the session state and clears
/// and any detected trackables.
/// </summary>
public void Reset() => provider.Reset();
#if !UNITY_2020_2_OR_NEWER
/// <summary>
/// Pauses the session.
/// </summary>
protected sealed override void OnStop() => provider.Pause();
/// <summary>
/// Destroys the session.
/// </summary>
protected sealed override void OnDestroyed() => provider.Destroy();
#endif
/// <summary>
/// Determines the <see cref="Configuration"/> the session will use given the requested <paramref name="features"/>.
/// </summary>
/// <remarks>
/// <para>
/// This method uses the current <see cref="configurationChooser"/> to choose a configuration using the requested
/// <paramref name="features"/> and the capabilities of the available configurations. The configuration chooser
/// is customizable, see <see cref="ConfigurationChooser"/>. If you do not set a configuration chooser, the
/// <see cref="DefaultConfigurationChooser"/> is used.
/// </para><para>
/// You can use this method to determine what would happen if you were to enable or disable a particular feature.
/// For example, you can use this method to determine which features would be enabled if you were to change the
/// camera mode from <see cref="Feature.WorldFacingCamera"/> to <see cref="Feature.UserFacingCamera"/>.
/// </para>
/// </remarks>
/// <param name="features">A set of requested <see cref="Feature"/>s.</param>
/// <returns>The <see cref="Configuration"/> the session would use given the requested <paramref name="features"/>,
/// or <c>null</c> if configuration introspection is not available.</returns>
/// <seealso cref="Configuration"/>
/// <seealso cref="ConfigurationChooser"/>
/// <seealso cref="ConfigurationDescriptor"/>
/// <seealso cref="Feature"/>
public Configuration? DetermineConfiguration(Feature features)
{
var descriptors = GetConfigurationDescriptors(Allocator.Temp);
if (descriptors.IsCreated)
{
using (descriptors)
{
if (descriptors.Length > 0)
{
#if DEVELOPMENT_BUILD || UNITY_EDITOR
if (m_FirstUpdate)
{
var sb = new System.Text.StringBuilder();
foreach (var descriptor in descriptors)
{
sb.Append($"Configuration Descriptor {HexString(descriptor.identifier)} (rank {descriptor.rank}): {descriptor.capabilities.ToStringList()}\n");
}
Debug.Log(sb.ToString());
m_FirstUpdate = false;
}
#endif
return m_ConfigurationChooser.ChooseConfiguration(descriptors, features);
}
}
}
return null;
}
/// <summary>
/// Trigger the session's update loop.
/// </summary>
/// <param name="updateParams">Data needed by the session to perform its update.</param>
public void Update(XRSessionUpdateParams updateParams)
{
currentConfiguration = DetermineConfiguration(requestedFeatures);
if (currentConfiguration.HasValue)
{
#if DEVELOPMENT_BUILD || UNITY_EDITOR
DebugPrintConfigurationChange(currentConfiguration.Value, requestedFeatures);
#endif
provider.Update(updateParams, currentConfiguration.Value);
}
else
{
provider.Update(updateParams);
}
}
/// <summary>
/// The current <see cref="Configuration"/> in use by the session.
/// </summary>
/// <seealso cref="XRSessionSubsystem.DetermineConfiguration(Feature)"/>
/// <seealso cref="Feature"/>
public Configuration? currentConfiguration { get; private set; }
#if DEVELOPMENT_BUILD || UNITY_EDITOR
unsafe string HexString(IntPtr ptr) => sizeof(IntPtr) == 4 ? $"0x{ptr.ToInt32():x}" : $"0x{ptr.ToInt64():x}";
void DebugPrintConfigurationChange(Configuration configuration, Feature desiredFeatures)
{
if (configuration != m_PreviousConfiguration ||
desiredFeatures != m_PreviousDesiredFeatures)
{
var sb = new System.Text.StringBuilder();
sb.Append($"Using session configuration {HexString(configuration.descriptor.identifier)}");
if (configuration.descriptor.identifier == m_PreviousConfiguration.descriptor.identifier)
{
sb.Append(" (unchanged)");
}
sb.Append("\n\tRequested Features: ");
sb.Append(desiredFeatures.ToStringList());
sb.Append("\n\tSupported Features: ");
sb.Append(configuration.features.ToStringList());
sb.Append("\n\tRequested features not satisfied: ");
sb.Append(desiredFeatures.SetDifference(configuration.features).ToStringList());
Debug.Log(sb.ToString());
m_PreviousConfiguration = configuration;
m_PreviousDesiredFeatures = desiredFeatures;
}
}
Feature m_PreviousDesiredFeatures;
Configuration m_PreviousConfiguration;
bool m_FirstUpdate = true;
#endif
/// <summary>
/// Get the requested <see cref="Feature"/>s. These are used to determine the session's <see cref="Configuration"/>.
/// </summary>
/// <seealso cref="XRSessionSubsystem.DetermineConfiguration(Feature)"/>
public Feature requestedFeatures => provider.requestedFeatures;
/// <summary>
/// Get the list of supported configuration descriptors. The session may have multiple, discrete "modes" of operation.
/// A configuration represents the capabilities of a "mode" of operation, which may be a subset of the session's overal
/// capabilities. That is, the session may support many features, but not all at the same time. This is used by
/// <see cref="XRSessionSubsystem.DetermineConfiguration(Feature)"/> to determine the best configuration given a set
/// of requested features.
/// </summary>
/// <param name="allocator">The [allocator](https://docs.unity3d.com/ScriptReference/Unity.Collections.Allocator.html)
/// to use for the returned [NativeArray](https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeArray_1.html).</param>
/// <returns>Allocates a new [NativeArray](https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeArray_1.html)
/// and populates it with descriptors describing the supported configuration(s). The caller
/// owns the memory and is responsible for [Dispose](https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeArray_1.Dispose.html)'ing
/// of the <c>NativeArray</c>.</returns>
public NativeArray<ConfigurationDescriptor> GetConfigurationDescriptors(Allocator allocator) => provider.GetConfigurationDescriptors(allocator);
/// <summary>
/// Should be invoked when the application is paused.
/// </summary>
public void OnApplicationPause() => provider.OnApplicationPause();
/// <summary>
/// Should be invoked when the application is resumed.
/// </summary>
public void OnApplicationResume() => provider.OnApplicationResume();
/// <summary>
/// Gets the <see cref="TrackingState"/> for the session.
/// </summary>
public TrackingState trackingState => provider.trackingState;
/// <summary>
/// The requested tracking mode. Query for support with <c>SubsystemDescriptor.supportedTrackingModes</c>.
/// </summary>
public Feature requestedTrackingMode
{
get => provider.requestedTrackingMode.TrackingModes();
set => provider.requestedTrackingMode = value.TrackingModes();
}
/// <summary>
/// Get the current tracking mode in use by the subsystem.
/// </summary>
public Feature currentTrackingMode => provider.currentTrackingMode.TrackingModes();
/// <summary>
/// Get or set the <see cref="ConfigurationChooser"/> used by
/// <see cref="XRSessionSubsystem.DetermineConfiguration(Feature)"/>.
/// If set to <c>null</c>, the <see cref="DefaultConfigurationChooser"/>
/// is used.
/// </summary>
public ConfigurationChooser configurationChooser
{
get => m_ConfigurationChooser;
set
{
if (ReferenceEquals(value, null))
{
m_ConfigurationChooser = m_DefaultConfigurationChooser;
}
else
{
m_ConfigurationChooser = value;
}
}
}
ConfigurationChooser m_DefaultConfigurationChooser = new DefaultConfigurationChooser();
ConfigurationChooser m_ConfigurationChooser;
/// <summary>
/// Gets the <see cref="NotTrackingReason"/> for the session.
/// </summary>
public NotTrackingReason notTrackingReason => provider.notTrackingReason;
/// <summary>
/// Whether the AR session update is synchronized with the Unity frame rate.
/// If <c>true</c>, <see cref="Update(XRSessionUpdateParams)"/> should block until the next AR frame is available.
/// </summary>
/// <exception cref="System.NotSupportedException">Thrown if <see cref="XRSessionSubsystemDescriptor.supportsMatchFrameRate"/> is <c>False</c>.</exception>
public bool matchFrameRateEnabled
{
get => provider.matchFrameRateEnabled;
}
/// <summary>
/// Get or set whether the match frame rate feature should be enabled.
/// When enabled, the AR session update is synchronized with the Unity frame rate.
/// </summary>
/// <seealso cref="matchFrameRateEnabled"/>
public bool matchFrameRateRequested
{
get => provider.matchFrameRateRequested;
set => provider.matchFrameRateRequested = value;
}
/// <summary>
/// The native update rate of the AR Session.
/// </summary>
/// <exception cref="System.NotSupportedException">Thrown if <see cref="XRSessionSubsystemDescriptor.supportsMatchFrameRate"/> is <c>False</c>.</exception>
public int frameRate => provider.frameRate;
#if !UNITY_2020_2_OR_NEWER
/// <summary>
/// Implement this to provide this class with an interface to
/// platform specific implementations.
/// </summary>
/// <returns>An implementation specific provider.</returns>
protected abstract Provider CreateProvider();
#endif
/// <summary>
/// The API this subsystem uses to interop with
/// different provider implementations.
/// </summary>
public class Provider
#if UNITY_2020_2_OR_NEWER
: SubsystemProvider<XRSessionSubsystem>
#endif
{
#if UNITY_2020_2_OR_NEWER
/// <summary>
/// Invoked to start or resume a session. This is different from <see cref="OnApplicationResume"/>.
/// </summary>
public override void Start() {}
/// <summary>
/// Invoked to pause a running session. This is different from <see cref="OnApplicationPause"/>.
/// </summary>
public override void Stop() {}
#else
/// <summary>
/// Invoked to start or resume a session. This is different from <see cref="OnApplicationResume"/>.
/// </summary>
public virtual void Resume() { }
/// <summary>
/// Invoked to pause a running session. This is different from <see cref="OnApplicationPause"/>.
/// </summary>
public virtual void Pause() { }
#endif
/// <summary>
/// Perform any per-frame update logic here.
/// </summary>
/// <param name="updateParams">Parameters about the current state that may be needed to inform the session.</param>
public virtual void Update(XRSessionUpdateParams updateParams) { }
/// <summary>
/// Perform any per-frame update logic here. The session should use the configuration indicated by
/// <paramref name="configuration.descriptor.identifier"/>, which should be one of the ones returned
/// by <see cref="GetConfigurationDescriptors(Unity.Collections.Allocator)"/>.
/// </summary>
/// <param name="updateParams">Parameters about the current state that may be needed to inform the session.</param>
/// <param name="configuration">The configuration the session should use.</param>
public virtual void Update(XRSessionUpdateParams updateParams, Configuration configuration) { }
/// <summary>
/// Should return the features requested by the enabling of other <c>Subsystem</c>s.
/// </summary>
public virtual Feature requestedFeatures => Feature.None;
/// <summary>
/// Get or set the requested tracking mode, e.g., the <see cref="Feature.AnyTrackingMode"/> bits.
/// </summary>
public virtual Feature requestedTrackingMode
{
get => Feature.None;
set {}
}
/// <summary>
/// Get the current tracking mode, e.g., the <see cref="Feature.AnyTrackingMode"/> bits.
/// </summary>
public virtual Feature currentTrackingMode => Feature.None;
/// <summary>
/// This getter should allocate a new <c>NativeArray</c> using <paramref name="allocator"/>
/// and populate it with the supported <see cref="ConfigurationDescriptor"/>s.
/// </summary>
/// <param name="allocator">The <c>[Allocator](https://docs.unity3d.com/ScriptReference/Unity.Collections.Allocator.html)</c>
/// to use to create the returned <c>NativeArray</c>.</param>
/// <returns>A newly allocated <c>NativeArray</c> of <see cref="ConfigurationDescriptor"/>s describing the capabilities
/// of all the supported configurations.</returns>
public virtual NativeArray<ConfigurationDescriptor> GetConfigurationDescriptors(Allocator allocator) => default;
/// <summary>
/// Stop the session and destroy all associated resources.
/// </summary>
#if UNITY_2020_2_OR_NEWER
public override void Destroy() { }
#else
public virtual void Destroy() { }
#endif
/// <summary>
/// Reset the session. The behavior should be equivalent to destroying and recreating the session.
/// </summary>
public virtual void Reset() { }
/// <summary>
/// Invoked when the application is paused.
/// </summary>
public virtual void OnApplicationPause() { }
/// <summary>
/// Invoked when the application is resumed.
/// </summary>
public virtual void OnApplicationResume() { }
/// <summary>
/// Get a pointer to an object associated with the session.
/// Callers should be able to manipulate the session in their own code using this.
/// </summary>
public virtual IntPtr nativePtr => IntPtr.Zero;
/// <summary>
/// Get the session's availability, such as whether the platform supports XR.
/// </summary>
/// <returns>A <see cref="Promise{T}"/> that the caller can yield on until availability is determined.</returns>
public virtual Promise<SessionAvailability> GetAvailabilityAsync()
{
return Promise<SessionAvailability>.CreateResolvedPromise(SessionAvailability.None);
}
/// <summary>
/// Attempt to update or install necessary XR software. Will only be called if
/// <see cref="XRSessionSubsystemDescriptor.supportsInstall"/> is true.
/// </summary>
/// <returns></returns>
public virtual Promise<SessionInstallationStatus> InstallAsync()
{
return Promise<SessionInstallationStatus>.CreateResolvedPromise(SessionInstallationStatus.ErrorInstallNotSupported);
}
/// <summary>
/// Get the <see cref="TrackingState"/> for the session.
/// </summary>
public virtual TrackingState trackingState => TrackingState.None;
/// <summary>
/// Get the <see cref="NotTrackingReason"/> for the session.
/// </summary>
public virtual NotTrackingReason notTrackingReason => NotTrackingReason.Unsupported;
/// <summary>
/// Get a unique identifier for this session
/// </summary>
public virtual Guid sessionId => Guid.Empty;
/// <summary>
/// Whether the AR session update is synchronized with the Unity frame rate.
/// If <c>true</c>, <see cref="Update(XRSessionUpdateParams)"/> will block until the next AR frame is available.
/// </summary>
public virtual bool matchFrameRateEnabled => false;
/// <summary>
/// Whether the AR session update should be synchronized with the Unity frame rate.
/// If <c>true</c>, <see cref="Update(XRSessionUpdateParams)"/> should block until the next AR frame is available.
/// Must be implemented if
/// <see cref="XRSessionSubsystemDescriptor.supportsMatchFrameRate"/>
/// is <c>True</c>.
/// </summary>
public virtual bool matchFrameRateRequested
{
get => false;
set
{
if (value)
{
throw new NotSupportedException("Matching frame rate is not supported.");
}
}
}
/// <summary>
/// The native update rate of the AR Session. Must be implemented if
/// <see cref="XRSessionSubsystemDescriptor.supportsMatchFrameRate"/>
/// is <c>True</c>.
/// </summary>
public virtual int frameRate =>
throw new NotSupportedException("Querying the frame rate is not supported by this session subsystem.");
}
#if !UNITY_2020_2_OR_NEWER
/// <summary>
/// The provider created by the implementation that contains the required session functionality.
/// </summary>
protected Provider provider { get; }
XRSessionSubsystemDescriptor subsystemDescriptor => SubsystemDescriptor;
#endif
}
}