Struct DynamicBuffer<T>

An array-like data structure that can be used as a component.

Namespace: Unity.Entities

Syntax

[NativeContainer]
public struct DynamicBuffer<T> : IEnumerable<T>, IEnumerable where T : struct

Type Parameters

Name	Description
T	The data type stored in the buffer. Must be a value type.

Examples

[InternalBufferCapacity(8)]
public struct FloatBufferElement : IBufferElementData
{
    // Actual value each buffer element will store.
    public float Value;

    // The following implicit conversions are optional, but can be convenient.
    public static implicit operator float(FloatBufferElement e)
    {
        return e.Value;
    }

    public static implicit operator FloatBufferElement(float e)
    {
        return new FloatBufferElement {Value = e};
    }
}

public class DynamicBufferExample : ComponentSystem
{
    protected override void OnUpdate()
    {
        float sum = 0;

        Entities.ForEach((DynamicBuffer<FloatBufferElement> buffer) =>
        {
            foreach (var element in buffer.Reinterpret<float>())
            {
                sum += element;
            }
        });

        Debug.Log("Sum of all buffers: " + sum);
    }
}

Properties

Capacity

The number of elements the buffer can hold.

Declaration

public int Capacity { get; set; }

Property Value

Type	Description
Int32

Remarks

Capacity can not be set lower than Length - this will raise an exception. If Capacity grows greater than the internal capacity of the DynamicBuffer, memory external to the DynamicBuffer will be allocated. If Capacity shrinks to the internal capacity of the DynamicBuffer or smaller, memory external to the DynamicBuffer will be freed. No effort is made to avoid costly reallocations when Capacity changes slightly; if Capacity is incremented by 1, an array 1 element bigger is allocated.

IsCreated

Whether the memory for this dynamic buffer has been allocated.

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
Boolean

Item[Int32]

Array-like indexing operator.

Declaration

public T this[int index] { get; set; }

Parameters

Type	Name	Description
Int32	index	The zero-based index.

Property Value

Type	Description
T

Examples

        for (int i = 0; i < buffer.Length; i++)
        {
            buffer[i] = i * i;
        }

Length

The number of elements the buffer holds.

Declaration

public int Length { get; }

Property Value

Type	Description
Int32

Examples

        for (int i = 0; i < buffer.Length; i++)
        {
            buffer[i] = i * i;
        }

Methods

Add(T)

Adds an element to the end of the buffer, resizing as necessary.

Declaration

public int Add(T elem)

Parameters

Type	Name	Description
T	elem	The element to add to the buffer.

Returns

Type	Description
Int32	The new length of the buffer.

Remarks

The buffer is resized if it has no additional capacity.

Examples

        buffer.Add(5);

AddRange(NativeArray<T>)

Adds all the elements from newElems to the end of the buffer, resizing as necessary.

Declaration

public void AddRange(NativeArray<T> newElems)

Parameters

Type	Name	Description
NativeArray<T>	newElems	The native array of elements to insert.

Remarks

The buffer is resized if it has no additional capacity.

Examples

        int[] source = {1, 2, 3, 4, 5};
        NativeArray<int> newElements = new NativeArray<int>(source, Allocator.Persistent);
        buffer.AddRange(newElements);

AsNativeArray()

Return a native array that aliases the original buffer contents.

Declaration

public NativeArray<T> AsNativeArray()

Returns

Type	Description
NativeArray<T>

Remarks

You can only access the native array as long as the the buffer memory has not been reallocated. Several dynamic buffer operations, such as Add(T) and TrimExcess() can result in buffer reallocation.

Examples

        int[] intArray = {1, 2, 3, 4, 5};
        NativeArray<int>.Copy(intArray, buffer.AsNativeArray());

Clear()

Sets the buffer length to zero.

Declaration

public void Clear()

Remarks

The capacity of the buffer remains unchanged. Buffer memory is not overwritten.

Examples

        buffer.Clear();

CopyFrom(T[])

Copies all the elements from an array.

Declaration

public void CopyFrom(T[] v)

Parameters

Type	Name	Description
T[]	v	A C# array containing the elements to copy.

Examples

        int[] integerArray = {1, 2, 3, 4, 5};
        buffer.CopyFrom(integerArray);

Exceptions

Type	Condition
ArgumentNullException

CopyFrom(NativeArray<T>)

Copies all the elements from the specified native array into this dynamic buffer.

Declaration

public void CopyFrom(NativeArray<T> v)

Parameters

Type	Name	Description
NativeArray<T>	v	The native array containing the elements to copy.

Examples

        int[] sourceArray = {1, 2, 3, 4, 5};
        NativeArray<int> nativeArray = new NativeArray<int>(source, Allocator.Persistent);
        buffer.CopyFrom(nativeArray);

CopyFrom(NativeSlice<T>)

Copies all the elements from the specified native slice into this dynamic buffer.

Declaration

public void CopyFrom(NativeSlice<T> v)

Parameters

Type	Name	Description
NativeSlice<T>	v	The native slice containing the elements to copy.

Examples

        NativeSlice<int> nativeSlice = new NativeSlice<int>(nativeArray, 1, 3);
        buffer.CopyFrom(nativeSlice);

CopyFrom(DynamicBuffer<T>)

Copies all the elements from another dynamic buffer.

Declaration

public void CopyFrom(DynamicBuffer<T> v)

Parameters

Type	Name	Description
DynamicBuffer<T>	v	The dynamic buffer containing the elements to copy.

Examples

        buffer.CopyFrom(secondBuffer);

EnsureCapacity(Int32)

Ensures that the buffer has at least the specified capacity.

Declaration

public void EnsureCapacity(int length)

Parameters

Type	Name	Description
Int32	length	The buffer capacity is ensured to be at least this big.

Remarks

If length is greater than the current Capacity of this buffer and greater than the capacity reserved with InternalBufferCapacityAttribute, this function allocates a new memory block and copies the current buffer to it. The number of elements in the buffer remains unchanged.

Examples

        buffer.EnsureCapacity(buffer.Capacity + 10);

GetEnumerator()

Provides an enumerator for iterating over the buffer elements.

Declaration

public NativeArray<T>.Enumerator GetEnumerator()

Returns

Type	Description
Unity.Collections.NativeArray.Enumerator<>	The enumerator.

Examples

        foreach (var element in buffer)
        {
            //Use element...
        }

GetUnsafePtr()

Gets an unsafe read/write pointer to the contents of the buffer.

Declaration

public void *GetUnsafePtr()

Returns

Type	Description
Void*	A typed, unsafe pointer to the first element in the buffer.

Remarks

This function can only be called in unsafe code contexts.

GetUnsafeReadOnlyPtr()

Gets an unsafe read-only pointer to the contents of the buffer.

Declaration

public void *GetUnsafeReadOnlyPtr()

Returns

Type	Description
Void*	A typed, unsafe pointer to the first element in the buffer.

Remarks

This function can only be called in unsafe code contexts.

Insert(Int32, T)

Inserts an element at the specified index, resizing as necessary.

Declaration

public void Insert(int index, T elem)

Parameters

Type	Name	Description
Int32	index	The position at which to insert the new element.
T	elem	The element to add to the buffer.

Remarks

The buffer is resized if it has no additional capacity.

Examples

        if (insertionIndex < buffer.Length)
            buffer.Insert(insertionIndex, 6);

Reinterpret<U>()

Returns a dynamic buffer of a different type, pointing to the same buffer memory.

Declaration

public DynamicBuffer<U> Reinterpret<U>()
    where U : struct

Returns

Type	Description
DynamicBuffer<U>	A dynamic buffer of the reinterpreted type.

Type Parameters

Name	Description
U	The reinterpreted type.

Remarks

No memory modification occurs. The reinterpreted type must be the same size in memory as the original type.

Examples

        Entities.ForEach((DynamicBuffer<FloatBufferElement> buffer) =>
        {
            DynamicBuffer<float> floatBuffer = buffer.Reinterpret<float>();
            for (int i = 0; i < floatBuffer.Length; i++)
            {
                floatBuffer[i] = i * 1.2f;
            }
        }).ScheduleParallel();

Exceptions

Type	Condition
InvalidOperationException	If the reinterpreted type is a different size than the original.

RemoveAt(Int32)

Removes the element at the specified index.

Declaration

public void RemoveAt(int index)

Parameters

Type	Name	Description
Int32	index	The index of the element to remove.

Examples

        if (insertionIndex < buffer.Length)
            buffer.RemoveAt(insertionIndex);

RemoveRange(Int32, Int32)

Removes the specified number of elements, starting with the element at the specified index.

Declaration

public void RemoveRange(int index, int count)

Parameters

Type	Name	Description
Int32	index	The first element to remove.
Int32	count	How many elements tot remove.

Remarks

The buffer capacity remains unchanged.

Examples

        buffer.RemoveRange(start, 5);

ResizeUninitialized(Int32)

Increases the buffer capacity and length.

Declaration

public void ResizeUninitialized(int length)

Parameters

Type	Name	Description
Int32	length	The new length of the buffer.

Remarks

If length is less than the current length of the buffer, the length of the buffer is reduced while the capacity remains unchanged.

Examples

        buffer.ResizeUninitialized(buffer.Length + 10);

ToNativeArray(Allocator)

Copies the buffer into a new native array.

Declaration

public NativeArray<T> ToNativeArray(Allocator allocator)

Parameters

Type	Name	Description
Allocator	allocator	The type of memory allocation to use when creating the native array.

Returns

Type	Description
NativeArray<T>	A native array containing copies of the buffer elements.

Examples

        NativeArray<int> copy = buffer.ToNativeArray(Allocator.Persistent);

TrimExcess()

Removes any excess capacity in the buffer.

Declaration

public void TrimExcess()

Remarks

Sets the buffer capacity to the current length. If the buffer memory size changes, the current contents of the buffer are copied to a new block of memory and the old memory is freed. If the buffer now fits in the space in the chunk reserved with InternalBufferCapacityAttribute, then the buffer contents are moved to the chunk.

Examples

        if (buffer.Capacity > buffer.Length)
            buffer.TrimExcess();