Repository/Library/PackageCache/com.unity.xr.arsubsystems@3.1.3/Runtime/EnvironmentProbeSubsystem/XREnvironmentProbeSubsystem.cs

using System;
using Unity.Collections;

namespace UnityEngine.XR.ARSubsystems
{
    /// <summary>
    /// Defines an interface for interacting with environment probe functionality for creating realistic lighting and
    /// environment texturing in AR scenes.
    /// </summary>
    public abstract class XREnvironmentProbeSubsystem : TrackingSubsystem<XREnvironmentProbe, XREnvironmentProbeSubsystemDescriptor>
    {
        /// <summary>
        /// Constructs an <see cref="XREnvironmentProbeSubsystem"/>.
        /// Do not create this directly.
        /// Call <c>Create</c> on an <see cref="XREnvironmentProbeSubsystemDescriptor"/> obtained from the <c>SubsystemManager</c>.
        /// </summary>
        public XREnvironmentProbeSubsystem() => m_Provider = CreateProvider();

        /// <summary>
        /// Specifies whether the AR session should automatically place environment probes in the scene.
        /// </summary>
        /// <value>
        /// <c>true</c> if automatic placement of environment probes is enabled. Otherwise, <c>false</c>.
        /// </value>
        /// <remarks>
        /// If both manual and automatic placement of environment probes are supported, manually placed environment
        /// probes may be specified via <see cref="AddEnvironmentProbe"/> regardless of whether automatic placement is
        /// enabled or not.
        /// </remarks>
        /// <exception cref="System.NotSupportedException">Thrown when setting this value to <c>true</c> for
        /// implementations that do not support automatic placement.</exception>
        public bool automaticPlacement
        {
            get { return m_AutomaticPlacement; }
            set
            {
                if (value && !SubsystemDescriptor.supportsAutomaticPlacement)
                    throw new NotSupportedException("subsystem does not support automatic placement of environment probes.");

                if (m_AutomaticPlacement != value && running)
                {
                    m_Provider.SetAutomaticPlacement(value);
                }

                m_AutomaticPlacement = value;
            }
        }
        bool m_AutomaticPlacement;

        /// <summary>
        /// Specifies whether the environment textures should be returned as HDR textures.
        /// </summary>
        /// <value>
        /// <c>true</c> if the environment textures should be returned as HDR textures. Otherwise, <c>false</c>.
        /// </value>
        public bool environmentTextureHDR
        {
            get { return m_EnvironmentTextureHDR; }
            set
            {
                if ((m_EnvironmentTextureHDR != value) && m_Provider.TrySetEnvironmentTextureHDREnabled(value))
                {
                    m_EnvironmentTextureHDR = value;
                }
            }
        }
        bool m_EnvironmentTextureHDR = true;

        /// <summary>
        ///
        /// </summary>
        /// <param name="allocator"></param>
        /// <returns></returns>
        public override TrackableChanges<XREnvironmentProbe> GetChanges(Allocator allocator)
        {
            return m_Provider.GetChanges(XREnvironmentProbe.defaultValue, allocator);
        }

        /// <summary>
        /// Starts the subsystem. If <see cref="automaticPlacement"/> is <c>true</c>, environment probes will be created automatically.
        /// </summary>
        protected sealed override void OnStart()
        {
            m_Provider.SetAutomaticPlacement(automaticPlacement);
            m_Provider.Start();
        }

        /// <summary>
        /// Stops the subsystem. This does not remove existing environment probes, but it stops automatically placing them, and manually placed probes will not be updated
        /// until <see cref="OnStart"/> is called again.
        /// </summary>
        protected sealed override void OnStop() => m_Provider.Stop();

        /// <summary>
        /// Destroys the subsystem and any internal state.
        /// </summary>
        protected sealed override void OnDestroyed() => m_Provider.Destroy();

        /// <summary>
        /// Tries to create an environment probe.
        /// </summary>
        /// <param name="pose">The position and rotation at which to create the environment probe.</param>
        /// <param name="scale">The scale at which to create the environment probe.</param>
        /// <param name="size">The size (dimensions) of the environment probe to create.</param>
        /// <param name="environmentProbe">If successful, populated with the newly created environment probe. Otherwise, it will contain default values.</param>
        /// <returns>
        /// <c>true</c> if the environment probe was successfully added, otherwise <c>false</c>.
        /// </returns>
        /// <exception cref="InvalidOperationException">Thrown when the environment probe subsystem is not running and
        /// this method is called to an add environment probe.</exception>
        /// <exception cref="NotSupportedException">Thrown for platforms that do not support manual placement of
        /// environment probes.</exception>
        public bool TryAddEnvironmentProbe(Pose pose, Vector3 scale, Vector3 size, out XREnvironmentProbe environmentProbe)
        {
            if (!running)
            {
                throw new InvalidOperationException("cannot add environment probes when environment probe system is not running");
            }

            environmentProbe = XREnvironmentProbe.defaultValue;
            return m_Provider.TryAddEnvironmentProbe(pose, scale, size, out environmentProbe);
        }

        /// <summary>
        /// Asynchronously removes the environment probe matching the trackable ID from the AR session.
        /// </summary>
        /// <param name='trackableId'>Trackable ID of the environment probe to be removed from the AR session.</param>
        /// <returns>
        /// <c>true</c> if the environment probe is found in the current AR session and will be removed. Otherwise,
        /// <c>false</c>.
        /// </returns>
        /// <remarks>
        /// <c>RemoveEnvironmentProbe</c> may be used to remove both manually-placed and automatically-placed
        /// environment probes if the implementation supports such removals, as indicated by the descriptor properties
        /// <see cref="XREnvironmentProbeSubsystemDescriptor.supportsRemovalOfManual"/> and
        /// <see cref="XREnvironmentProbeSubsystemDescriptor.supportsRemovalOfAutomatic"/>.
        /// </remarks>
        /// <exception cref="InvalidOperationException">Thrown when the environment probe subsystem is not running and
        /// this method is called to an add environment probe.</exception>
        /// <exception cref="System.NotSupportedException">Thrown for platforms that do not support removal of the
        /// type of environment probe.</exception>
        public bool RemoveEnvironmentProbe(TrackableId trackableId)
        {
            if (!running)
            {
                throw new InvalidOperationException("cannot remove environment probes when environment probe system is not running");
            }

            return m_Provider.RemoveEnvironmentProbe(trackableId);
        }

        /// <summary>
        /// Must create an implementation of <see cref="Provider"/>, the provider-specific implementation of this subsystem.
        /// </summary>
        protected abstract Provider CreateProvider();

        /// <summary>
        /// The class for providers to implement to support the <see cref="XREnvironmentProbeSubsystem"/>.
        /// </summary>
        protected abstract class Provider
        {
            /// <summary>
            /// Starts the subsystem. Will only be invoked if <see cref="running"/> is <c>false</c>.
            /// </summary>
            public virtual void Start()
            { }

            /// <summary>
            /// Stops the subsystem. Will only be invoked if <see cref="running"/> is <c>true</c>.
            /// </summary>
            public virtual void Stop()
            { }

            /// <summary>
            /// Invoked when the <see cref="XREnvironmentProbeSubsystem"/> is about to be destroyed.
            /// </summary>
            public virtual void Destroy()
            { }

            /// <summary>
            /// Overridden by the provider implementation to set the automatic placement state for the environment probe
            /// subsystem.
            /// </summary>
            /// <param name='value'>Whether automatic placement of environment probes should be enabled (<c>true</c>) or
            /// disabled (<c>false</c>).</param>
            /// <exception cref="System.NotSupportedException">Thrown in the defualt implementation if
            /// <paramref name="value"/> is <c>true</c>.</exception>
            public virtual void SetAutomaticPlacement(bool value)
            {
                if (value)
                {
                    throw new NotSupportedException("automatic placement of environment probes is not supported by this implementation");
                }
            }

            /// <summary>
            /// Overridden by the provider implementation to set the state of HDR environment texture generation.
            /// </summary>
            /// <param name="value">Whether HDR environment texture generation is enabled (<c>true</c>) or disabled
            /// (<c>false</c>).</param>
            /// <returns>
            /// Whether the HDR environment texture generation state was set.
            /// </returns>
            /// <exception cref="System.NotSupportedException">Thrown if the implementation does not support HDR
            /// environment textures if the state is being enabled.</exception>
            public virtual bool TrySetEnvironmentTextureHDREnabled(bool value)
            {
                if (value)
                {
                    throw new NotSupportedException("HDR environment textures are not supported by this implementation");
                }
                return false;
            }

            /// <summary>
            /// Overridden by the provider implementation to manually add an environment probe to the AR session.
            /// </summary>
            /// <param name='pose'>The position and rotation at which to create the new environment probe.</param>
            /// <param name='scale'>The scale of the new environment probe.</param>
            /// <param name='size'>The size (dimensions) of the new environment probe.</param>
            /// <param name='environmentProbe'>If successful, should be populated with the newly created environment probe.</param>
            /// <returns>
            /// <c>true</c> if a new environment probe was created, otherwise <c>false</c>.
            /// </returns>
            /// <exception cref="System.NotSupportedException">Thrown in the default implementation of this method.</exception>
            public virtual bool TryAddEnvironmentProbe(Pose pose, Vector3 scale, Vector3 size, out XREnvironmentProbe environmentProbe)
            {
                throw new NotSupportedException("manual placement of environment probes is not supported by this implementation");
            }

            /// <summary>
            /// Overridden by the provider to remove the environment probe matching the trackable ID from
            /// the AR session.
            /// </summary>
            /// <param name='trackableId'>Trackable ID of the environment probe to be removed from the AR session.</param>
            /// <returns>
            /// <c>true</c> whether the environment probe is found in the current AR session and will be removed.
            /// Otherwise, <c>false</c>.
            /// </returns>
            /// <remarks>
            /// This method may be used to remove both manually-placed and automatically-placed environment probes if the
            /// implementation supports such removals. Providers should implement this method remove environment probes of
            /// the allowed types and to throw a <c>System.NotSupportedException</c> for removals of environment probes of
            /// disallowed types.
            /// </remarks>
            /// <exception cref="System.NotSupportedException">Thrown in the default implementation.</exception>
            public virtual bool RemoveEnvironmentProbe(TrackableId trackableId)
            {
                throw new NotSupportedException("removal of environment probes is not supported by this implementation");
            }

            /// <summary>
            /// Get changes (added, updated, and removed) in environment probes since the last call to this method.
            /// </summary>
            /// <param name="defaultEnvironmentProbe">A default value for environment probes. Implementations should first fill their output
            /// arrays with copies of this value, then copy in their own. See the <see cref="NativeCopyUtility"/>.
            /// This allows additional fields to be added to the <see cref="XREnvironmentProbe"/> in the future.</param>
            /// <param name="allocator">The allocator to use for the <c>NativeArray</c>s in the returned <see cref="TrackableChanges{T}"/>.</param>
            /// <returns>The environment probes which have been added, updated, and removed since the last call to this method.</returns>
            /// <seealso cref="NativeCopyUtility"/>
            public abstract TrackableChanges<XREnvironmentProbe> GetChanges(XREnvironmentProbe defaultEnvironmentProbe, Allocator allocator);
        }

        /// <summary>
        /// Registers a subsystem implementation based on the given subystem parameters.
        /// </summary>
        /// <param name='environmentProbeSubsystemCinfo'>The parameters defining the environment probe functionality
        /// implemented by the subsystem provider.</param>
        /// <returns>
        /// <c>true</c> if the subsystem implementation is registered. Otherwise, <c>false</c>.
        /// </returns>
        /// <exception cref="ArgumentException">Thrown when the values specified in the
        /// <paramref name="environmentProbeSubsystemCinfo"/> parameter are invalid. Typically, this will occur
        /// <list type="bullet">
        /// <item>
        /// <description>if <see cref="XREnvironmentProbeSubsystemCinfo.id"/> is <c>null</c> or empty</description>
        /// </item>
        /// <item>
        /// <description>if <see cref="XREnvironmentProbeSubsystemCinfo.implementationType"/> is <c>null</c>
        /// </description>
        /// </item>
        /// <item>
        /// <description>if <see cref="XREnvironmentProbeSubsystemCinfo.implementationType"/> does not derive from the
        /// <c>XREnvironmentProbeSubsystem</c> class
        /// </description>
        /// </item>
        /// </list>
        /// </exception>
        public static bool Register(XREnvironmentProbeSubsystemCinfo environmentProbeSubsystemCinfo)
        {
            XREnvironmentProbeSubsystemDescriptor environmentProbeSubsystemDescriptor = XREnvironmentProbeSubsystemDescriptor.Create(environmentProbeSubsystemCinfo);

            return SubsystemRegistration.CreateDescriptor(environmentProbeSubsystemDescriptor);
        }

        Provider m_Provider;
    }
}