To load instance data, such as transform matrices, the shaderA program that runs on the GPU. More info
See in Glossary needs to define DOTS Instanced properties. Below is an example of a simple DOTS Instanced property block:
UNITY_DOTS_INSTANCING_START(MaterialPropertyMetadata)
UNITY_DOTS_INSTANCED_PROP(float4, Color)
UNITY_DOTS_INSTANCING_END(MaterialPropertyMetadata)
To mark the beginning and end of the property block, use the UNITY_DOTS_INSTANCING_START
and UNITY_DOTS_INSTANCING_END
macros followed by the name of the block. The example uses the name MaterialPropertyMetadata
. There are three allowed block names:
The shader can declare one of each, so a DOTS Instanced shader can have between zero and three of such blocks. Unity-defined shader code doesn’t use UserPropertyMetadata so this name is guaranteed to be free for you to use. URP and HDRP define BuiltinPropertyMetadata for every shader they provide and define MaterialPropertyMetadata for most of them too, so it’s best practice to use UserPropertyMetadata. Your custom shaders can use all three possible names, even all at once.
The block can contain any number of DOTS Instanced property definitions formatted like:
UNITY_DOTS_INSTANCED_PROP(PropertyType, PropertyName)
PropertyType
can be any HLSL built-in type (like uint, float4, float4x4, or int2x4) except a bool vector, and PropertyName
is the name of the DOTS Instanced property. DOTS Instanced properties are completely separate from regular material properties, and you can give them the same name as another regular material property. This is possible because the UNITY_DOTS_INSTANCED_PROP
macro generates special constant names which Unity recognizes that don’t conflict with other property names. Shaders that Unity provides give DOTS Instanced properties the same names as regular material properties, but you don’t need to follow this convention.
Internally, Unity provides the shader with a 32-bit integer metadata value for every DOTS Instanced property the shader declares. Unity sets the metadata value when your code makes a BatchRendererGroup.AddBatch call to create the batch associated with the draw. The metadata value defaults to 0
if Unity doesn’t set it. The shader also has access to ByteAddressBuffer unity_DOTSInstanceData
which Unity sets to the GraphicsBuffer you pass as an argument to BatchRendererGroup.AddBatch
. This buffer is typically where the shader loads the instance data from. Multiple batches can share a single GraphicsBuffer, but it is also possible for each batch to use its own separate GraphicsBuffer for unity_DOTSInstanceData
.
Note: Unity doesn’t provide any DOTS Instanced data automatically. It’s your responsibility to make sure that the unity_DOTSInstanceData
buffer of each batch contains the correct data. Instance data must include many properties that are Unity normally provides for GameObjectsThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary, such as transform matrices, light probeLight probes store information about how light passes through space in your scene. A collection of light probes arranged within a given space can improve lighting on moving objects and static LOD scenery within that space. More info
See in Glossary coefficients, and lightmapA pre-rendered texture that contains the effects of light sources on static objects in the scene. Lightmaps are overlaid on top of scene geometry to create the effect of lighting. More info
See in Glossary texture coordinates.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.