Laurens-Packages/Packages/com.unity.render-pipelines.core/Runtime/UnifiedRayTracing/IRayTracingAccelStruct.cs

using System;

namespace UnityEngine.Rendering.UnifiedRayTracing
{
    /// <summary>
    /// Parameters used to configure the creation of instances that are part of a <see cref="IRayTracingAccelStruct"/>.
    /// </summary>
    public struct MeshInstanceDesc
    {
        /// <summary>
        /// The Mesh used to build this instance's geometry.
        /// </summary>
        public Mesh mesh;

        /// <summary>
        /// The index of the sub-mesh (MeshInstanceDesc references a single sub-mesh).
        /// </summary>
        public int subMeshIndex;

        /// <summary>
        /// The transformation matrix of the instance.
        /// </summary>
        public Matrix4x4 localToWorldMatrix;

        /// <summary>
        /// The instance mask.
        /// </summary>
        /// <remarks>
        /// Instances in the acceleration structure contain an 8-bit user defined instance mask.
        /// The TraceRayClosestHit/TraceRayAnyHit HLSL functions have an 8-bit input parameter, InstanceInclusionMask which gets ANDed with the instance mask from
        /// any instance that is a candidate for intersection during acceleration structure traversal on the GPU.
        /// If the result of the AND operation is zero, the GPU ignores the intersection.
        /// </remarks>
        public uint mask;

        /// <summary>
        /// Instance identifier. Can be accessed in the HLSL via the instanceID member of Hit (Hit is returned by the TraceRayClosestHit/TraceRayAnyHit HLSL functions).
        /// </summary>
        public uint instanceID;

        /// <summary>
        /// Whether front/back face culling for this ray tracing instance is enabled. Default value: true.
        /// </summary>
        public bool enableTriangleCulling;

        /// <summary>
        /// Whether to flip the way triangles face in this ray tracing instance. Default value: false.
        /// </summary>
        public bool frontTriangleCounterClockwise;

        /// <summary>
        /// Whether the geometry is considered opaque. Default value: true.
        /// </summary>
        /// <remarks>
        /// When an instance's opaqueGeometry field is set to false, the AnyHitExecute shader function will be invoked during the ray traversal when a hit is found.
        /// This alows the user to programmatically decide whether to reject or accept the candidate hit. This feature can, for example, be used to implement alpha cutout transparency.
        /// For best performance, prefer to set this parameter to false for as many geometries as possibe.
        /// </remarks>
        public bool opaqueGeometry;

        /// <summary>
        /// Creates a MeshInstanceDesc.
        /// </summary>
        /// <param name="mesh">The Mesh used to build this instance's geometry.</param>
        /// <param name="subMeshIndex">The index of the sub-mesh (MeshInstanceDesc references a single sub-mesh).</param>
        public MeshInstanceDesc(Mesh mesh, int subMeshIndex = 0)
        {
            this.mesh = mesh;
            this.subMeshIndex = subMeshIndex;
            localToWorldMatrix = Matrix4x4.identity;
            mask = 0xFFFFFFFF;
            instanceID = 0xFFFFFFFF;
            enableTriangleCulling = true;
            frontTriangleCounterClockwise = false;
            opaqueGeometry = true;
        }
    }

    /// <summary>
    /// A data structure used to represent a collection of instances and geometries that are used for GPU ray tracing.
    /// It can be created by calling <see cref="RayTracingContext.CreateAccelerationStructure"/>.
    /// </summary>
    public interface IRayTracingAccelStruct : IDisposable
    {
        /// <summary>
        /// Adds an instance to the RayTracingAccelerationStructure.
        /// </summary>
        /// <param name="meshInstance">The parameters describing this instance.</param>
        /// <returns>A value representing a handle that you can use to perform later actions (e.g. RemoveInstance...)</returns>
        /// <exception cref="UnifiedRayTracingException">Thrown if the instance cannot be added. Inspect <see cref="UnifiedRayTracingException.errorCode"/> for the reason.</exception>
        int AddInstance(MeshInstanceDesc meshInstance);

        /// <summary>
        /// Removes an instance.
        /// </summary>
        /// <param name="instanceHandle">The handle associated with an instance.</param>
        void RemoveInstance(int instanceHandle);

        /// <summary>
        /// Removes all ray tracing instances from the acceleration structure.
        /// </summary>
        void ClearInstances();

        /// <summary>
        /// Updates the transformation of an instance.
        /// </summary>
        /// <param name="instanceHandle">The handle associated with an instance.</param>
        /// <param name="localToWorldMatrix">The new transformation matrix of the instance.</param>
        void UpdateInstanceTransform(int instanceHandle, Matrix4x4 localToWorldMatrix);

        /// <summary>
        /// Updates the instance ID of an instance.
        /// </summary>
        /// <param name="instanceHandle">The handle associated with an instance.</param>
        /// <param name="instanceID">The new instance ID.</param>
        void UpdateInstanceID(int instanceHandle, uint instanceID);

        /// <summary>
        /// Updates the instance mask of an instance.
        /// </summary>
        /// <remarks>
        /// Ray tracing instances in the acceleration structure contain an 8-bit user defined instance mask.
        /// The TraceRay() HLSL function has an 8-bit input parameter, InstanceInclusionMask which gets ANDed with the instance mask from
        /// any ray tracing instance that is a candidate for intersection during acceleration structure traversal on the GPU.
        /// If the result of the AND operation is zero, the GPU ignores the intersection.
        /// </remarks>
        /// <param name="instanceHandle">The handle associated with an instance.</param>
        /// <param name="mask">	The new mask.</param>
        void UpdateInstanceMask(int instanceHandle, uint mask);

        /// <summary>
        /// Adds a command in cmd to build this acceleration structure on the GPU.
        /// </summary>
        /// <remarks>
        /// Depending on the backend, the GPU build algorithm can require additional GPU storage that is supplied through the scratchBuffer parameter.
        /// Its required size can be queried by calling <see cref="GetBuildScratchBufferRequiredSizeInBytes"/>.
        /// </remarks>
        /// <param name="cmd">CommandBuffer to register the build command to.</param>
        /// <param name="scratchBuffer">Temporary buffer used during the build.</param>
        /// <exception cref="UnifiedRayTracingException">Thrown if the build failed. Inspect <see cref="UnifiedRayTracingException.errorCode"/> for the reason.</exception>
        void Build(CommandBuffer cmd, GraphicsBuffer scratchBuffer);

        /// <summary>
        /// Returns the minimum buffer size that is required by the scratchBuffer parameter of <see cref="Build"/>.
        /// </summary>
        /// <returns>The minimum size in bytes.</returns>
        ulong GetBuildScratchBufferRequiredSizeInBytes();
    }
}