docs.unity3d.com
    Show / Hide Table of Contents

    Interface IJobEntityBatch

    IJobEntityBatch is a type of IJob that iterates over a set of ArchetypeChunk instances, where each instance represents a contiguous batch of entities within a chunk.

    Namespace: Unity.Entities
    Syntax
    [JobProducerType(typeof(JobEntityBatchExtensions.JobEntityBatchProducer<>))]
    public interface IJobEntityBatch
    Remarks

    Schedule or run an IJobEntityBatch job inside the OnUpdate() function of a SystemBase implementation. When the system schedules or runs an IJobEntityBatch job, it uses the specified EntityQuery to select a set of chunks. These selected chunks are divided into batches of entities. A batch is a contiguous set of entities, always stored in the same chunk. The job struct's Execute function is called for each batch.

    When you schedule or run the job with one of the following methods:

    • Schedule<T>(T, EntityQuery, JobHandle),
    • ScheduleParallel<T>(T, EntityQuery, JobHandle),
    • or Run<T>(T, EntityQuery)

    all the entities of each chunk are processed as a single batch. The ArchetypeChunk object passed to the Execute function of your job struct provides access to the components of all the entities in the chunk.

    Use to force each batch to contain only a single entity. This allows multiple worker threads to process the entities within a chunk concurrently, which may lead to better load balancing if the number of entities to process is relatively small and the amount of work per entity is relatively high. As always, you should profile your job to find the best arrangement for your specific application.

    To pass data to your Execute function (beyond the Execute parameters), add public fields to the IJobEntityBatch struct declaration and set those fields immediately before scheduling the job. You must always pass the component type information for any components that the job reads or writes using a field of type, ComponentTypeHandle<T>. Get this type information by calling the appropriate GetComponentTypeHandle<T>(Boolean) function for the type of component.

    For more information see Using IJobEntityBatch.

    [GenerateAuthoringComponent]
    public struct ExpensiveTarget : IComponentData
    {
       public Entity entity;
    }
    
    public partial class BatchedChaserSystem : SystemBase
    {
       private EntityQuery query; // Initialized in Oncreate()
    
       [BurstCompile]
       private struct BatchedChaserSystemJob : IJobEntityBatch
       {
           // Read-write data in the current chunk
           public ComponentTypeHandle<Translation> PositionTypeHandleAccessor;
    
           // Read-only data in the current chunk
           [ReadOnly]
           public ComponentTypeHandle<Target> TargetTypeHandleAccessor;
    
           // Read-only data stored (potentially) in other chunks
           [ReadOnly]
           //[NativeDisableParallelForRestriction]
           public ComponentDataFromEntity<LocalToWorld> EntityPositions;
    
           // Non-entity data
           public float deltaTime;
    
           public void Execute(ArchetypeChunk batchInChunk, int batchIndex)
           {
               // Within Execute(), the scope of the ArchetypeChunk is limited to the current batch.
               // For example, these NativeArrays will have Length = batchInChunk.BatchEntityCount,
               // where batchInChunk.BatchEntityCount may be less than the full chunk entity count.
               NativeArray<Translation> positions = batchInChunk.GetNativeArray<Translation>(PositionTypeHandleAccessor);
               NativeArray<Target> targets = batchInChunk.GetNativeArray<Target>(TargetTypeHandleAccessor);
    
               for (int i = 0; i < positions.Length; i++)
               {
                   Entity targetEntity = targets[i].entity;
                   float3 targetPosition = EntityPositions[targetEntity].Position;
                   float3 chaserPosition = positions[i].Value;
    
                   float3 displacement = (targetPosition - chaserPosition);
                   positions[i] = new Translation { Value = chaserPosition + displacement * deltaTime };
               }
           }
       }
    
       protected override void OnCreate()
       {
           query = this.GetEntityQuery(typeof(Translation), ComponentType.ReadOnly<Target>());
       }
    
       protected override void OnUpdate()
       {
           var job = new BatchedChaserSystemJob();
           job.PositionTypeHandleAccessor = this.GetComponentTypeHandle<Translation>(false);
           job.TargetTypeHandleAccessor = this.GetComponentTypeHandle<Target>(true);
    
           job.EntityPositions = this.GetComponentDataFromEntity<LocalToWorld>(true);
           job.deltaTime = this.Time.DeltaTime;
    
           // In cases where relatively few entities are being processed, and the processing per entity is relatively
           // expensive, using ScheduleGranularity.Entity can lead to better load balancing of work among worker threads.
           this.Dependency = job.ScheduleParallel(query, ScheduleGranularity.Entity, default, this.Dependency);
       }
    }

    If you are looking for an interface which provides the firstEntityIndex parameter, IJobEntityBatchWithIndex

    Methods

    Name Description
    Execute(ArchetypeChunk, Int32)

    Implement the Execute function to perform a unit of work on an ArchetypeChunk representing a contiguous batch of entities within a chunk.

    See Also

    JobEntityBatchExtensions
    IJobEntityBatchWithIndex
    Back to top
    Terms of use
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023