Class NativeTensorArray

Represents an area of native memory that's exposed to managed code for tensor data storage.

Inheritance

object

NativeTensorArray

NativeTensorArrayFromManagedArray

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Unity.InferenceEngine

Assembly: Unity.InferenceEngine.dll

Syntax

[MovedFrom("Unity.Sentis")]
public class NativeTensorArray : IDisposable

Remarks

NativeTensorArray provides a managed wrapper around native memory allocated for tensor operations. The backing buffer stores elements as 32-bit floats (k_DataItemSize bytes per element), regardless of the logical data type.

Use this class when you need to allocate native memory for tensor data that will be used by CPU backends. For data backed by managed arrays (avoiding copies), use NativeTensorArrayFromManagedArray instead.

The class implements IDisposable. Call Dispose() when you no longer need the array to release native resources. Accessing RawPtr or other members after disposal throws InvalidOperationException.

Use Get<T>(int) and Set<T>(int, T) for individual element access. Use the static Copy(NativeTensorArray, int, NativeTensorArray, int, int) and BlockCopy(NativeTensorArray, int, byte[], int, int) methods to transfer data in bulk between NativeTensorArray instances and managed arrays.

Additional resources

Examples

// Allocate native memory for 1024 float elements
var tensorArray = new NativeTensorArray(1024);
// Set and get values
tensorArray.Set(0, 1.0f);
float value = tensorArray.Get<float>(0);
// Copy to managed array
float[] floatArray = tensorArray.ToArray<float>(1024, 0);
// Dispose of the native memory
tensorArray.Dispose();

Constructors

NativeTensorArray(int, bool, Allocator)

Initializes and returns an instance of NativeTensorArray with a given length.

Declaration

public NativeTensorArray(int length, bool clearOnInit = false, Allocator allocator = Allocator.Persistent)

Parameters

Type	Name	Description
int	length	The number of elements to allocate.
bool	clearOnInit	Whether to zero the data after allocating. The default value is `false`.
Allocator	allocator	The allocation type to use. The default value is Persistent.

Remarks

Allocates native memory for length elements (each k_DataItemSize bytes). Use clearOnInit to zero-initialize the buffer. The default allocator is Persistent, which survives across frames.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the allocator is not valid.
ArgumentOutOfRangeException	Thrown when length is less than or equal to zero.

NativeTensorArray(SafeHandle, int)

Initializes and returns an instance of NativeTensorArray with a preexisting handle.

Declaration

protected NativeTensorArray(SafeHandle safeHandle, int dataLength)

Parameters

Type	Name	Description
SafeHandle	safeHandle	The safe handle to the data.
int	dataLength	The number of elements.

Remarks

Use this constructor when creating derived types that wrap existing memory (for example, pinned managed arrays). The caller is responsible for ensuring the handle remains valid for the lifetime of the array.

Fields

k_DataItemSize

Size in bytes of an individual element.

Declaration

public const int k_DataItemSize = 4

Field Value

Type	Description
int

Remarks

The backing buffer stores elements as 32-bit floats. Note: Generic methods use sizeof(T) for indexing instead.

Properties

Disposed

Whether the backing data has been disposed.

Declaration

public bool Disposed { get; }

Property Value

Type	Description
bool

Remarks

When true, accessing RawPtr or performing operations throws InvalidOperationException.

Length

The number of allocated elements in the backing buffer.

Declaration

public int Length { get; }

Property Value

Type	Description
int

Remarks

The total size in bytes is Length * k_DataItemSize.

RawPtr

The raw pointer of the backing data.

Declaration

public virtual void* RawPtr { get; }

Property Value

Type	Description
void*

Remarks

Returns a pointer to the first element. Throws InvalidOperationException if the array has been disposed.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has been disposed.

Methods

AddressAt<T>(long)

Returns the raw pointer of the backing data at a given index.

Declaration

public T* AddressAt<T>(long index) where T : unmanaged

Parameters

Type	Name	Description
long	index	The index of the element.

Returns

Type	Description
T*	The raw pointer to the element in the data.

Type Parameters

Name	Description
T	The type of the element.

Remarks

Computes the address of the element at index as a pointer to type T. Use for low-level access when Get<T>(int) or Set<T>(int, T) are insufficient.

Examples

using (var tensorArray = new NativeTensorArray(64))
{
    unsafe
    {
        float* ptr = tensorArray.AddressAt<float>(0);
        *ptr = 3.14f;
    }
}

AsReadOnlyNativeArray<T>(int, int)

Returns the data as a NativeArray constrained to read only operations.

Declaration

public NativeArray<T>.ReadOnly AsReadOnlyNativeArray<T>(int dstCount, int srcOffset = 0) where T : unmanaged

Parameters

Type	Name	Description
int	dstCount	The number of elements.
int	srcOffset	The index of the first element. Defaults to `0`.

Returns

Type	Description
NativeArray<T>.ReadOnly	The read only native array of the data.

Type Parameters

Name	Description
T	The type of the data.

Remarks

Creates a read-only view over a slice of the backing memory. Use for passing data to jobs or APIs that require read-only access.

Examples

Get a read-only view over a slice for use with jobs or read-only APIs.

using (var tensorArray = new NativeTensorArray(64))
{
    tensorArray.Set(0, 1.0f);
    NativeArray<float>.ReadOnly readOnly = tensorArray.AsReadOnlyNativeArray<float>(64, 0);
    // Pass readOnly to jobs that require read-only access
}

AsReadOnlySpan<T>(int, int)

Returns the data as a ReadOnlySpan<T>.

Declaration

public ReadOnlySpan<T> AsReadOnlySpan<T>(int dstCount, int srcOffset = 0) where T : unmanaged

Parameters

Type	Name	Description
int	dstCount	The number of elements.
int	srcOffset	The index of the first element. Defaults to `0`.

Returns

Type	Description
ReadOnlySpan<T>	The span of the data.

Type Parameters

Name	Description
T	The type of the data.

Remarks

Creates a read-only span over a slice of the backing memory. Use for passing data to APIs that accept spans.

Examples

Get a read-only span over a slice for use with .NET span APIs.

using (var tensorArray = new NativeTensorArray(64))
{
    tensorArray.Set(0, 1.0f);
    ReadOnlySpan<float> span = tensorArray.AsReadOnlySpan<float>(64, 0);
    // Pass span to .NET APIs that accept ReadOnlySpan
}

BlockCopy(byte[], int, NativeTensorArray, int, int)

Copies the data from a source byte array to a destination NativeTensorArray up to a given length starting from given offsets.

Declaration

public static void BlockCopy(byte[] src, int srcByteIndex, NativeTensorArray dst, int dstByteIndex, int lengthInBytes)

Parameters

Type	Name	Description
byte[]	src	The array to copy from.
int	srcByteIndex	The offset to copy from.
NativeTensorArray	dst	The array to copy to.
int	dstByteIndex	The offset to copy to in the destination array.
int	lengthInBytes	The number of bytes to copy.

Remarks

Performs a raw byte copy. Use when you need to transfer a specific byte range without element-type conversion. Offsets and length are in bytes.

Examples

Copy a raw byte range from a byte array into a tensor buffer.

byte[] src = new byte[256];
using (var dst = new NativeTensorArray(64))
{
    NativeTensorArray.BlockCopy(src, 0, dst, 0, 256);
}

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

BlockCopy(NativeTensorArray, int, byte[], int, int)

Copies the data from a source NativeTensorArray to a destination byte array up to a given length starting from given offsets.

Declaration

public static void BlockCopy(NativeTensorArray src, int srcByteIndex, byte[] dst, int dstByteIndex, int lengthInBytes)

Parameters

Type	Name	Description
NativeTensorArray	src	The array to copy from.
int	srcByteIndex	The offset of the first element to copy from.
byte[]	dst	The array to copy to.
int	dstByteIndex	The offset to copy to in the destination array.
int	lengthInBytes	The number of bytes to copy.

Remarks

Performs a raw byte copy. Use when you need to transfer a specific byte range without element-type conversion. Offsets and length are in bytes.

Examples

Copy a raw byte range from a tensor buffer to a byte array.

using (var src = new NativeTensorArray(64))
{
    src.Set(0, 1.0f);
    byte[] dst = new byte[256];
    NativeTensorArray.BlockCopy(src, 0, dst, 0, 256);
}

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

Copy(NativeTensorArray, int, NativeTensorArray, int, int)

Copies the data from a source NativeTensorArray to a destination NativeTensorArray up to a given length starting from given indexes.

Declaration

public static void Copy(NativeTensorArray src, int srcIndex, NativeTensorArray dst, int dstIndex, int length)

Parameters

Type	Name	Description
NativeTensorArray	src	The array to copy from.
int	srcIndex	The index of the first element to copy from.
NativeTensorArray	dst	The array to copy to.
int	dstIndex	The index of the first element to copy to.
int	length	The number of elements.

Remarks

Performs a byte-level copy. Both source and destination use k_DataItemSize bytes per element.

Examples

Copy elements between two NativeTensorArray instances.

using (var src = new NativeTensorArray(100))
using (var dst = new NativeTensorArray(100))
{
    NativeTensorArray.Copy(src, 0, dst, 0, 100);
}

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

Copy<T>(NativeArray<T>, int, NativeTensorArray, int, int)

Copies the data from a source NativeArray_1 to a destination NativeTensorArray up to a given length starting from given indexes.

Declaration

public static void Copy<T>(NativeArray<T> src, int srcIndex, NativeTensorArray dst, int dstIndex, int length) where T : unmanaged

Parameters

Type	Name	Description
NativeArray<T>	src	The array to copy from.
int	srcIndex	The index of the first element to copy from.
NativeTensorArray	dst	The array to copy to.
int	dstIndex	The index of the first element to copy to.
int	length	The number of elements.

Type Parameters

Name	Description
T	The data type of the elements.

Remarks

The source uses sizeof(T) bytes per element. The destination uses k_DataItemSize. Use when uploading job output or other NativeArray data into a tensor buffer.

Examples

Upload NativeArray data into a tensor buffer.

var src = new NativeArray<float>(new[] { 1.0f, 2.0f, 3.0f }, Allocator.Temp);
using (var dst = new NativeTensorArray(64))
{
    NativeTensorArray.Copy(src, 0, dst, 0, 3);
}
src.Dispose();

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

Copy<T>(ReadOnly, int, NativeTensorArray, int, int)

Copies the data from a source read-only NativeArray_1 to a destination NativeTensorArray up to a given length starting from given indexes.

Declaration

public static void Copy<T>(NativeArray<T>.ReadOnly src, int srcIndex, NativeTensorArray dst, int dstIndex, int length) where T : unmanaged

Parameters

Type	Name	Description
NativeArray<T>.ReadOnly	src	The array to copy from.
int	srcIndex	The index of the first element to copy from.
NativeTensorArray	dst	The array to copy to.
int	dstIndex	The index of the first element to copy to.
int	length	The number of elements.

Type Parameters

Name	Description
T	The data type of the elements.

Remarks

The source uses sizeof(T) bytes per element. The destination uses k_DataItemSize. Use when uploading read-only job output into a tensor buffer.

Examples

Upload read-only NativeArray data into a tensor buffer.

var src = new NativeArray<float>(new[] { 1.0f, 2.0f, 3.0f }, Allocator.Temp);
using (var dst = new NativeTensorArray(64))
{
    NativeTensorArray.Copy(src.AsReadOnly(), 0, dst, 0, 3);
}
src.Dispose();

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

Copy<T>(NativeTensorArray, int, NativeArray<T>, int, int)

Copies the data from a source NativeTensorArray to a destination NativeArray_1 up to a given length starting from given indexes.

Declaration

public static void Copy<T>(NativeTensorArray src, int srcIndex, NativeArray<T> dst, int dstIndex, int length) where T : unmanaged

Parameters

Type	Name	Description
NativeTensorArray	src	The array to copy from.
int	srcIndex	The index of the first element to copy from.
NativeArray<T>	dst	The array to copy to.
int	dstIndex	The index of the first element to copy to.
int	length	The number of elements.

Type Parameters

Name	Description
T	The data type of the elements.

Remarks

The source uses k_DataItemSize bytes per element. The destination uses sizeof(T). Use when transferring tensor data to a NativeArray for use with Unity Jobs.

Examples

Copy tensor data to a NativeArray to use with Unity Jobs.

using (var src = new NativeTensorArray(64))
{
    src.Set(0, 1.0f);
    var dst = new NativeArray<float>(64, Allocator.Temp);
    NativeTensorArray.Copy(src, 0, dst, 0, 64);
    dst.Dispose();
}

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

Copy<T>(NativeTensorArray, int, T[], int, int)

Copies the data from a source NativeTensorArray to a destination managed array up to a given length starting from given indexes.

Declaration

public static void Copy<T>(NativeTensorArray src, int srcIndex, T[] dst, int dstIndex, int length) where T : unmanaged

Parameters

Type	Name	Description
NativeTensorArray	src	The array to copy from.
int	srcIndex	The index of the first element to copy from.
T[]	dst	The array to copy to.
int	dstIndex	The index of the first element to copy to.
int	length	The number of elements.

Type Parameters

Name	Description
T	The data type of the elements.

Remarks

The source uses k_DataItemSize bytes per element. The destination uses sizeof(T). Use when transferring tensor data to a managed array for interoperability.

Examples

Copy tensor data to a managed array.

using (var src = new NativeTensorArray(64))
{
    src.Set(0, 1.0f);
    float[] dst = new float[64];
    NativeTensorArray.Copy(src, 0, dst, 0, 64);
}

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

Copy<T>(T[], int, NativeTensorArray, int, int)

Copies the data from a source managed array to a destination NativeTensorArray up to a given length starting from given indexes.

Declaration

public static void Copy<T>(T[] src, int srcIndex, NativeTensorArray dst, int dstIndex, int length) where T : unmanaged

Parameters

Type	Name	Description
T[]	src	The array to copy from.
int	srcIndex	The index of the first element to copy from.
NativeTensorArray	dst	The array to copy to.
int	dstIndex	The index of the first element to copy to.
int	length	The number of elements.

Type Parameters

Name	Description
T	The data type of the elements.

Remarks

The source uses sizeof(T) bytes per element. The destination uses k_DataItemSize. Use when uploading managed data into a tensor buffer.

Examples

Upload managed array data into a tensor buffer.

float[] src = { 1.0f, 2.0f, 3.0f };
using (var dst = new NativeTensorArray(64))
{
    NativeTensorArray.Copy(src, 0, dst, 0, 3);
}

Exceptions

Type	Condition
ArgumentException	Thrown if the given indexes and length are out of bounds of the source or destination array.
ArgumentOutOfRangeException	Thrown when indexes or length are invalid.

Dispose()

Disposes of the array and any associated memory.

Declaration

public virtual void Dispose()

Remarks

Releases the native memory backing the array. Once disposed, Disposed returns true, and any access to RawPtr or other members throws InvalidOperationException.

Examples

Use a using block to ensure Dispose is called when finished.

using (var tensorArray = new NativeTensorArray(64))
{
    tensorArray.Set(0, 1.0f);
    // Dispose is called automatically when the using block exits.
}

GetNativeArrayHandle<T>()

Returns the data converted to a NativeArray.

Declaration

public NativeArray<T> GetNativeArrayHandle<T>() where T : unmanaged

Returns

Type	Description
NativeArray<T>	The converted native array from data.

Type Parameters

Name	Description
T	The type of the data.

Remarks

Creates a view over the backing memory without copying. The returned array shares the same allocator and lifetime as this instance. Do not use the returned array after this instance is disposed.

Examples

using (var tensorArray = new NativeTensorArray(64))
{
    NativeArray<float> nativeArray = tensorArray.GetNativeArrayHandle<float>();
    // Use nativeArray with Unity Jobs or other NativeArray APIs
}

Get<T>(int)

Returns the value of the backing data at a given index.

Declaration

public T Get<T>(int index) where T : unmanaged

Parameters

Type	Name	Description
int	index	The index of the element.

Returns

Type	Description
T	The value of the element at `index`, read as type `T`.

Type Parameters

Name	Description
T	The type of the element.

Remarks

Uses sizeof(T) for byte-offset indexing. For correct behavior, use T such that sizeof(T) == k_DataItemSize (for example, float or int), since the backing buffer stores elements as 32-bit floats.

Examples

using (var tensorArray = new NativeTensorArray(64))
{
    tensorArray.Set(0, 42.0f);
    float value = tensorArray.Get<float>(0); // Returns 42.0f
}

Set<T>(int, T)

Sets the value of the backing data at a given index.

Declaration

public void Set<T>(int index, T value) where T : unmanaged

Parameters

Type	Name	Description
int	index	The index of the element.
T	value	The value to set at the index.

Type Parameters

Name	Description
T	The type of the element.

Remarks

Examples

using (var tensorArray = new NativeTensorArray(64))
{
    tensorArray.Set(0, 1.0f);
    tensorArray.Set(1, 2.0f);
}

ToArray<T>(int, int)

Returns the data as an array.

Declaration

public T[] ToArray<T>(int dstCount, int srcOffset = 0) where T : unmanaged

Parameters

Type	Name	Description
int	dstCount	The number of elements.
int	srcOffset	The index of the first element. Defaults to `0`.

Returns

Type	Description
T[]	The copied array of the data.

Type Parameters

Name	Description
T	The type of the data.

Remarks

Allocates a new managed array and copies the specified slice of data.

Examples

using (var tensorArray = new NativeTensorArray(64))
{
    tensorArray.Set(0, 1.0f);
    float[] managedArray = tensorArray.ToArray<float>(64, 0);
}

ZeroMemory()

Clears the allocated memory to zero.

Declaration

public void ZeroMemory()

Remarks

Fills the entire backing buffer with zeros.

Examples

using (var tensorArray = new NativeTensorArray(256))
{
    // Clear before use to ensure deterministic behavior
    tensorArray.ZeroMemory();
}

Implements

IDisposable