Struct DynamicBuffer<T>
An array-like data structure that can be used as a component.
Namespace: Unity.Entities
Syntax
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(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 |
---|---|
NativeArray.Enumerator<> | The enumerator. |
Examples
foreach (var element in buffer)
{
//Use element...
}
GetUnsafePtr()
Gets an langword_csharp_unsafe 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.
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;
}
});
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();