Struct DynamicBuffer<T> | Entities | 0.2.0-preview.18
docs.unity3d.com
    Show / Hide Table of Contents

    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; }
    Property Value
    Type Description
    Int32

    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);

    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);

    Reserve(Int32)

    Increases the buffer capacity without increasing its length.

    Declaration
    public void Reserve(int length)
    Parameters
    Type Name Description
    Int32 length

    The new buffer capacity.

    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.Reserve(buffer.Capacity + 10);

    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();
    Back to top Copyright © 2019 Unity Technologies
    Generated by DocFX