# AddInstance

> Adds a ray tracing instance to the RayTracingAccelerationStructure.

## Definition

* **Type:** Method
* **Namespace:** [UnityEngine.Rendering](/engine/6000.7/script-reference/unityengine/rendering.md)
* **Assembly:** UnityEngine.CoreModule

## AddInstance(Renderer, RayTracingSubMeshFlags\[], bool, bool, uint, uint)

Adds a ray tracing instance to the RayTracingAccelerationStructure.

```csharp
public int AddInstance(Renderer targetRenderer, RayTracingSubMeshFlags[] subMeshFlags, bool enableTriangleCulling = true, bool frontTriangleCounterClockwise = false, uint mask = 255, uint id = 4294967295)
```

### Parameters

**** (\[Renderer]\(/engine/6000.7/script-reference/unityengine/renderer)): The Renderer to add to the RayTracingAccelerationStructure.**** (\[RayTracingSubMeshFlags\[]]\(/engine/6000.7/script-reference/unityengine/rendering/raytracingsubmeshflags)): A list of flags that control the shader execution behaviour when a ray intersects a sub-mesh geometry. See [RayTracingSubMeshFlags](/engine/6000.7/script-reference/unityengine/rendering/raytracingsubmeshflags.md) for additional information.**** (\[bool]\(https\://learn.microsoft.com/dotnet/api/system.boolean)): A bool that indicates whether front/back face culling for this ray tracing instance is enabled. The culling takes place when the GPU performs a ray-triangle intersection test. Culling is enabled (true) by default.**** (\[bool]\(https\://learn.microsoft.com/dotnet/api/system.boolean)): A bool that indicates whether to flip the way triangles face in this ray tracing instance. If this is set to true, front-facing triangles will become back-facing and vice versa. Set to false by default.**** (\[uint]\(https\://learn.microsoft.com/dotnet/api/system.uint32)): An 8-bit mask you can use to selectively intersect the ray tracing instance associated with the target Renderer with rays that only pass the mask. All rays are enabled (0xff) by default.**** (\[uint]\(https\://learn.microsoft.com/dotnet/api/system.uint32)): An optional instance ID value accessed with `InstanceID()` HLSL function.

### Returns

| Type                                                       | Description                                                                                                                                    |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [int](https://learn.microsoft.com/dotnet/api/system.int32) | A value representing a handle that you can use to perform later actions (e.g. RemoveInstance), or 0 if the instance is not added successfully. |

### 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 intersection is ignored.

When you have added all required instances, use [RayTracingAccelerationStructure.Build](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/build.md) or [CommandBuffer.BuildRayTracingAccelerationStructure](/engine/6000.7/script-reference/unityengine/rendering/commandbuffer/buildraytracingaccelerationstructure.md) to build the acceleration structure on the GPU.

Additional Resources: [RayTracingAccelerationStructure.RemoveInstance](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/removeinstance.md), [RayTracingSubMeshFlags](/engine/6000.7/script-reference/unityengine/rendering/raytracingsubmeshflags.md).

## AddInstance(RayTracingAABBsInstanceConfig, Matrix4x4, uint)

Adds a ray tracing instance associated with a list of axis-aligned bounding boxes (AABBs) to the RayTracingAccelerationStructure for procedural geometry generation using intersection shaders.

```csharp
public int AddInstance(RayTracingAABBsInstanceConfig config, Matrix4x4 matrix, uint id = 4294967295)
```

### Parameters

**** (\[RayTracingAABBsInstanceConfig]\(/engine/6000.7/script-reference/unityengine/rendering/raytracingaabbsinstanceconfig)): The common parameters that this AABBs ray tracing instance uses.**** (\[Matrix4x4]\(/engine/6000.7/script-reference/unityengine/matrix4x4)): The transformation matrix of the ray tracing instance.**** (\[uint]\(https\://learn.microsoft.com/dotnet/api/system.uint32)): An optional instance ID value that you can access with `InstanceID()` HLSL function.

### Returns

| Type                                                       | Description                                                                                                                                                                                            |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [int](https://learn.microsoft.com/dotnet/api/system.int32) | A value representing a handle that can be used to perform later actions (e.g. RemoveInstance, UpdateInstancePropertyBlock or UpdateInstanceTransform), or 0 if the instance is not added successfully. |

### Remarks

Define the AABB list in the [GraphicsBuffer](/engine/6000.7/script-reference/unityengine/graphicsbuffer.md) you set the [config.aabbBuffer](/engine/6000.7/script-reference/unityengine/rendering/raytracingaabbsinstanceconfig/aabbbuffer.md) parameter to. Unity uses the AABBs to build an acceleration structure for this ray tracing instance.

The AABBs are defined in local space and can be transformed using the matrix argument. Use [RayTracingAccelerationStructure.UpdateInstanceTransform](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/updateinstancetransform.md) to update the transformation of the ray tracing instance at a later time.

Unity copies the contents of the [MaterialPropertyBlock](/engine/6000.7/script-reference/unityengine/materialpropertyblock.md) in the [config.materialProperties](/engine/6000.7/script-reference/unityengine/rendering/raytracingaabbsinstanceconfig/materialproperties.md) parameter into the ray tracing instance when this function is called. Any subsequent changes to the [MaterialPropertyBlock](/engine/6000.7/script-reference/unityengine/materialpropertyblock.md) object that was passed as argument are not taken into account. Use [RayTracingAccelerationStructure.UpdateInstancePropertyBlock](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/updateinstancepropertyblock.md) to updated the properties again at a later time.

When a ray intersects one of the AABBs in the list during a ray tracing dispatch, the GPU invokes an intersection shader. You can retrieve the index of a discrete AABB in the acceleration structure with the `PrimitiveIndex()` HLSL function.

When you have added all required instances, use [RayTracingAccelerationStructure.Build](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/build.md) or [CommandBuffer.BuildRayTracingAccelerationStructure](/engine/6000.7/script-reference/unityengine/rendering/commandbuffer/buildraytracingaccelerationstructure.md) to build the acceleration structure on the GPU.

Additional Resources: [RayTracingAccelerationStructure.RemoveInstance](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/removeinstance.md), [RayTracingShader.Dispatch](/engine/6000.7/script-reference/unityengine/rendering/raytracingshader/dispatch.md).

## AddInstance(RayTracingMeshInstanceConfig, Matrix4x4, Matrix4x4?, uint)

Adds a ray tracing instance associated with a [Mesh](/engine/6000.7/script-reference/unityengine/mesh.md) to the RayTracingAccelerationStructure.

```csharp
public int AddInstance(in RayTracingMeshInstanceConfig config, Matrix4x4 matrix, Matrix4x4? prevMatrix = null, uint id = 4294967295)
```

### Parameters

**** (\[RayTracingMeshInstanceConfig]\(/engine/6000.7/script-reference/unityengine/rendering/raytracingmeshinstanceconfig)): The common parameters that this Mesh ray tracing instance uses.**** (\[Matrix4x4]\(/engine/6000.7/script-reference/unityengine/matrix4x4)): The transformation matrix of the ray tracing instance.**** (\[Matrix4x4?]\(https\://learn.microsoft.com/dotnet/api/system.nullable)): The previous frame transformation matrix of the ray tracing instance that you can use to compute motion vectors in shader code.**** (\[uint]\(https\://learn.microsoft.com/dotnet/api/system.uint32)): An optional instance ID value that you can access with `InstanceID()` HLSL function.

### Returns

| Type                                                       | Description                                                                                                                                                                                            |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [int](https://learn.microsoft.com/dotnet/api/system.int32) | A value representing a handle that you can use to perform later actions (e.g. RemoveInstance, UpdateInstancePropertyBlock or UpdateInstanceTransform), or 0 if the instance is not added successfully. |

### Remarks

The config function argument specifies the relevant [Mesh](/engine/6000.7/script-reference/unityengine/mesh.md) and associated parameters.

When you have added all required instances, use [RayTracingAccelerationStructure.Build](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/build.md) or [CommandBuffer.BuildRayTracingAccelerationStructure](/engine/6000.7/script-reference/unityengine/rendering/commandbuffer/buildraytracingaccelerationstructure.md) to build the acceleration structure on the GPU.

Additional Resources: [RayTracingAccelerationStructure.RemoveInstance](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/removeinstance.md), [RayTracingShader.Dispatch](/engine/6000.7/script-reference/unityengine/rendering/raytracingshader/dispatch.md).

## AddInstance(RayTracingGeometryInstanceConfig, Matrix4x4, Matrix4x4?, uint)

Adds a ray tracing instance to the RayTracingAccelerationStructure.

```csharp
public int AddInstance(in RayTracingGeometryInstanceConfig config, Matrix4x4 matrix, Matrix4x4? prevMatrix = null, uint id = 4294967295)
```

### Parameters

**** (\[RayTracingGeometryInstanceConfig]\(/engine/6000.7/script-reference/unityengine/rendering/raytracinggeometryinstanceconfig)): The common parameters that this geometry ray tracing instance uses.**** (\[Matrix4x4]\(/engine/6000.7/script-reference/unityengine/matrix4x4)): The transformation matrix of the ray tracing instance.**** (\[Matrix4x4?]\(https\://learn.microsoft.com/dotnet/api/system.nullable)): The previous frame transformation matrix of the ray tracing instance that you can use to compute motion vectors in shader code.**** (\[uint]\(https\://learn.microsoft.com/dotnet/api/system.uint32)): An optional instance ID value that you can access with `InstanceID()` HLSL function.

### Returns

| Type                                                       | Description                                                                                                                                                                                            |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [int](https://learn.microsoft.com/dotnet/api/system.int32) | A value representing a handle that you can use to perform later actions (e.g. RemoveInstance, UpdateInstancePropertyBlock or UpdateInstanceTransform), or 0 if the instance is not added successfully. |

### Remarks

The config function argument specifies the relevant triangle geometry data (vertex and index buffers) and associated parameters.

When you have added all required instances, use [RayTracingAccelerationStructure.Build](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/build.md) or [CommandBuffer.BuildRayTracingAccelerationStructure](/engine/6000.7/script-reference/unityengine/rendering/commandbuffer/buildraytracingaccelerationstructure.md) to build the acceleration structure on the GPU.

Additional Resources: [RayTracingAccelerationStructure.RemoveInstance](/engine/6000.7/script-reference/unityengine/rendering/raytracingaccelerationstructure/removeinstance.md), [RayTracingShader.Dispatch](/engine/6000.7/script-reference/unityengine/rendering/raytracingshader/dispatch.md).