docs.unity3d.com
    Show / Hide Table of Contents

    Interface IJobEntityBatchWithIndex

    IJobEntityBatchWithIndex is a variant of [IJobEntityBatch] that provides an additional indexOfFirstEntityInQuery parameter, which provides a per-batch index that is the aggregate of all previous batch counts.

    Namespace: Unity.Entities
    Syntax
    public interface IJobEntityBatchWithIndex
    Remarks

    Schedule or run an IJobEntityBatchWithIndex job inside the OnUpdate() function of a SystemBase implementation. When the system schedules or runs an IJobEntityBatchWithIndex 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, Int32, 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 ScheduleParallel<T>(T, EntityQuery, Int32, JobHandle) to divide each chunk selected by your query into (approximately) equal batches of contiguous entities. For example, if you use a batch count of two, one batch provides access to the first half of the component arrays in a chunk and the other provides access to the second half. When you use batching, the ArchetypeChunk object only provides access to the components in the current batch of entities -- not those of all entities in a chunk.

    In general, processing whole chunks at a time (setting batch count to one) is the most efficient. However, in cases where the algorithm itself is relatively expensive for each entity, executing smaller batches in parallel can provide better overall performance, especially when the entities are contained in a small number of chunks. 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 IJobEntityBatchWithIndex 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.

    Methods

    Name Description
    Execute(ArchetypeChunk, Int32, 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

    JobEntityBatchIndexExtensions
    IJobEntityBatch
    Back to top
    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